Annotation of embedaddon/libpdel/util/tinfo.3, revision 1.1.1.1
1.1 misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
2: .\" All rights reserved.
3: .\"
4: .\" Subject to the following obligations and disclaimer of warranty,
5: .\" use and redistribution of this software, in source or object code
6: .\" forms, with or without modifications are expressly permitted by
7: .\" Packet Design; provided, however, that:
8: .\"
9: .\" (i) Any and all reproductions of the source or object code
10: .\" must include the copyright notice above and the following
11: .\" disclaimer of warranties; and
12: .\" (ii) No rights are granted, in any manner or form, to use
13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
14: .\" on advertising, endorsements, or otherwise except as such
15: .\" appears in the above copyright notice or in the software.
16: .\"
17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
34: .\" THE POSSIBILITY OF SUCH DAMAGE.
35: .\"
36: .\" Author: Archie Cobbs <archie@freebsd.org>
37: .\"
38: .\" $Id: tinfo.3,v 1.6 2004/06/02 17:24:39 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt TINFO 3
42: .Os
43: .Sh NAME
44: .Nm tinfo
45: .Nd self-(de)allocating thread-local data structures
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In pthread.h
50: .In pdel/util/tinfo.h
51: .Fn TINFO_INIT type mtype initfunc
52: .Ft "void *"
53: .Fn tinfo_get "struct tinfo *t"
54: .Ft "int"
55: .Fn tinfo_set "struct tinfo *t" "const void *data"
56: .Ft "int"
57: .Fn tinfo_set_nocopy "struct tinfo *t" "void *data"
58: .Sh DESCRIPTION
59: These functions provide support for thread-local data structures defined by
60: .Xr structs 3
61: types that are automatically initialized and destroyed.
62: A thread-local data structure is described by a static or global
63: .Li "struct tinfo" ;
64: each such structure must be initialized with the
65: .Fn TINFO_INIT
66: macro.
67: For example:
68: .Pp
69: .Bd -literal -compact -offset 3n
70: static struct tinfo foo_info
71: = TINFO_INIT(&foo_type, "foo", fooinit);
72: .Ed
73: .Pp
74: .Fa type
75: is the
76: .Xr structs 3
77: type for the data structure,
78: .Fa mtype
79: is the
80: .Xr typed_mem 3
81: type used to allocate memory to hold each thread's instance, and
82: .Fa initfunc
83: is an optional instance initializer function of this type:
84: .Pp
85: .Bd -literal -compact -offset 3n
86: typedef int tinfo_init_t(struct tinfo *t, void *data);
87: .Ed
88: .Pp
89: .Fn initfunc
90: should initialize the data structure pointed to by
91: .Fa data
92: as an instance of
93: .Fa type
94: (which will also be available as
95: .Fa "t->type") .
96: The memory pointed to by
97: .Fa data
98: will have been allocated with
99: .Xr typed_mem 3
100: type
101: .Fa mtype
102: but will be otherwise uninitialized.
103: If
104: .Fa initfunc
105: is
106: .Dv NULL ,
107: then
108: .Xr structs_init 3
109: is used to initialize the data structure to the default value defined by
110: .Fa type .
111: .Pp
112: Instances of
113: .Nm tinfo
114: thread-local data structure are automatically destroyed when the associated
115: thread exits, by calling
116: .Fn structs_free type NULL data
117: and then
118: .Fn FREE mtype data .
119: .Pp
120: .Fn tinfo_get
121: returns the current thread's instance of the data structure.
122: If this is the thread's first invocation of
123: .Fn tinfo_get ,
124: a new instance is automatically allocated and initialized.
125: The caller should
126: .En not
127: free the returned value, but may modify it in a way consistent
128: with its
129: .Xr structs 3
130: type.
131: .Pp
132: .Fn tinfo_set
133: sets the current thread's data structure instance to be a copy of
134: .Fa data ,
135: made using
136: .Xr structs_get 3 .
137: The original
138: .Fa data
139: is unmodified and remains the caller's responsibility to free.
140: Any existing thread-local data structure instance is automatically
141: replaced and freed.
142: .Pp
143: .Fn tinfo_set_nocopy
144: is equivalent to
145: .Fn tinfo_set
146: except that no copy of
147: .Fa data
148: is made; therefore,
149: .Fa data
150: must point to heap memory allocated with
151: .Xr typed_mem 3
152: type
153: .Fa "mtype"
154: (also available as
155: .Fa "t->mtype")
156: and the caller should not dereference
157: .Fa data
158: once
159: .Fn tinfo_set_nocopy
160: has returned successfully.
161: .Pp
162: Both
163: .Fn tinfo_set
164: and
165: .Fn tinfo_set_nocopy
166: may take a
167: .Dv NULL
168: .Fa data
169: parameter; this causes any existing thread-local data structure instance
170: to be freed so that the next call to
171: .Fn tinfo_get
172: will cause a new instance to be constructed.
173: .Sh RETURN VALUES
174: .Fn tinfo_get ,
175: .Fn tinfo_set ,
176: and
177: .Fn tinfo_set_nocopy
178: return
179: .Dv NULL
180: or -1 with
181: .Va errno
182: set appropriately to indicate an error.
183: .Sh SEE ALSO
184: .Xr libpdel 3 ,
185: .Xr structs 3 ,
186: .Xr typed_mem 3
187: .Sh HISTORY
188: The PDEL library was developed at Packet Design, LLC.
189: .Dv "http://www.packetdesign.com/"
190: .Sh AUTHORS
191: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to tinfo.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / util