__xa_alloc_cyclic(9)

📦 version 7.3.1, in nixpkgs unstable

💅 __xa_alloc_cyclic — kernel API manual, but make it make sense 💅

okay bestie, buckle up, because this one is literally the "find a home for my little guy" function and it's lowkey iconic ✨ (it's __xa_alloc_cyclic(9) from the Kernel API Manual, iykyk)

🌸 NAME 🌸

__xa_alloc_cyclic — find somewhere to store this entry in the XArray. that's it, that's the whole vibe 🎀

✨ SYNOPSIS ✨

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

like, no cap, that's the whole signature 💖

🫶 ARGUMENTS 🫶

  • xa — the XArray. your whole little world, bestie 🦋
  • id — pointer to the ID. it's giving "where the answer goes" 👑
  • entry — the new entry. the main character we're finding a spot for 💅
  • limit — the range of allocated ID. like a velvet rope at the club, but for indices 🌈
  • next — pointer to the next ID to allocate. the starting point of the hunt, fr fr 🔥
  • gfp — memory allocation flags. the little settings that decide how hard we're allowed to try 😭

💜 DESCRIPTION 💜

So here's the tea, bestie 🍓: this function finds an empty entry in xa somewhere between limit.min and limit.max, stores the index into the id pointer, and then stores the entry at that index. the order matters, okay? a concurrent lookup will not see an uninitialised id — slay, no race, no drama ✨

The search for an empty entry starts at next and will wrap around if necessary. it really said "i'll go around the whole thing if i have to" 🌀

okay and this is the important part, do not skip it 🙈 — this must only be operated on an xarray initialized with flag XA_FLAGS_ALLOC set in xa_init_flags. like if you skip that, it's not my fault, i warned you 💀

🧚 CONTEXT 🧚

Any context. yes, ANY. we're flexible like that 💃

It expects xa_lock to be held on entry. it may release and reacquire xa_lock if the gfp flags permit — so like, it might let go of the lock for a sec and then grab it back, depending on what you allowed it to do. ngl that's kinda iconic 😌

⭐ RETURN ⭐

  • 0 — the allocation succeeded without wrapping. clean, no notes 💖
  • 1 — the allocation succeeded after wrapping. it did the extra lap 🏃‍♀️
  • -ENOMEM — memory could not be allocated 😭
  • -EBUSY — there are no free entries in limit. the door is closed, the club is full, nothing for you here 💀

🦋 SEE ALSO 🦋

kernel file ./lib/xarray.c, plus literally the whole friend group: xas_load(9), xas_nomem(9), xas_free_nodes(9), xas_create_range(9), xas_store(9), xas_get_mark(9), xas_set_mark(9), xas_clear_mark(9), xas_init_marks(9), xas_split_alloc(9), xas_split(9), xas_try_split_min_order(9), xas_try_split(9), xas_pause(9), xas_find(9), xas_find_marked(9), xas_find_conflict(9), xa_load(9), __xa_erase(9), xa_erase(9), __xa_store(9), xa_store(9), __xa_cmpxchg(9), __xa_insert(9), xa_store_range(9), xas_get_order(9), xa_get_order(9), __xa_alloc(9), __xa_set_mark(9), __xa_clear_mark(9), xa_get_mark(9), xa_set_mark(9), xa_clear_mark(9), xa_find(9), xa_find_after(9), xa_extract(9), xa_delete_node(9), xa_destroy(9)

🎀 sign-off 🎀

this masterpiece lives in ./lib, dated October 2026, and it's <rainbow>__xa_alloc_cyclic(9)</rainbow> forever and ever, periodt 💅💖✨

📦 where this page comes from