NAME

       kobj — a kernel object system for FreeBSD

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

       The  kernel  object  system  implements an object-oriented programming system in the FreeBSD kernel.  The
       system is based around the concepts of interfaces, which are descriptions of sets  of  methods;  classes,
       which  are  lists  of  functions  implementing  certain methods from those interfaces; and objects, which
       combine a class with a structure in memory.

       Methods are called using a dynamic method dispatching algorithm which is designed to allow new interfaces
       and classes to be introduced into the system at runtime.  The method dispatch algorithm is designed to be
       both fast and robust and is only slightly more expensive than  a  direct  function  call,  making  kernel
       objects suitable for performance-critical algorithms.

       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.

       The  simplest  way  to create a kernel object is to call kobj_create() with a suitable class, malloc type
       and flags (see malloc(9) for a description of the malloc type and flags).  This will allocate memory  for
       the  object  based  on the object size specified by the class and initialise it by zeroing the memory and
       installing a pointer to the class' method dispatch table.  Objects created in this way should be freed by
       calling kobj_delete().

       Clients which would 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 is
       also possible to use kobj_init() and kobj_init_static() to change the class for an object.   This  should
       be  done with care as the classes must agree on the layout of the object.  The device framework uses this
       feature to associate drivers with devices.

       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.  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().

       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)  and  a  pointer  to  a  function  which  implements it.  The table should be
       terminated with two zeros.  The macro DEFINE_CLASS() can  then  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.

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.

AUTHORS

       This manual page was written by Doug Rabson.

Debian                                          November 14, 2011                                        KOBJ(9)