xa_alloc_cyclic(9)

📦 version 7.3.1, in nixpkgs unstable

💅 xa_alloc_cyclic(9) — like, the Kernel API Manual page, but make it make sense ✨

okay so bestie, gather round, because this one is from the Kernel API Manual and it's genuinely so useful once you get the vibe. The function is xa_alloc_cyclic, and it is literally the "find me a spot and put my thing there" icon of the XArray world. 👑

🎀 NAME 🎀

xa_alloc_cyclic — find somewhere to store this entry in the XArray. that's it. that's the whole assignment. 💖

🌸 SYNOPSIS 🌸

int xa_alloc_cyclic (struct xarray *xa , u32 *id , void *entry , struct
xa_limit limit , u32 *next , gfp_t gfp );

look at her. six params. main character energy fr fr. 🦋

✨ ARGUMENTS ✨

  • xa — the XArray. your canvas. your little data home. 💜
  • id — pointer to the ID. the function writes the index it picked in here. 🎀
  • entry — the new entry. the thing you actually want to store. 🍓
  • limit — the range of allocated ID. you get a min and a max and you do not stray outside them, periodt. 🚧
  • next — pointer to next ID to allocate. it's where the search starts (and it wraps around if it runs off the end, iykyk). 🔄
  • gfp — memory allocation flags. the whole "can I sleep or not" situation. 😴

🦋 DESCRIPTION 🦋

so the way this works: it finds an empty entry in xa somewhere between limit.min and limit.max — inclusive vibes — then stores the index into the id pointer, and then stores the entry at that index. ✨

and the order matters bestie: because it does the id first, a concurrent lookup will not see an uninitialised id. slay. 💅

the search for an empty entry starts at next, and it will wrap around if necessary. cyclic, see? it's giving circular. 🌈

⚠️ okay, important one: this must only be operated on an xarray initialized with the flag XA_FLAGS_ALLOC set in xa_init_flags. no cap, don't skip this. 🙈

also ngl, if you're a caller who actually cares whether wrapping has occurred, you should use __xa_alloc_cyclic instead. the info is there, just not from this one. 💀

💜 CONTEXT 💜

any context, bestie. it takes and releases the xa_lock. and it may sleep if the gfp flags permit — so like, know your flags before you commit. 😭

⭐ RETURN ⭐

  • 0 if the allocation succeeded 🎉
  • -ENOMEM if memory could not be allocated 😔
  • -EBUSY if there are no free entries in limit 🚫

three outcomes. that's it. go off. 🔥

👑 SEE ALSO 👑

so there's a whole friend group here, and honestly? they're all iconic. first up, the kernel file itself lives at ./include/linux/xarray.h. and then:

the value-detective squad:

the struct girlies:

  • struct xa_limit(9), struct xarray(9)

defining + initialising:

iteration nation:

storing + erasing (the bh/irq cinematic universe):

compare-and-swap crew:

inserting:

the alloc family (our girl's relatives):

reserve + release:

little status checks:

the XA_STATE macros:

the xas_* extended family (there are SO many, drink some water):

and that's the page, bestie!! 🫶 coming at you from ./include/linux and dated October 2026 — mwah, go allocate something cyclic responsibly, ily, bye!! 🧚💖

📦 where this page comes from