Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
KOBJ(9)			 BSD Kernel Developer's	Manual		       KOBJ(9)

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	inter-
     faces, 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 func-
     tion call,	making kernel objects suitable for performance-critical	algo-
     rithms.

     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 ze-
     roing 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 mem-
     ory for the object	and the	class which implements it.  It is also possi-
     ble 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 asso-
     ciate 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 ob-
     ject.

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.

BSD			       November	14, 2011			   BSD

NAME | SYNOPSIS | DESCRIPTION | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=kobj&sektion=9&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help