1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2000 Doug Rabson 4.\" 5.\" All rights reserved. 6.\" 7.\" This program is free software. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 19.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 20.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 21.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 23.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 27.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd April 4, 2000 32.Dt KOBJ 9 33.Os FreeBSD 34.Sh NAME 35.Nm kobj 36.Nd a kernel object system for FreeBSD 37.Sh SYNOPSIS 38.Fd #include <sys/param.h> 39.Fd #include <sys/kobj.h> 40.Ft void 41.Fn kobj_class_compile "kobj_class_t cls" 42.Ft void 43.Fn kobj_class_free "kobj_class_t cls" 44.Ft kobj_t 45.Fn kobj_create "kobj_class_t cls" "struct malloc_type *mtype" "int mflags" 46.Ft void 47.Fn kobj_init "kobj_t obj" "kobj_class_t cls" 48.Ft void 49.Fn kobj_delete "kobj_t obj" "struct malloc_type *mtype" 50.Fn DEFINE_CLASS "name" "methods" "size" 51.Sh DESCRIPTION 52.Pp 53The kernel object system implements an object-oriented programming 54system in the FreeBSD kernel. 55The system is based around the concepts of interfaces, which are 56descriptions of sets of methods; classes, which are lists of functions 57implementing certain methods from those interfaces; and objects, 58which combine a class with a structure in memory. 59.Pp 60Methods are called using a dynamic method dispatching algorithm which 61is designed to allow new interfaces and classes to be introduced into 62the system at runtime. 63The method dispatch algorithm is designed to be both fast and robust 64and is only slightly more expensive than a direct function call, 65making kernel objects suitable for performance-critical algorithms. 66.Pp 67Suitable uses for kernel objects are any algorithms which need some 68kind of polymorphism (i.e. many different objects which can be treated 69in a uniform way). 70The common behaviour of the objects is described by a suitable 71interface and each different type of object is implemented by a 72suitable class. 73.Pp 74The simplest way to create a kernel object is to call 75.Fn kobj_create 76with a suitable class, malloc type and flags (see 77.Xr malloc 9 78for a description of the malloc type and flags). 79This will allocate memory for the object based on the object size 80specified by the class and initialise it be zeroing the memory and 81installing a pointer to the class' method dispatch table. 82Objects created in this way should be freed by calling 83.Fn kobj_free . 84.Pp 85Clients which would like to manage the allocation of memory 86themselves should call 87.Fn kobj_init 88with a pointer to the memory for the object and the class which 89implements it. 90It is also possible to use 91.Fn kobj_init 92to change the class for an object. 93This should be done with care as the classes must agree on the layout 94of the object. 95The device framework uses this feature to associate drivers with 96devices. 97.Pp 98The functions 99.Fn kobj_class_compile 100and 101.Fn kobj_class_free 102are used to process a class description to make method despatching 103efficient. 104A client should not normally need to call these since a class 105will automatically be compiled the first time it is used. 106.Pp 107To define a class, first define a simple array of 108.Dv kobj_method_t . 109Each method which the class implements should be entered into the 110table using the macro 111.Fn KOBJMETHOD 112which takes the name of the method (including its interface) and a 113pointer to a function which implements it. 114The table should be terminated with two zeros. 115The macro 116.Fn DEFINE_CLASS 117can then be used to initialise a 118.Dv kobj_class_t 119structure. 120The size argument to 121.Fn DEFINE_CLASS 122specifies how much memory should be allocated for each object. 123.Sh HISTORY 124Some of the concepts for this interface appeared in the device 125framework used for the alpha port of 126.Fx 3.0 127and more widely in 128.Fx 4.0 . 129.Sh AUTHORS 130This man page was written by 131.An Doug Rabson . 132