crush_choose_firstn(9)

💅 crush_choose_firstn — choose numrep distinct items of given type ✨

okay so bestie, this is a page from the Kernel API Manual (section 9 of the manual, iykyk) and honestly? it's giving "the function that actually picks your OSDs" energy. the whole vibe is: give me a bucket, give me a number, and I'll hand you back that many distinct items of a given type. no dupes, no cap. 👑

🌸 SYNOPSIS 🌸

int crush_choose_firstn (const struct crush_map *map , struct crush_work
*work , const struct crush_bucket *bucket , const __u32 *weight , int
weight_max , int x , int numrep , int type , int *out , int outpos , int
out_size , unsigned int tries , unsigned int recurse_tries , unsigned
int local_retries , unsigned int local_fallback_retries , int
recurse_to_leaf , unsigned int vary_r , unsigned int stable , int *out2
, int parent_r , const struct crush_choose_arg *choose_args );

yes she takes twenty-two arguments. twenty-two. she's high-maintenance and we love her for it 💖

🎀 ARGUMENTS 🎀

• map — the crush_map. the map. the whole entire blueprint, bestie.
• work — working space initialized by crush_init_workspace. it's the scratch pad, pre-chewed for her convenience ✨
• bucket — the bucket we are choose an item from. (their words, not mine, but yes: this is the bucket we're picking out of.)
• weight — weight vector (for map leaves). the actual weights, laid out for the leaves of the map.
• weight_max — size of weight vector. how long weight is.
• x — crush input value. the input. the seed of the whole situation.
• numrep — the number of items to choose. how many you want back, periodt.
• type — the type of item to choose. like, what kind of thing you're shopping for.
• out — pointer to output vector. where the chosen ones land 🫶
• outpos — our position in that vector. where we start writing. our little spot.
• out_size — size of the out vector. don't overflow it, bestie, I'm begging.
• tries — number of attempts to make. how many shots we take.
• recurse_tries — number of attempts to have recursive chooseleaf make. the retry budget for the recursive chooseleaf situation.
• local_retries — localized retries.
• local_fallback_retries — localized fallback retries. yes, that's a second kind of local retry. she's thorough 💅
• recurse_to_leaf — true if we want one device under each item of given type (chooseleaf instead of choose). so like: chooseleaf mode instead of plain choose mode. 🍓
• vary_r — pass r to recursive calls. literally just: forward the r down into recursion.
• stable — stable mode starts rep=0 in the recursive call for all replicas. that's the whole behavior, no notes.
• out2 — second output vector for leaf items (if recurse_to_leaf). the second vector. only relevant when you're doing the recurse-to-leaf thing.
• parent_r — r value passed from the parent. inherited from mom-and-dad call site.
• choose_args — weights and ids for each known bucket. the per-bucket weights + ids lookup situation.

🦋 SEE ALSO 🦋

• Kernel file ./net/ceph/crush/mapper.c
• crush_find_rule(9)
• crush_do_rule(9)

go read those next, bestie, they're literally the rest of the lore 📚

⚠️ real talk: this is kernel API territory — every parameter, every unsigned int, every pointer matters exactly as written. I didn't invent a single one and neither should you. 🙈

sign-off time ✨ this iconic little page lives in ./net/ceph/crush, dated October 2026, and it's filed as crush_choose_firstn(9) — go off, section 9 🎀💜