1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
<table class="head">
<tr>
<td class="head-ltitle">KOBJ(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">KOBJ(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">kobj</code> — <span class="Nd">a kernel
object system for FreeBSD</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/param.h</a>></code>
<br/>
<code class="In">#include <<a class="In">sys/kobj.h</a>></code></p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">kobj_class_compile</code>(<var class="Fa" style="white-space: nowrap;">kobj_class_t
cls</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">kobj_class_compile_static</code>(<var class="Fa" style="white-space: nowrap;">kobj_class_t
cls</var>, <var class="Fa" style="white-space: nowrap;">kobj_ops_t
ops</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">kobj_class_free</code>(<var class="Fa" style="white-space: nowrap;">kobj_class_t
cls</var>);</p>
<p class="Pp"><var class="Ft">kobj_t</var>
<br/>
<code class="Fn">kobj_create</code>(<var class="Fa" style="white-space: nowrap;">kobj_class_t
cls</var>, <var class="Fa" style="white-space: nowrap;">struct malloc_type
*mtype</var>, <var class="Fa" style="white-space: nowrap;">int
mflags</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">kobj_init</code>(<var class="Fa" style="white-space: nowrap;">kobj_t
obj</var>, <var class="Fa" style="white-space: nowrap;">kobj_class_t
cls</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">kobj_init_static</code>(<var class="Fa" style="white-space: nowrap;">kobj_t
obj</var>, <var class="Fa" style="white-space: nowrap;">kobj_class_t
cls</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">kobj_delete</code>(<var class="Fa" style="white-space: nowrap;">kobj_t
obj</var>, <var class="Fa" style="white-space: nowrap;">struct malloc_type
*mtype</var>);</p>
<p class="Pp"><code class="Fn">DEFINE_CLASS</code>(<var class="Fa" style="white-space: nowrap;">name</var>,
<var class="Fa" style="white-space: nowrap;">kobj_method_t *methods</var>,
<var class="Fa" style="white-space: nowrap;">size_t size</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The kernel object system implements an object-oriented programming
system in the <span class="Ux">FreeBSD</span> 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.</p>
<p class="Pp">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.</p>
<p class="Pp">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.</p>
<p class="Pp" id="kobj_create">The simplest way to create a kernel object is to
call
<a class="permalink" href="#kobj_create"><code class="Fn">kobj_create</code></a>()
with a suitable class, malloc type and flags (see
<a class="Xr">malloc(9)</a> 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
<a class="permalink" href="#kobj_delete"><code class="Fn" id="kobj_delete">kobj_delete</code></a>().</p>
<p class="Pp" id="kobj_init">Clients which would like to manage the allocation
of memory themselves should call
<a class="permalink" href="#kobj_init"><code class="Fn">kobj_init</code></a>()
or
<a class="permalink" href="#kobj_init_static"><code class="Fn" id="kobj_init_static">kobj_init_static</code></a>()
with a pointer to the memory for the object and the class which implements
it. It is also possible to use <code class="Fn">kobj_init</code>() and
<code class="Fn">kobj_init_static</code>() 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.</p>
<p class="Pp" id="kobj_class_compile">The functions
<a class="permalink" href="#kobj_class_compile"><code class="Fn">kobj_class_compile</code></a>(),
<a class="permalink" href="#kobj_class_compile_static"><code class="Fn" id="kobj_class_compile_static">kobj_class_compile_static</code></a>()
and
<a class="permalink" href="#kobj_class_free"><code class="Fn" id="kobj_class_free">kobj_class_free</code></a>()
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 <a class="Xr">malloc(9)</a> and <a class="Xr">mutex(9)</a>
are initialised, then <code class="Fn">kobj_class_compile_static</code>()
should be called with the class and a pointer to a statically allocated
<var class="Vt">kobj_ops</var> structure before the class is used to
initialise any objects. In that case, also
<code class="Fn">kobj_init_static</code>() should be used instead of
<code class="Fn">kobj_init</code>().</p>
<p class="Pp" id="KOBJMETHOD">To define a class, first define a simple array of
<var class="Vt">kobj_method_t</var>. Each method which the class implements
should be entered into the table using the macro
<a class="permalink" href="#KOBJMETHOD"><code class="Fn">KOBJMETHOD</code></a>()
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
<a class="permalink" href="#DEFINE_CLASS"><code class="Fn" id="DEFINE_CLASS">DEFINE_CLASS</code></a>()
can then be used to initialise a <var class="Vt">kobj_class_t</var>
structure. The size argument to <code class="Fn">DEFINE_CLASS</code>()
specifies how much memory should be allocated for each object.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">Some of the concepts for this interface appeared in the device
framework used for the alpha port of <span class="Ux">FreeBSD 3.0</span> and
more widely in <span class="Ux">FreeBSD 4.0</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">This manual page was written by <span class="An">Doug
Rabson</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">November 14, 2011</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
