kobj_init_static (9)

Leading comments

Copyright (c) 2000 Doug Rabson

All rights reserved.

This program is free software.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in...

(The comments found at the beginning of the groff file "man9/kobj_init_static.9freebsd".)

NAME

kobj - a kernel object system for FreeBSD

SYNOPSIS

In sys/param.h In sys/kobj.h Ft void Fn kobj_class_compile kobj_class_t cls Ft void Fn kobj_class_compile_static kobj_class_t cls kobj_ops_t ops Ft void Fn kobj_class_free kobj_class_t cls Ft kobj_t Fn kobj_create kobj_class_t cls struct malloc_type *mtype int mflags Ft void Fn kobj_init kobj_t obj kobj_class_t cls Ft void Fn kobj_init_static kobj_t obj kobj_class_t cls Ft void Fn kobj_delete kobj_t obj struct malloc_type *mtype Fn DEFINE_CLASS name kobj_method_t *methods size_t size

DESCRIPTION

The kernel object system implements an object-oriented programming system in the Fx 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 Fn 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 Fn kobj_delete .

Clients which would like to manage the allocation of memory themselves should call Fn kobj_init or Fn kobj_init_static with a pointer to the memory for the object and the class which implements it. It is also possible to use Fn kobj_init and Fn 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 Fn kobj_class_compile , Fn kobj_class_compile_static and Fn 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 Fn kobj_class_compile_static should be called with the class and a pointer to a statically allocated Vt kobj_ops structure before the class is used to initialise any objects. In that case, also Fn kobj_init_static should be used instead of Fn kobj_init .

To define a class, first define a simple array of Vt kobj_method_t . Each method which the class implements should be entered into the table using the macro Fn 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 Fn DEFINE_CLASS can then be used to initialise a Vt kobj_class_t structure. The size argument to Fn 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 Fx 3.0 and more widely in Fx 4.0 .

AUTHORS

This manual page was written by An Doug Rabson .