KOBJ(9)

✨ KOBJ(9) ✨

okay bestie, buckle up 💖 this is the manual page for kobj, aka the kernel object system for FreeBSD, and it lives in section 9 of the Kernel Developer's Manual. it's giving object-oriented programming but make it kernel. let's go 💅

---

🌸 SYNOPSIS 🌸

#include <sys/param.h>
#include <sys/kobj.h>

void
kobj_class_compile(kobj_class_t cls);

void
kobj_class_compile_static(kobj_class_t cls, kobj_ops_t ops);

void
kobj_class_free(kobj_class_t cls);

kobj_t
kobj_create(kobj_class_t cls, struct malloc_type *mtype, int mflags);

void
kobj_init(kobj_t obj, kobj_class_t cls);

void
kobj_init_static(kobj_t obj, kobj_class_t cls);

void
kobj_delete(kobj_t obj, struct malloc_type *mtype);

DEFINE_CLASS(name, kobj_method_t *methods, size_t size);

---

🦋 DESCRIPTION 🦋

so the kernel object system literally implements an object-oriented programming system right inside the FreeBSD kernel. iconic. it's built around three concepts and they're all main characters:

• interfaces — these are descriptions of sets of methods
• classes — these are lists of functions implementing certain methods from those interfaces
• objects — these combine a class with a structure in memory

Methods get called using a dynamic method dispatching algorithm that's designed so new interfaces and classes can be introduced into the system at runtime. and the way this dispatch algorithm is built? it's both fast and robust, and it's only slightly more expensive than a direct function call — which means kernel objects are suitable for performance-critical algorithms. no cap 🔥

suitable uses for kernel objects are any algorithms which need some kind of polymorphism (i.e., many different objects which can be treated in a uniform way). the common behaviour of the objects is described by a suitable interface, and each different type of object is implemented by a suitable class. vibe check passed ✨

---

💜 creating objects, the easy way

the simplest way to create a kernel object is to call kobj_create() with a suitable class, malloc type and flags (peep malloc(9) for a description of the malloc type and flags 🫶). this will:

1. allocate memory for the object based on the object size specified by the class
2. initialise it by zeroing the memory
3. install a pointer to the class' method dispatch table

objects created this way should be freed by calling kobj_delete(). periodt.

💖 managing memory yourself

clients who'd like to manage the allocation of memory themselves should call kobj_init() or kobj_init_static() with a pointer to the memory for the object and the class which implements it.

it's also possible to use kobj_init() and kobj_init_static() to change the class for an object. do this with care, bestie, because the classes must agree on the layout of the object 😭. the device framework uses this feature to associate drivers with devices.

🌈 compiling classes

the functions kobj_class_compile(), kobj_class_compile_static() and kobj_class_free() are used to process a class description to make method dispatching efficient.

a client should not normally need to call these, since a class will automatically be compiled the first time it is used. ✨

but listen — if a class is to be used before malloc(9) and mutex(9) are initialised, then kobj_class_compile_static() should be called with the class and a pointer to a statically allocated kobj_ops structure before the class is used to initialise any objects. in that case, also kobj_init_static() should be used instead of kobj_init(). noted 📝

🎀 defining a class

to define a class, first define a simple array of kobj_method_t. each method which the class implements should be entered into the table using the macro KOBJMETHOD(), which takes:

• the name of the method (including its interface)
• a pointer to a function which implements it

the table should be terminated with two zeros. then the macro DEFINE_CLASS() can be used to initialise a kobj_class_t structure. the size argument to DEFINE_CLASS() specifies how much memory should be allocated for each object. slay 💅

---

🧚 HISTORY 🧚

some of the concepts for this interface appeared in the device framework used for the alpha port of FreeBSD 3.0, and more widely in FreeBSD 4.0. the lore is real 🫶

---

👑 AUTHORS 👑

this manual page was written by Doug Rabson. thank u Doug, we are obsessed 💜

---

and that's the whole page bestie — brought to you from Debian, dated November 14, 2011, on behalf of the KOBJ(9) manual. go forth and dispatch those methods dynamically 🌟💖