3 .\" Copyright (c) 2000 Doug Rabson
5 .\" All rights reserved.
7 .\" This program is free software.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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.
36 .Nd a kernel object system for FreeBSD
41 .Fn kobj_class_compile "kobj_class_t cls"
43 .Fn kobj_class_compile_static "kobj_class_t cls" "kobj_ops_t ops"
45 .Fn kobj_class_free "kobj_class_t cls"
47 .Fn kobj_create "kobj_class_t cls" "struct malloc_type *mtype" "int mflags"
49 .Fn kobj_init "kobj_t obj" "kobj_class_t cls"
51 .Fn kobj_init_static "kobj_t obj" "kobj_class_t cls"
53 .Fn kobj_delete "kobj_t obj" "struct malloc_type *mtype"
54 .Fn DEFINE_CLASS name "kobj_method_t *methods" "size_t size"
56 The kernel object system implements an object-oriented programming
60 The system is based around the concepts of interfaces, which are
61 descriptions of sets of methods; classes, which are lists of functions
62 implementing certain methods from those interfaces; and objects,
63 which combine a class with a structure in memory.
65 Methods are called using a dynamic method dispatching algorithm which
66 is designed to allow new interfaces and classes to be introduced into
67 the system at runtime.
68 The method dispatch algorithm is designed to be both fast and robust
69 and is only slightly more expensive than a direct function call,
70 making kernel objects suitable for performance-critical algorithms.
72 Suitable uses for kernel objects are any algorithms which need some
73 kind of polymorphism (i.e., many different objects which can be treated
75 The common behaviour of the objects is described by a suitable
76 interface and each different type of object is implemented by a
79 The simplest way to create a kernel object is to call
81 with a suitable class, malloc type and flags (see
83 for a description of the malloc type and flags).
84 This will allocate memory for the object based on the object size
85 specified by the class and initialise it by zeroing the memory and
86 installing a pointer to the class' method dispatch table.
87 Objects created in this way should be freed by calling
90 Clients which would like to manage the allocation of memory
91 themselves should call
95 with a pointer to the memory for the object and the class which
97 It is also possible to use
101 to change the class for an object.
102 This should be done with care as the classes must agree on the layout
104 The device framework uses this feature to associate drivers with
108 .Fn kobj_class_compile ,
109 .Fn kobj_class_compile_static
112 are used to process a class description to make method dispatching
114 A client should not normally need to call these since a class
115 will automatically be compiled the first time it is used.
116 If a class is to be used before
122 .Fn kobj_class_compile_static
123 should be called with the class and a pointer to a statically
126 structure before the class is used to initialise any objects.
129 should be used instead of
132 To define a class, first define a simple array of
134 Each method which the class implements should be entered into the
135 table using the macro
137 which takes the name of the method (including its interface) and a
138 pointer to a function which implements it.
139 The table should be terminated with two zeros.
142 can then be used to initialise a
147 specifies how much memory should be allocated for each object.
149 Some of the concepts for this interface appeared in the device
150 framework used for the alpha port of
155 This manual page was written by