Annotation of embedaddon/libpdel/util/tinfo.3, revision 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