/// <reference types="node" />
import { MapRef, TypeConversion } from './common';
/**
 * Generic interface to manipulate an eBPF map of any type. API-compatible
 * with JavaScript `Map`.
 *
 * In an eBPF map, keys and values are binary strings of a fixed length,
 * defined at map creation (see [[MapDef]]). [[RawMap]] returns these
 * directly as `Buffer` with no conversion, and [[ConvMap]] performs
 * the conversion specified at construction time.
 *
 * ### Operation semantics
 *
 * The exact semantics of the operations (whether they're atomic or not,
 * supported flags, etc.) depend on the chosen map type.
 *
 * If your kernel doesn't implement a map operation, it will generally
 * throw `EINVAL`. If it's implemented, but the map type doesn't
 * have it, it will generally throw `ENOTSUPP`.
 *
 * ### Convenience methods
 *
 * Some methods, such as [[clear]], are implemented using one or more
 * map operations. These are marked as convenience methods in their
 * documentation.
 *
 * Notably, **iterating methods** such as [[entries]], [[consumeEntries]],
 * [[values]] and also [[clear]] are all convenience methods, implemented
 * using a combination of [[keys]] and another operation.
 *
 * ### Batched operations
 *
 * These are special map operations that process many entries.
 * [[setBatch]] and [[deleteBatch]] are mostly equivalent to a
 * repeated [[set]] or [[delete]] on each of the entries.
 * [[getBatch]] iterates through the entries of the map
 * and is mostly equivalent to [[entries]].
 *
 * The difference is that all this is performed in the kernel
 * through a single syscall, so they perform better than normal
 * operations or iterating methods (especially when syscall overhead
 * is a problem).
 *
 * However they're much more recent and, like other operations,
 * may not be available on your map type or kernel version.
 */
export interface IMap<K, V> {
    /**
     * Fetch the value for a single key.
     *
     * @param key Entry key
     * @param flags Operation flags (since Linux 5.1), see [[MapLookupFlags]]
     * @returns Entry value, or `undefined` if no such entry exists
     * @category Operations
     */
    get(key: K, flags?: number): V | undefined;
    /**
     * Atomically deletes an entry and returns its former value,
     * or `undefined` if no entry was found. This operation is
     * generally implemented only for stack / queue types.
     *
     * Since Linux 4.20. Most map types probably won't implement
     * this operation.
     *
     * @param key Entry key
     * @category Operations
     */
    getDelete(key: K): V | undefined;
    /**
     * Add or override a single map entry.
     *
     * @param key Entry key
     * @param value Entry value
     * @param flags Operation flags (since Linux 3.19), see [[MapUpdateFlags]]
     * @category Operations
     */
    set(key: K, value: V, flags?: number): this;
    /**
     * Delete a single map entry.
     *
     * Returns `true` if an entry was found
     * and deleted, `false` otherwise.
     *
     * @param key Entry key
     * @category Operations
     */
    delete(key: K): boolean;
    /**
     * Iterate through the map entries.
     *
     * This works like [[entries]] but the iteration is performed
     * in the kernel, returning many items at once. The
     * interator yields each batch produced by the kernel, until
     * an error is found or there are no more entries.
     *
     * `batchSize` specifies the requested size, but batches may
     * be smaller. If the kernel returns a partial batch together
     * with an error, the partial batch will be yielded before
     * throwing the error. If the map is empty, nothing is yielded.
     *
     * Since Linux 5.6.
     *
     * @param batchSize Amount of entries to request per batch,
     * must be non-zero
     * @param flags Operation flags, see [[MapLookupFlags]]
     * @category Batched operations
     */
    getBatch(batchSize: number, flags?: number): IterableIterator<[K, V][]>;
    /**
     * TODO: implement this
     *
     * Since Linux 5.6. Map types may implement this operation
     * without implementing [[getDelete]], or viceversa.
     *
     * @param key Entry keys
     * @category Batched operations
     */
    /**
     * Perform [[set]] operation on the passed entries.
     *
     * Since Linux 5.6.
     *
     * Note that if an error is thrown, part of the entries
     * could already have been processed. The thrown error
     * includes a `count` field that, if not undefined,
     * corresponds to the amount of processed entries.
     *
     * @param entries Entries to set
     * @param flags Operation flags, see [[MapUpdateFlags]]
     * @category Batched operations
     */
    setBatch(entries: [K, V][], flags?: number): this;
    /**
     * Perform [[delete]] operation on the passed entries.
     *
     * Since Linux 5.6.
     *
     * Unlike in [[delete]], an entry isn't found,
     * `ENOENT` will be thrown and no more entries will
     * be processed.
     *
     * Note that if an error is thrown, part of the entries
     * could already have been processed. The thrown error
     * includes a `count` field that, if not undefined,
     * corresponds to the amount of processed entries.
     *
     * @param keys Entry keys to delete
     * @category Batched operations
     */
    deleteBatch(keys: K[]): void;
    /**
     * Non-atomically iterates through the map's keys, starting
     * by the key immediately following the passed one. If no
     * key isn't passed or it doesn't exist, iteration starts by
     * the first key in the map.
     *
     * **Note:** Not passing a key is only supported
     * on kernels 4.12 and above.
     *
     * Because this calls `BPF_MAP_GET_NEXT_KEY` repeatedly,
     * if the map's keys are deleted while it's being iterated
     * (by this or another program), iteration could restart to
     * the beginning. However, this method fetches the next key
     * *before* yielding the current one, making it safe to delete
     * the current key (and any past ones).
     *
     * Keep in mind that the order of keys depends on the
     * type of map, and isn't necessarily guaranteed to be
     * consistent.
     *
     * @param start Start key (if passed and found, iteration
     * will yield keys *after* this one, i.e. it's not included
     * in the result)
     * @category Operations
     */
    keys(start?: K): Generator<K, undefined>;
    /**
     * Freezes the map, making it non-modifiable from userspace.
     * The map stays writeable from BPF side.
     *
     * Since Linux 5.2.
     *
     * @category Operations
     */
    freeze(): void;
    /**
     * Convenience function. Tests if the map has an entry.
     *
     * @param key Entry key
     * @category Convenience
     */
    has(key: K): boolean;
    /**
     * Convenience function. Non-atomically iterates through the map's entries.
     * Gets the next key *before* yielding the current one, making it
     * suitable for deleting entries while iterating.
     *
     * **Note:** For kernels older than 4.12, a start key must be passed.
     * See [[keys]].
     *
     * This is a wrapper around [[keys]] and [[get]].
     *
     * @category Convenience
     */
    entries(start?: K): IterableIterator<[K, V]>;
    /**
     * Convenience function. Non-atomically iterates through the map's values.
     *
     * **Note:** For kernels older than 4.12, a start key must be passed.
     * See [[keys]].
     *
     * This is a wrapper around [[keys]] and [[get]].
     *
     * @category Convenience
     */
    values(start?: K): IterableIterator<V>;
    /**
     * Convenience function. Non-atomically iterates through the map's entries,
     * deleting them while iterating.
     *
     * This is a wrapper around [[keys]] and [[getDelete]].
     *
     * @category Convenience
     */
    consumeEntries(start?: K): IterableIterator<[K, V]>;
    /**
     * Convenience function. Non-atomically iterates over the map's entries,
     * deleting them.
     *
     * **Note:** For kernels older than 4.12, a start key must be passed.
     * See [[keys]].
     *
     * This is a wrapper around [[keys]] and [[delete]].
     *
     * @category Convenience
     */
    clear(start?: K): void;
    /**
     * Convenience function. Alias of [[entries]].
     *
     * @category Convenience
     */
    [Symbol.iterator](): IterableIterator<[K, V]>;
}
/**
 * Raw version of the [[IMap]] interface where keys and values
 * are returned directly as `Buffer`s.
 */
export declare class RawMap implements IMap<Buffer, Buffer> {
    readonly ref: MapRef;
    /**
     * Construct a new instance operating on the given map.
     *
     * @param ref Reference to the map. See [[MapRef]] if
     * you want to implement your own instances.
     */
    constructor(ref: MapRef);
    private _checkBuf;
    private _getBuf;
    private _kBuf;
    private _vBuf;
    private _kOrBuf;
    private _vOrBuf;
    get(key: Buffer, flags?: number, out?: Buffer): Buffer | undefined;
    getDelete(key: Buffer, out?: Buffer): Buffer | undefined;
    set(key: Buffer, value: Buffer, flags?: number): this;
    delete(key: Buffer): boolean;
    getBatch(batchSize: number, flags?: number): IterableIterator<[Buffer, Buffer][]>;
    setBatch(entries: [Buffer, Buffer][], flags?: number): this;
    deleteBatch(keys: Buffer[]): void;
    keys(start?: Buffer): Generator<Buffer, undefined>;
    getNextKey(key?: Buffer, out?: Buffer): Buffer | undefined;
    freeze(): void;
    has(key: Buffer): boolean;
    entries(start?: Buffer): IterableIterator<[Buffer, Buffer]>;
    values(start?: Buffer): IterableIterator<Buffer>;
    consumeEntries(start?: Buffer): IterableIterator<[Buffer, Buffer]>;
    clear(start?: Buffer): void;
    [Symbol.iterator](): IterableIterator<[Buffer, Buffer]>;
}
/**
 * Implementation of [[IMap]] that converts keys and values
 * to 'parsed' representations using the given [[TypeConversion]].
 */
export declare class ConvMap<K, V> implements IMap<K, V> {
    private readonly map;
    private readonly keyConv;
    private readonly valueConv;
    get ref(): MapRef;
    /**
     * Construct a new instance operating on the given map.
     *
     * @param ref Reference to the map. See [[MapRef]] if
     * you want to implement your own instances.
     * @param keyConv Type conversion for keys
     * @param valueConv Type conversion for values
     */
    constructor(ref: MapRef, keyConv: TypeConversion<K>, valueConv: TypeConversion<V>);
    get(key: K, flags?: number): V | undefined;
    getDelete(key: K): V | undefined;
    set(key: K, value: V, flags?: number): this;
    delete(key: K): boolean;
    getBatch(batchSize: number, flags?: number): IterableIterator<[K, V][]>;
    setBatch(entries: [K, V][], flags?: number): this;
    deleteBatch(keys: K[]): void;
    keys(start?: K): Generator<K, undefined>;
    freeze(): void;
    has(key: K): boolean;
    entries(start?: K): IterableIterator<[K, V]>;
    values(start?: K): IterableIterator<V>;
    consumeEntries(start?: K): IterableIterator<[K, V]>;
    clear(start?: K): void;
    [Symbol.iterator](): IterableIterator<[K, V]>;
}