try_grab_folio_fast(9)

📦 version 7.3.1, in nixpkgs unstable

💅 try_grab_folio_fast — from the Kernel API Manual, bestie 🎀

okay so picture this: you're deep in the kernel, the fast path is right there, and you need to grab or pin a folio. that's the whole vibe of this page. welcome to try_grab_folio_fast(9), it's giving "low-level memory management but make it fashion" ✨

✨ NAME ✨

try_grab_folio_fast — Attempt to get or pin a folio in fast path. that's it, that's the girl 💅

🌸 SYNOPSIS 🌸

struct folio * try_grab_folio_fast (struct page *page , int refs ,
       unsigned int flags );

like, look at her signature. iconic. no cap.

🦋 ARGUMENTS 🦋

  • page — pointer to page to be grabbed. yes bestie, this is the page we're snatching up 🫶
  • refs — the value to (effectively) add to the folio's refcount. emphasis on effectively, the math is doing something, we'll get to it
  • flags — gup flags: these are the FOLL_* flag values. those ones, iykyk 🔥

💖 DESCRIPTION 💖

so first things first, vocabulary check 📚 — "grab" names in this file mean, "look at flags to decide whether to use FOLL_PIN or FOLL_GET behavior, when incrementing the folio's refcount." that's the whole definition, periodt.

important bestie — Either FOLL_PIN or FOLL_GET (or neither) must be set, but not both at the same time. (and yeah, that's true throughout the get_user_pages*() and pin_user_pages*() APIs. it's a whole family rule, fr fr.)

now the cases, because there ARE cases and you're gonna want to know them 👑

  • FOLL_GET: folio's refcount will be incremented by refs.
  • FOLL_PIN on large folios: folio's refcount will be incremented by refs, and its pincount will be incremented by refs. two for the price of one, ate 💅
  • FOLL_PIN on single-page folios: folio's refcount will be incremented by refs * GUP_PIN_COUNTING_BIAS. the bias is doing heavy lifting here, don't ask her to explain

It uses add ref unless zero to elevate the folio refcount — and it must be called in fast path only. not the slow path, not the vibes path, the fast path. main character energy only 🌈

⭐ RETURN ⭐

  • the folio containing page (with refcount appropriately incremented) — that's success, slay 👑
  • NULL — that's failure, we don't love her but we respect her 😭

and one more thing: if neither FOLL_GET nor FOLL_PIN was set, that's considered failure, and furthermore, a likely bug in the caller, so a warning is also emitted. so like… you get a NULL AND you get yelled at. the kernel is literally your bestie who tells you the truth 💀

🧚 SEE ALSO 🧚

Kernel file ./mm/gup.c, plus the whole friend group 🫶:

anyway that's the page!! came from ./mm, dated October 2026, and honestly?? obsessed. go pin a folio responsibly, bestie 💜🍓✨

📦 where this page comes from