VM_PAGE_BUSY(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 VM_PAGE_BUSY(9) — Kernel Developer's Manual 💅

okay so bestie, welcome to the VM_PAGE_BUSY(9) page from the Kernel Developer’s Manual 💖 this whole thing is about protecting page identity changes and page content references, and it’s lowkey a whole vibe.

✨ NAME ✨

vm_page_busied, vm_page_busy_downgrade, vm_page_busy_sleep, vm_page_sbusied, vm_page_sunbusy, vm_page_trysbusy, vm_page_tryxbusy, vm_page_xbusied, vm_page_xunbusy, vm_page_assert_sbusied, vm_page_assert_unbusied, vm_page_assert_xbusied — protect page identity changes and page content references 💖

🦋 SYNOPSIS 🦋

the includes and signatures, served exactly as written, no cap:

#include <sys/param.h>
#include <vm/vm.h>
#include <vm/vm_page.h>

int
vm_page_busied(vm_page_t m);

void
vm_page_busy_downgrade(vm_page_t m);

bool
vm_page_busy_sleep(vm_page_t m, const char *msg, int allocflags);

int
vm_page_sbusied(vm_page_t m);

void
vm_page_sunbusy(vm_page_t m);

int
vm_page_trysbusy(vm_page_t m);

int
vm_page_tryxbusy(vm_page_t m);

int
vm_page_xbusied(vm_page_t m);

void
vm_page_xunbusy(vm_page_t m);

options INVARIANTS
options INVARIANT_SUPPORT

void
vm_page_assert_sbusied(vm_page_t m);

void
vm_page_assert_unbusied(vm_page_t m);

void
vm_page_assert_xbusied(vm_page_t m);

🔥 DESCRIPTION 🔥

so page identity is usually protected by higher level locks like vm_object locks and vm page locks. but sometimes it is not possible to hold such locks for the time necessary to complete the identity change 😭 in that case the page can be exclusively busied by a thread which needs to own the identity for a certain amount of time. main character energy, honestly.

in other situations, threads do not need to change the identity of the page but they want to prevent other threads from changing the identity themselves. for example, when a thread wants to access or update page contents without a lock held, the page is shared busied ✨

🔒 big rule energy: before busying a page the vm_object lock must be held. the same rule applies when a page is unbusied. this makes the vm_object lock a real busy interlock. periodt.

okay now the function tea, one by one:

  • vm_page_busied() — returns non-zero if the current thread busied m in either exclusive or shared mode. returns zero otherwise.
  • vm_page_busy_downgrade() — must be used to downgrade m from an exclusive busy state to a shared busy state.
  • vm_page_busy_sleep() — checks the busy state of the page m and puts the invoking thread to sleep if the page is busy. the VM object for the page must be locked. the allocflags parameter must be either 0, in which case the function will sleep if the page is busied, or VM_ALLOC_IGN_SBUSY, in which case the function will sleep only if the page is exclusively busied. a return value of true indicates that the invoking thread was put to sleep and that the object was unlocked. a return value of false indicates that the invoking thread did not sleep and the object remains locked. the parameter msg is a string describing the sleep condition for userland tools.
  • vm_page_busied() — the shared-mode line as printed: returns non-zero if the current thread busied m in shared mode. returns zero otherwise.
  • vm_page_sunbusy() — shared unbusies m.
  • vm_page_trysbusy() — attempts to shared busy m. if the operation cannot immediately succeed vm_page_trysbusy() returns 0, otherwise a non-zero value is returned.
  • vm_page_tryxbusy() — attempts to exclusive busy m. if the operation cannot immediately succeed vm_page_tryxbusy() returns 0, otherwise a non-zero value is returned.
  • vm_page_xbusied() — returns non-zero if the current thread busied m in exclusive mode. returns zero otherwise.
  • vm_page_xunbusy() — exclusive unbusies m. assertions on the busy state allow kernels compiled with options INVARIANTS and options INVARIANT_SUPPORT to panic if they are not respected.
  • vm_page_assert_sbusied() — panics if m is not shared busied.
  • vm_page_assert_unbusied() — panics if m is not unbusied.
  • vm_page_assert_xbusied() — panics if m is not exclusive busied.

🌈 SEE ALSO 🌈

and that’s the whole page, bestie 💖 this one came from Debian, dated November 11, 2021, and its manual handle is VM_PAGE_BUSY(9) — slay and stay correctly busied ✨🎀

📦 where this page comes from