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: src/share/man/man9/kobj.9,v 1.16 2005/06/28 20:15:18 hmp Exp $ 30.\" $DragonFly: src/share/man/man9/kobj.9,v 1.5 2007/12/13 20:51:37 swildner Exp $ 31.\" 32.Dd April 4, 2000 33.Dt KOBJ 9 34.Os 35.Sh NAME 36.Nm kobj 37.Nd a kernel object system for DragonFly 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/kobj.h 41.Ft void 42.Fn kobj_class_compile "kobj_class_t cls" 43.Ft void 44.Fn kobj_class_free "kobj_class_t cls" 45.Ft kobj_t 46.Fn kobj_create "kobj_class_t cls" "struct malloc_type *mtype" "int mflags" 47.Ft void 48.Fn kobj_init "kobj_t obj" "kobj_class_t cls" 49.Ft void 50.Fn kobj_delete "kobj_t obj" "struct malloc_type *mtype" 51.Fn DEFINE_CLASS name "kobj_method_t *methods" "size_t size" 52.Sh DESCRIPTION 53The kernel object system implements an object-oriented programming 54system in the 55.Dx 56kernel. 57The system is based around the concepts of interfaces, which are 58descriptions of sets of methods; classes, which are lists of functions 59implementing certain methods from those interfaces; and objects, 60which combine a class with a structure in memory. 61.Pp 62Methods are called using a dynamic method dispatching algorithm which 63is designed to allow new interfaces and classes to be introduced into 64the system at runtime. 65The method dispatch algorithm is designed to be both fast and robust 66and is only slightly more expensive than a direct function call, 67making kernel objects suitable for performance-critical algorithms. 68.Pp 69Suitable uses for kernel objects are any algorithms which need some 70kind of polymorphism (i.e., many different objects which can be treated 71in a uniform way). 72The common behaviour of the objects is described by a suitable 73interface and each different type of object is implemented by a 74suitable class. 75.Pp 76The simplest way to create a kernel object is to call 77.Fn kobj_create 78with a suitable class, malloc type and flags (see 79.Xr kmalloc 9 80for a description of the malloc type and flags). 81This will allocate memory for the object based on the object size 82specified by the class and initialise it by zeroing the memory and 83installing a pointer to the class' method dispatch table. 84Objects created in this way should be freed by calling 85.Fn kobj_delete . 86.Pp 87Clients which would like to manage the allocation of memory 88themselves should call 89.Fn kobj_init 90with a pointer to the memory for the object and the class which 91implements it. 92It is also possible to use 93.Fn kobj_init 94to change the class for an object. 95This should be done with care as the classes must agree on the layout 96of the object. 97The device framework uses this feature to associate drivers with 98devices. 99.Pp 100The functions 101.Fn kobj_class_compile 102and 103.Fn kobj_class_free 104are used to process a class description to make method dispatching 105efficient. 106A client should not normally need to call these since a class 107will automatically be compiled the first time it is used. 108.Pp 109To define a class, first define a simple array of 110.Vt kobj_method_t . 111Each method which the class implements should be entered into the 112table using the macro 113.Fn KOBJMETHOD 114which takes the name of the method (including its interface) and a 115pointer to a function which implements it. 116The table should be terminated with two zeros. 117The macro 118.Fn DEFINE_CLASS 119can then be used to initialise a 120.Vt kobj_class_t 121structure. 122The size argument to 123.Fn DEFINE_CLASS 124specifies how much memory should be allocated for each object. 125.Sh HISTORY 126Some of the concepts for this interface appeared in the device 127framework used for the alpha port of 128.Fx 3.0 129and more widely in 130.Fx 4.0 . 131.Sh AUTHORS 132This manual page was written by 133.An Doug Rabson . 134