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