BPF map operations and abstractions
BPF map operations and abstractions
(add-inner-map mim key)Add a new inner map at the specified index/key.
Creates a new inner map matching the template and registers it in the outer map at the given location.
Parameters:
Returns the newly created inner BpfMap.
Add a new inner map at the specified index/key. Creates a new inner map matching the template and registers it in the outer map at the given location. Parameters: - mim: MapInMap record - key: Index (for array-of-maps) or key (for hash-of-maps) Returns the newly created inner BpfMap.
(assoc-map! bpf-map key value)Associate key-value pair in BPF map (mutable operation)
Associate key-value pair in BPF map (mutable operation)
(bloom-add bloom-map value)Add an element to a bloom filter.
Parameters:
Add an element to a bloom filter. Parameters: - bloom-map: Bloom filter map - value: Value bytes to add (must match value-size)
(bloom-check bloom-map value)Check if an element might be in the bloom filter.
Returns:
Parameters:
Check if an element might be in the bloom filter. Returns: - true: Element might be in the set (could be false positive) - false: Element is definitely not in the set Parameters: - bloom-map: Bloom filter map - value: Value bytes to check
(close-map-in-map mim)Close a map-in-map structure and all its inner maps.
Parameters:
Close a map-in-map structure and all its inner maps. Parameters: - mim: MapInMap record
(create-array-map max-entries
&
{:keys [value-size map-name] :or {value-size 4}})Create an array map (array-indexed) Keys are 0-based indices
Create an array map (array-indexed) Keys are 0-based indices
(create-bloom-filter max-entries value-size & {:keys [map-name nr-hash-funcs]})Create a bloom filter map.
Bloom filters are space-efficient probabilistic data structures used for membership testing. They may return false positives but never false negatives.
Parameters:
Options:
Example: (def bloom (create-bloom-filter 10000 4)) (bloom-add bloom (hash-bytes some-data)) (bloom-check bloom (hash-bytes some-data)) ; => true or false
Create a bloom filter map. Bloom filters are space-efficient probabilistic data structures used for membership testing. They may return false positives but never false negatives. Parameters: - max-entries: Number of entries (affects false positive rate) - value-size: Size of values to store (typically hash size) Options: - :map-name - Name for the map - :nr-hash-funcs - Number of hash functions (default: kernel decides) Example: (def bloom (create-bloom-filter 10000 4)) (bloom-add bloom (hash-bytes some-data)) (bloom-check bloom (hash-bytes some-data)) ; => true or false
(create-hash-map max-entries
&
{:keys [key-size value-size map-name]
:or {key-size 4 value-size 4}})Create a hash map with integer keys and values
Create a hash map with integer keys and values
(create-lpm-trie-map max-entries
&
{:keys [key-size value-size map-name]
:or {key-size 8 value-size 4}})Create an LPM (Longest Prefix Match) trie map
LPM trie maps are specialized for longest prefix matching, commonly used for IP routing tables and CIDR block lookups.
Parameters:
Optional keyword arguments:
Example key structure for IPv4:
Note: Keys must include prefix length as first 4 bytes.
Create an LPM (Longest Prefix Match) trie map
LPM trie maps are specialized for longest prefix matching, commonly used
for IP routing tables and CIDR block lookups.
Parameters:
- max-entries: Maximum number of prefixes
Optional keyword arguments:
- :key-size - Size of key in bytes including prefix length (default: 8)
First 4 bytes are prefix length, rest is the prefix data
- :value-size - Size of value in bytes (default: 4)
- :map-name - Name for the map
- :map-flags - Must include BPF_F_NO_PREALLOC for LPM tries
Example key structure for IPv4:
- Bytes 0-3: Prefix length (32 bits)
- Bytes 4-7: IPv4 address (32 bits)
Note: Keys must include prefix length as first 4 bytes.(create-lru-hash-map max-entries
&
{:keys [key-size value-size map-name]
:or {key-size 4 value-size 4}})Create an LRU (Least Recently Used) hash map with integer keys and values
LRU maps automatically evict the least recently used entries when full, making them ideal for caching scenarios.
Parameters:
Optional keyword arguments:
Create an LRU (Least Recently Used) hash map with integer keys and values LRU maps automatically evict the least recently used entries when full, making them ideal for caching scenarios. Parameters: - max-entries: Maximum number of entries (also the LRU cache size) Optional keyword arguments: - :key-size - Size of key in bytes (default: 4) - :value-size - Size of value in bytes (default: 4) - :map-name - Name for the map
(create-lru-percpu-hash-map max-entries
&
{:keys [key-size value-size map-name]
:or {key-size 4 value-size 4}})Create a per-CPU LRU hash map with integer keys and values
Like LRU hash maps, but each CPU has its own separate LRU cache, providing better performance for multi-core systems.
Parameters:
Optional keyword arguments:
Create a per-CPU LRU hash map with integer keys and values Like LRU hash maps, but each CPU has its own separate LRU cache, providing better performance for multi-core systems. Parameters: - max-entries: Maximum number of entries per CPU Optional keyword arguments: - :key-size - Size of key in bytes (default: 4) - :value-size - Size of value in bytes per CPU (default: 4) - :map-name - Name for the map
(create-map {:keys [map-type key-size value-size max-entries map-flags map-name
key-serializer key-deserializer value-serializer
value-deserializer inner-map-fd numa-node map-ifindex btf-fd
btf-key-type-id btf-value-type-id btf-vmlinux-value-type-id
map-extra percpu? percpu-value-size]
:or {map-flags 0
key-serializer identity
key-deserializer identity
value-serializer identity
value-deserializer identity
percpu? false
percpu-value-size nil}})Create a new BPF map
Options:
Create a new BPF map Options: - :map-type - Type of map (:hash, :array, :ringbuf, etc.) - :key-size - Size of key in bytes - :value-size - Size of value in bytes - :max-entries - Maximum number of entries - :map-flags - Optional flags (default 0) - :map-name - Optional name - :key-serializer - Optional function to convert key to bytes - :key-deserializer - Optional function to convert bytes to key - :value-serializer - Optional function to convert value to bytes - :value-deserializer - Optional function to convert bytes to value
(create-map-in-map outer-type
max-entries
inner-spec
&
{:keys [outer-key-size name] :or {name "map_in_map"}})Create a map-in-map structure (outer map containing inner maps).
Map-in-map allows dynamic creation of inner maps at runtime, useful for per-entity data structures or hierarchical configs.
Parameters:
Options:
Returns a MapInMap record.
Example: ;; Create array of hash maps (e.g., per-CPU connection tables) (create-map-in-map :array-of-maps 64 {:map-type :hash :key-size 16 ; Connection tuple :value-size 32 ; Connection state :max-entries 1024} :name "conn_table")
Create a map-in-map structure (outer map containing inner maps).
Map-in-map allows dynamic creation of inner maps at runtime,
useful for per-entity data structures or hierarchical configs.
Parameters:
- outer-type: :array-of-maps or :hash-of-maps
- max-entries: Maximum entries in outer map
- inner-spec: Specification for inner maps (same as create-map options)
Options:
- :outer-key-size - Key size for outer map (default: 4 for array, required for hash)
- :name - Name prefix for maps
Returns a MapInMap record.
Example:
;; Create array of hash maps (e.g., per-CPU connection tables)
(create-map-in-map
:array-of-maps 64
{:map-type :hash
:key-size 16 ; Connection tuple
:value-size 32 ; Connection state
:max-entries 1024}
:name "conn_table")(create-percpu-array-map max-entries
&
{:keys [value-size map-name] :or {value-size 4}})Create a per-CPU array map
Like array maps but each CPU has its own independent values. Array keys are indices from 0 to (max-entries - 1). Lookups return vectors of values.
Parameters:
Optional keyword arguments:
Create a per-CPU array map Like array maps but each CPU has its own independent values. Array keys are indices from 0 to (max-entries - 1). Lookups return vectors of values. Parameters: - max-entries: Number of array entries (keys are 0 to max-entries-1) Optional keyword arguments: - :value-size - Size of value in bytes per CPU (default: 4) - :map-name - Name for the map
(create-percpu-hash-map max-entries
&
{:keys [key-size value-size map-name]
:or {key-size 4 value-size 4}})Create a per-CPU hash map with integer keys
Each CPU core has its own independent value for each key, eliminating contention between CPUs. Lookups return a vector of values (one per CPU).
Parameters:
Optional keyword arguments:
Note: The actual value size in the kernel is (value-size * num-cpus)
Create a per-CPU hash map with integer keys Each CPU core has its own independent value for each key, eliminating contention between CPUs. Lookups return a vector of values (one per CPU). Parameters: - max-entries: Maximum number of entries Optional keyword arguments: - :key-size - Size of key in bytes (default: 4) - :value-size - Size of value in bytes per CPU (default: 4) - :map-name - Name for the map Note: The actual value size in the kernel is (value-size * num-cpus)
(create-queue-map max-entries
&
{:keys [value-size map-name] :or {value-size 4}})Create a queue (FIFO) map
Queue maps provide First-In-First-Out semantics. Values are pushed and popped without explicit keys. Useful for work queues or message passing.
Parameters:
Optional keyword arguments:
Operations:
Note: Queue maps use special operations, not standard key-value operations.
Create a queue (FIFO) map Queue maps provide First-In-First-Out semantics. Values are pushed and popped without explicit keys. Useful for work queues or message passing. Parameters: - max-entries: Maximum number of entries in the queue Optional keyword arguments: - :value-size - Size of value in bytes (default: 4) - :map-name - Name for the map Operations: - Push: Use map-update with nil key - Pop: Use special stack/queue operations (not standard map-lookup) - Peek: Look at front without removing Note: Queue maps use special operations, not standard key-value operations.
(create-ringbuf-map max-entries & {:keys [map-name]})Create a ring buffer map max-entries must be a power of 2 and page-aligned
Create a ring buffer map max-entries must be a power of 2 and page-aligned
(create-stack-map max-entries
&
{:keys [value-size map-name] :or {value-size 4}})Create a stack (LIFO) map
Stack maps provide Last-In-First-Out semantics. Values are pushed and popped without explicit keys. Useful for maintaining call stacks or LIFO queues.
Parameters:
Optional keyword arguments:
Operations:
Note: Stack maps use special operations, not standard key-value operations.
Create a stack (LIFO) map Stack maps provide Last-In-First-Out semantics. Values are pushed and popped without explicit keys. Useful for maintaining call stacks or LIFO queues. Parameters: - max-entries: Maximum number of entries in the stack Optional keyword arguments: - :value-size - Size of value in bytes (default: 4) - :map-name - Name for the map Operations: - Push: Use map-update with nil key - Pop: Use special stack/queue operations (not standard map-lookup) - Peek: Look at top without removing Note: Stack maps use special operations, not standard key-value operations.
(dissoc-map! bpf-map key)Dissociate key from BPF map (mutable operation)
Dissociate key from BPF map (mutable operation)
(dump-map bpf-map)Dump all entries in map for debugging
Dump all entries in map for debugging
(get-inner-map mim key)Get the inner map at the specified index/key.
Returns the BpfMap if it exists in our tracking, or nil.
Get the inner map at the specified index/key. Returns the BpfMap if it exists in our tracking, or nil.
(get-map bpf-map key)(get-map bpf-map key default)Get value from BPF map, with optional default
Get value from BPF map, with optional default
(get-pinned-map path
{:keys [map-type key-size value-size max-entries map-flags
map-name key-serializer key-deserializer
value-serializer value-deserializer]
:or {map-flags 0
key-serializer identity
key-deserializer identity
value-serializer identity
value-deserializer identity}})Get a pinned map from BPF filesystem You must provide the map metadata (type, key-size, value-size, etc.)
Get a pinned map from BPF filesystem You must provide the map metadata (type, key-size, value-size, etc.)
(inner-map-count mim)Get the number of inner maps currently registered.
Get the number of inner maps currently registered.
(inner-map-keys mim)Get all keys that have inner maps registered.
Get all keys that have inner maps registered.
(inner-map-lookup mim outer-key inner-key)Look up a value in an inner map.
Convenience function for nested lookup.
Parameters:
Returns the value or nil if not found.
Look up a value in an inner map. Convenience function for nested lookup. Parameters: - mim: MapInMap record - outer-key: Key for outer map - inner-key: Key for inner map Returns the value or nil if not found.
(inner-map-update mim outer-key inner-key value)Update a value in an inner map.
Convenience function for nested update. Creates the inner map if it doesn't exist.
Parameters:
Update a value in an inner map. Convenience function for nested update. Creates the inner map if it doesn't exist. Parameters: - mim: MapInMap record - outer-key: Key for outer map - inner-key: Key for inner map - value: Value to store
(into-clj-map bpf-map)Convert BPF map entries into a Clojure persistent map.
Caution: This loads all entries into memory. Only use for maps you know are small enough to fit.
Parameters:
Returns a Clojure map with all entries.
Convert BPF map entries into a Clojure persistent map. Caution: This loads all entries into memory. Only use for maps you know are small enough to fit. Parameters: - bpf-map: The BPF map Returns a Clojure map with all entries.
(map-clear bpf-map)Delete all entries from map
Delete all entries from map
(map-count bpf-map)Count number of entries in map.
Note: This iterates through all keys, which can be slow for large maps. Consider using a separate counter if you need frequent count queries.
Count number of entries in map. Note: This iterates through all keys, which can be slow for large maps. Consider using a separate counter if you need frequent count queries.
(map-delete bpf-map key)Delete entry by key from map
Delete entry by key from map
(map-delete-batch bpf-map keys)Batch delete multiple keys from map
Parameters:
Returns the number of keys successfully deleted.
Batch delete multiple keys from map Parameters: - bpf-map: BpfMap instance - keys: Sequence of keys to delete Returns the number of keys successfully deleted.
(map-empty? bpf-map)Check if a BPF map has no entries.
Returns true if the map has no entries, false otherwise. Returns nil if the map doesn't exist or is inaccessible.
Check if a BPF map has no entries. Returns true if the map has no entries, false otherwise. Returns nil if the map doesn't exist or is inaccessible.
(map-entries bpf-map)Get all key-value pairs from map as a lazy sequence.
Returns a lazy sequence of [key value] vectors. Values are looked up on-demand, making this efficient for large maps.
Example: (doseq [[k v] (take 100 (map-entries my-map))] (process k v))
Get all key-value pairs from map as a lazy sequence. Returns a lazy sequence of [key value] vectors. Values are looked up on-demand, making this efficient for large maps. Example: (doseq [[k v] (take 100 (map-entries my-map))] (process k v))
(map-entries-chunked bpf-map)(map-entries-chunked bpf-map chunk-size)Get map entries in chunks for better performance.
Returns a lazy sequence of [key value] vectors, but fetches entries in batches to reduce syscall overhead.
Parameters:
Example: (doseq [[k v] (map-entries-chunked my-map 1000)] (process k v))
Get map entries in chunks for better performance. Returns a lazy sequence of [key value] vectors, but fetches entries in batches to reduce syscall overhead. Parameters: - bpf-map: The BPF map - chunk-size: Number of entries to fetch per batch (default 100) Example: (doseq [[k v] (map-entries-chunked my-map 1000)] (process k v))
(map-every? pred bpf-map)Returns true if pred returns true for all entries.
Short-circuits on first false.
Parameters:
Returns true if pred returns true for all entries. Short-circuits on first false. Parameters: - pred: Predicate function (fn [[key value]] ...) - bpf-map: The BPF map
(map-exists? bpf-map)Check if a BPF map is still valid and exists in the kernel.
Returns true if the map FD is valid and the map exists. Returns false if the map has been closed or deleted.
This performs a simple get-next-key operation which will fail if the map FD is invalid.
Check if a BPF map is still valid and exists in the kernel. Returns true if the map FD is valid and the map exists. Returns false if the map has been closed or deleted. This performs a simple get-next-key operation which will fail if the map FD is invalid.
(map-filter pred bpf-map)Return a lazy sequence of entries matching predicate.
Parameters:
Example: (map-filter (fn [[k v]] (> v 100)) my-map)
Return a lazy sequence of entries matching predicate. Parameters: - pred: Predicate function (fn [[key value]] ...) returning true to include - bpf-map: The BPF map Example: (map-filter (fn [[k v]] (> v 100)) my-map)
(map-from-fd fd
&
{:keys [key-size value-size map-type max-entries key-serializer
key-deserializer value-serializer value-deserializer]
:or {key-serializer identity
key-deserializer identity
value-serializer identity
value-deserializer identity}})Create a BpfMap record from an existing file descriptor (e.g., from a pinned map retrieved with obj-get)
Required keyword arguments:
Optional keyword arguments:
Note: The FD is assumed to be valid. Since the kernel doesn't provide a way to query map metadata, you must provide sizes and serializers.
Create a BpfMap record from an existing file descriptor (e.g., from a pinned map retrieved with obj-get) Required keyword arguments: - :key-size - Size of key in bytes - :value-size - Size of value in bytes - :key-serializer - Function to serialize keys to bytes - :key-deserializer - Function to deserialize bytes to keys - :value-serializer - Function to serialize values to bytes - :value-deserializer - Function to deserialize bytes to values Optional keyword arguments: - :map-type - Type of map (optional, for documentation) - :max-entries - Maximum entries (optional, for documentation) Note: The FD is assumed to be valid. Since the kernel doesn't provide a way to query map metadata, you must provide sizes and serializers.
(map-get-next-key bpf-map key)Get next key in map (for iteration) Pass nil as key to get first key
Get next key in map (for iteration) Pass nil as key to get first key
(map-keys bpf-map)Get all keys from map as a lazy sequence.
The sequence is generated on-demand using BPF's get_next_key syscall, making it memory-efficient for large maps.
Example: (take 10 (map-keys my-map)) ; Get first 10 keys without loading all
Get all keys from map as a lazy sequence. The sequence is generated on-demand using BPF's get_next_key syscall, making it memory-efficient for large maps. Example: (take 10 (map-keys my-map)) ; Get first 10 keys without loading all
(map-lookup bpf-map key)Lookup value by key in map
Lookup value by key in map
(map-lookup-and-delete-batch bpf-map keys)Batch lookup and delete multiple keys from map atomically
Parameters:
Returns a sequence of [key value] pairs for keys that existed. Keys are deleted from the map after being read.
Batch lookup and delete multiple keys from map atomically Parameters: - bpf-map: BpfMap instance - keys: Sequence of keys to lookup and delete Returns a sequence of [key value] pairs for keys that existed. Keys are deleted from the map after being read.
(map-lookup-batch bpf-map keys)Batch lookup multiple keys from map
Parameters:
Returns a sequence of [key value] pairs for keys that exist. Missing keys are omitted from the result.
Batch lookup multiple keys from map Parameters: - bpf-map: BpfMap instance - keys: Sequence of keys to lookup Returns a sequence of [key value] pairs for keys that exist. Missing keys are omitted from the result.
(map-pinned? bpf-map)Check if a map is pinned to the BPF filesystem.
Note: This only checks if the map was created with pinning info in this session. To check if a map file exists on disk, use clojure.java.io/file.
Check if a map is pinned to the BPF filesystem. Note: This only checks if the map was created with pinning info in this session. To check if a map file exists on disk, use clojure.java.io/file.
(map-some pred bpf-map)Returns the first entry where pred returns logical true.
Short-circuits as soon as a match is found.
Parameters:
Example: (map-some (fn [[k v]] (when (> v 1000) [k v])) my-map)
Returns the first entry where pred returns logical true. Short-circuits as soon as a match is found. Parameters: - pred: Predicate function (fn [[key value]] ...) - bpf-map: The BPF map Example: (map-some (fn [[k v]] (when (> v 1000) [k v])) my-map)
(map-update bpf-map key value & {:keys [flags] :or {flags :any}})Update or insert key-value pair in map
Flags:
Update or insert key-value pair in map Flags: - :any - Create new element or update existing (default) - :noexist - Create new element, fail if exists - :exist - Update existing element, fail if not exists
(map-update-batch bpf-map entries & {:keys [flags] :or {flags :any}})Batch update multiple key-value pairs in map
Parameters:
Returns the number of entries successfully updated.
Batch update multiple key-value pairs in map Parameters: - bpf-map: BpfMap instance - entries: Sequence of [key value] pairs to update - flags: Update flags (:any, :noexist, :exist), default :any Returns the number of entries successfully updated.
(map-values bpf-map)Get all values from map as a lazy sequence
Get all values from map as a lazy sequence
(percpu-avg percpu-values)Calculate average value across all CPUs.
Parameters:
Returns the average (mean) of all per-CPU values.
Calculate average value across all CPUs. Parameters: - percpu-values: Vector of values, one per CPU Returns the average (mean) of all per-CPU values.
(percpu-max percpu-values)Get maximum value across all CPUs.
Parameters:
Returns the maximum value among all CPUs.
Get maximum value across all CPUs. Parameters: - percpu-values: Vector of values, one per CPU Returns the maximum value among all CPUs.
(percpu-min percpu-values)Get minimum value across all CPUs.
Parameters:
Returns the minimum value among all CPUs.
Get minimum value across all CPUs. Parameters: - percpu-values: Vector of values, one per CPU Returns the minimum value among all CPUs.
(percpu-sum percpu-values)Sum values across all CPUs.
Parameters:
Returns the sum of all per-CPU values.
Sum values across all CPUs. Parameters: - percpu-values: Vector of values, one per CPU Returns the sum of all per-CPU values.
(pin-map bpf-map path)Pin map to BPF filesystem
Pin map to BPF filesystem
(queue-peek bpf-map)Peek at the front value of a queue map without removing it
Parameters:
Returns the front value, or nil if queue is empty.
Peek at the front value of a queue map without removing it Parameters: - bpf-map: Queue map instance Returns the front value, or nil if queue is empty.
(queue-pop bpf-map)Pop a value from a queue map (dequeue, FIFO)
Parameters:
Returns the popped value, or nil if queue is empty.
Pop a value from a queue map (dequeue, FIFO) Parameters: - bpf-map: Queue map instance Returns the popped value, or nil if queue is empty.
(queue-push bpf-map value)Push a value onto a queue map (enqueue)
Parameters:
Returns nil on success, throws on error.
Push a value onto a queue map (enqueue) Parameters: - bpf-map: Queue map instance - value: Value to push Returns nil on success, throws on error.
(reduce-map f init bpf-map)Reduce over map entries without creating intermediate sequences.
More memory-efficient than (reduce f init (map-entries m)) for very large maps as it processes entries one at a time.
Parameters:
Example: (reduce-map (fn [sum [k v]] (+ sum v)) 0 my-map)
Reduce over map entries without creating intermediate sequences. More memory-efficient than (reduce f init (map-entries m)) for very large maps as it processes entries one at a time. Parameters: - f: Reducing function (fn [acc [key value]] ...) - init: Initial accumulator value - bpf-map: The BPF map Example: (reduce-map (fn [sum [k v]] (+ sum v)) 0 my-map)
(remove-inner-map mim key)Remove an inner map at the specified index/key.
Deletes the entry from the outer map and closes the inner map.
Parameters:
Returns true if removed, false if not found.
Remove an inner map at the specified index/key. Deletes the entry from the outer map and closes the inner map. Parameters: - mim: MapInMap record - key: Index or key to remove Returns true if removed, false if not found.
(stack-peek bpf-map)Peek at the top value of a stack map without removing it
Parameters:
Returns the top value, or nil if stack is empty.
Peek at the top value of a stack map without removing it Parameters: - bpf-map: Stack map instance Returns the top value, or nil if stack is empty.
(stack-pop bpf-map)Pop a value from a stack map (LIFO)
Parameters:
Returns the popped value, or nil if stack is empty.
Pop a value from a stack map (LIFO) Parameters: - bpf-map: Stack map instance Returns the popped value, or nil if stack is empty.
(stack-push bpf-map value)Push a value onto a stack map
Parameters:
Returns nil on success, throws on error.
Push a value onto a stack map Parameters: - bpf-map: Stack map instance - value: Value to push Returns nil on success, throws on error.
(with-map [binding map-spec] & body)Create a map and ensure it's closed after use
Create a map and ensure it's closed after use
(with-map-in-map [binding outer-type max-entries inner-spec & opts] & body)Create a map-in-map and ensure it's closed after use.
Example: (with-map-in-map [mim :array-of-maps 64 {:map-type :hash :key-size 4 :value-size 8 :max-entries 100}] (add-inner-map mim 0) (inner-map-update mim 0 42 12345) (println (inner-map-lookup mim 0 42)))
Create a map-in-map and ensure it's closed after use.
Example:
(with-map-in-map [mim :array-of-maps 64
{:map-type :hash :key-size 4 :value-size 8 :max-entries 100}]
(add-inner-map mim 0)
(inner-map-update mim 0 42 12345)
(println (inner-map-lookup mim 0 42)))cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |