ioapic: Pass ioapic address to ioapic_{read,write}()
[dragonfly.git] / share / man / man9 / kref.9
1 .\"
2 .\" Copyright (c) 2010, The DragonFly Project.
3 .\"
4 .\" This software is derived from software contributed to the DragonFly Project
5 .\" by Venkatesh Srinivas <me@endeavour.zapto.org>.
6 .\"
7 .\" Permission to use, copy, modify, or distribute this software for any
8 .\" purpose with or without fee is hereby granted, provided that the above
9 .\" copyright notice and this permission notice appear in all copies.
10 .\"
11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR OTHER DAMAGES
15 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN
16 .\" ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF
17 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .\"
19 .Dd December 21, 2010
20 .Dt KREF 9
21 .Os
22 .Sh NAME
23 .Nm kref_init ,
24 .Nm kref_inc ,
25 .Nm kref_dec
26 .Nd lightweight reference counts
27 .Sh SYNOPSIS
28 .In sys/ref.h
29 .Ft void
30 .Fn kref_init "struct kref *ref" "int count"
31 .Ft void
32 .Fn kref_inc "struct kref *ref"
33 .Ft int
34 .Fn kref_dec "struct kref *ref" "void (*deconstruct)(void *, void *)" \
35 "void *priv1" "void *priv2"
36 .Sh DESCRIPTION
37 .Pp
38 Kref is a lightweight reference counting system applicable to many dynamically
39 allocated structures. The space overhead of a reference count is only one
40 machine word.
41 .Pp
42 The
43 .Fn kref_init
44 function initializes a reference to the value
45 .Fa count .
46 .Pp
47 The
48 .Fn kref_inc
49 function increments a reference atomically with respect to preemption and to
50 concurrent
51 .Fn kref_inc
52 calls.
53 .Pp
54 The
55 .Fn kref_dec
56 function decrements a reference atomically with respect to preemption and to
57 concurrent
58 .Fn kref_dec
59 calls. If the reference transitions from 1 to 0, the
60 .Fa deconstruct
61 function is called with
62 .Fa priv1
63 and
64 .Fa priv2
65 as arguments. The
66 .Fa deconstruct
67 argument may be NULL.
68 .Fn kref_dec
69 returns 0 if it sees a 1 to 0 transition, 1 otherwise.
70 .Sh NOTES
71 .Pp
72 An object cannot synchronize its own visibility. Therefore care must be taken
73 when interleaving calls to kref_inc and kref_dec; higher level synchronization
74 is often required.
75 .Sh EXAMPLE
76 Simple use of kref with a
77 .Xr kmalloc 9
78 allocated structure:
79 .Bd -literal
80 struct interesting {
81         int ctr;
82         struct kref ref;
83 };
84
85 struct interesting *thing = kmalloc(sizeof(struct interesting), M_DEVBUF);
86 /* Setup reference to 1 */
87 kref_init(&thing->ref, 1);
88
89 /* 1 -> 2 transition */
90 kref_inc(&thing->ref);
91
92 /* 2 -> 1 transition ; don't call deconstruct (kfree) */
93 kref_dec(&thing->ref, kfree, thing, M_DEVBUF);
94
95 /* 1 -> 0 transition, so call kfree to release thing */
96 kref_dec(&thing->ref, kfree, thing, M_DEVBUF);
97 .Ed
98 .Sh FILES
99 The kref implementation is in
100 .Pa /sys/kern/kern_ref.c .
101 .Sh HISTORY
102 kref first appeared in
103 .Dx 2.9 .