Document the fact that a zeroed-out refcounted object will behave in
[people/dverkamp/gpxe.git] / src / include / gpxe / refcnt.h
1 #ifndef _GPXE_REFCNT_H
2 #define _GPXE_REFCNT_H
3
4 /** @file
5  *
6  * Reference counting
7  *
8  */
9
10 /**
11  * A reference counter
12  *
13  * This data structure is designed to be embedded within a
14  * reference-counted object.
15  *
16  * Reference-counted objects are freed when their reference count
17  * drops below zero.  This means that a freshly allocated-and-zeroed
18  * reference-counted object will be freed on the first call to
19  * ref_put().
20  */
21 struct refcnt {
22         /** Current reference count
23          *
24          * When this count is decremented below zero, the free()
25          * method will be called.
26          */
27         int refcnt;
28         /** Free containing object
29          *
30          * This method is called when the reference count is
31          * decremented below zero.
32          *
33          * If this method is left NULL, the standard library free()
34          * function will be called.  The upshot of this is that you
35          * may omit the free() method if the @c refcnt object is the
36          * first element of your reference-counted struct.
37          */
38         void ( * free ) ( struct refcnt *refcnt );
39 };
40
41 extern void ref_get ( struct refcnt *refcnt );
42 extern void ref_put ( struct refcnt *refcnt );
43
44 #endif /* _GPXE_REFCNT_H */