tracing_map_insert(9)

📦 version 7.3.1, in nixpkgs unstable

💅 tracing_map_insert 💅

okay so bestie, this is straight from the Kernel API Manual and it's the page for tracing_map_insert — lowkey iconic, highkey useful, and very tracing-map-core. let's get into it 💖

✨ NAME ✨

tracing_map_insert — insert a key and/or retrieve val from a tracing_map. periodt.

🌸 SYNOPSIS 🌸

struct tracing_map_elt * tracing_map_insert (struct tracing_map *map ,
void *key );

🎀 ARGUMENTS 🎀

  • map — the tracing_map you're inserting into. that's the whole vibe.
  • key — the key to insert, bestie.

💖 DESCRIPTION 💖

Okay so here's the tea: tracing_map_insert inserts a key into a tracing_map and creates + returns a fresh new tracing_map_elt for it. If that key has already been inserted by a previous call, it returns the tracing_map_elt already associated with it instead. slay.

When the map was created, the number of elements to be allocated for the map was specified (internally maintained as the tracing_map_elts created by tracing_map_init). That's the pre-allocated pool of tracing_map_elts that tracing_map_insert will allocate from when adding new keys. Once that pool is exhausted, tracing_map_insert is useless and will return NULL to signal that state. not me crying at the empty pool 😭.

There are two user-visible tracing_map variables, 'hits' and 'drops', and this function updates both. Every time an element is either successfully inserted or retrieved, the 'hits' value is incremented. Every time an element insertion fails, the 'drops' value is incremented. she's keeping score fr fr.

This is a lock-free tracing map insertion function implementing a modified form of Cliff Click's basic insertion algorithm. It requires the table size be a power of two. To prevent any possibility of an infinite loop, we always make the internal table size double the size of the requested table size (max_elts * 2). Likewise, we never reuse a slot or resize or delete elements — when we've reached max_elts entries, we simply return NULL once we've run out of entries. Readers can at any point in time traverse the tracing map and safely access the key/val pairs. iconic behavior, no cap.

🦋 RETURN 🦋

So the return is the tracing_map_elt pointer val associated with the key. If this was a newly inserted key, the val will be a newly allocated and associated tracing_map_elt pointer val. If the key wasn't found and the pool of tracing_map_elts has been exhausted, NULL is returned and no further insertions will succeed. that's the whole ending, bestie 🫶

🔥 SEE ALSO 🔥

Kernel file ./kernel/trace/tracing_map.c plus these absolute legends:

mwah 💋 this page's source/version is ./kernel/trace, and its date is October 2026. bye bestie, go insert some keys 🫶

📦 where this page comes from