Annotation of embedaddon/libpdel/util/paction.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: paction.3,v 1.4 2004/06/02 17:24:39 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt PACTION 3
42: .Os
43: .Sh NAME
44: .Nm paction
45: .Nd actions in a separate thread
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In sys/types.h
50: .In pthread.h
51: .In pdel/util/paction.h
52: .Ft int
53: .Fn paction_start "struct paction **actionp" "pthread_mutex_t *mutex" "paction_handler_t *handler" "paction_finish_t *finish" "void *arg"
54: .Ft void
55: .Fn paction_cancel "struct paction **actionp"
56: .Sh DESCRIPTION
57: These functions provide support for
58: .Em actions ,
59: which are simply function invocations that happen in separate threads.
60: This is just a simplified API for spawning and cancelling threads with
61: built-in support for mutex locking and avoiding certain race conditions.
62: .Pp
63: .Fn paction_start
64: creates a new action and stores a pointer to the action, represented by a
65: .Li "struct paction" ,
66: in
67: .Fa "*actionp" .
68: The creation of an action results in
69: .Fn handler
70: being invoked in a new thread.
71: .Fn paction_cancel
72: cancels an action by canceling its associated thread.
73: In any case, when the action has completed,
74: .Fn finish
75: is invoked.
76: If the action was not canceled via
77: .Fn paction_cancel ,
78: then
79: .Fa "*mutex"
80: is acquired before
81: .Fn finish
82: is invoked and released afterward.
83: If
84: .Fn paction_cancel
85: was called, then the mutex is not acquired for
86: .Fn finish .
87: The
88: .Fa was_canceled
89: argument to
90: .Fn finish
91: reflects this.
92: .Pp
93: .Fa handler
94: and
95: .Fa finish
96: must be pointers to functions having these types:
97: .Pp
98: .Bd -literal -compact -offset 3n
99: typedef void paction_handler_t(void *arg);
100: typedef void paction_finish_t(void *arg, int was_canceled);
101: .Ed
102: .Pp
103: When
104: .Fn paction_start
105: is invoked,
106: .Fa "*actionp"
107: must be
108: .Dv NULL .
109: As long as the action is still in progress (i.e.,
110: .Fn finish
111: has not yet been invoked),
112: .Fa "*actionp"
113: will be non-NULL.
114: When the action completes or is canceled,
115: .Fa "*actionp"
116: is set to
117: .Dv NULL
118: again.
119: Therefore,
120: .Fa "*actionp"
121: must remain valid and unmodified for the duration of the action,
122: and can be used as an indicator of whether the action has completed.
123: .Pp
124: .Fn paction_cancel
125: cancels an outstanding action.
126: This results in the action thread being canceled at the next
127: cancellation point.
128: Therefore,
129: .Fn handler
130: may need to register thread cleanup hooks in order to free
131: any allocated resources in the case of cancellation.
132: Upon return,
133: .Fa "*actionp"
134: is set to
135: .Dv NULL .
136: If
137: .Fa "*actionp"
138: is already
139: .Dv NULL
140: when
141: .Fn paction_cancel
142: is invoked, nothing happens.
143: .Pp
144: In any case,
145: .Fn finish
146: is invoked when the action terminates.
147: There are two reasons for an action terminating:
148: either the action terminated normally, or
149: .Fn paction_cancel
150: was invoked.
151: If the action terminated normally,
152: .Fa "*mutex"
153: is locked,
154: .Fa "*actionp"
155: is set to
156: .Dv NULL ,
157: and
158: .Fn finish
159: is invoked with
160: .Fa was_canceled
161: set to zero.
162: When
163: .Fn finish
164: returns
165: .Fa *mutex
166: is unlocked.
167: .Pp
168: If the action was canceled by
169: .Fn paction_cancel ,
170: then neither
171: .Fa "mutex"
172: nor
173: .Fa "actionp"
174: are dereferenced;
175: .Fn final
176: is simply called with
177: .Fa was_canceled
178: set to non-zero.
179: Note that
180: .Fa "*actionp"
181: will have already been set to
182: .Dv NULL
183: previously by
184: .Fn paction_cancel .
185: .Pp
186: Cancelling the action thread directly via
187: .Xr pthread_cancel 3
188: is treated just as if
189: .Fn handler
190: returned early; i.e., the first case above.
191: .\"
192: .Ss Synchronization
193: .\"
194: There are inherent race conditions between an action's
195: .Fn finish
196: function being invoked and reading the value of
197: .Fa "*actionp"
198: or canceling the action with
199: .Fn paction_cancel .
200: The
201: .Fa "*mutex"
202: should be used to avoid these problems by using it to
203: protect
204: .Fa "*actionp" .
205: .Pp
206: The user code should acquire
207: .Fa "*mutex"
208: before calling
209: .Fn paction_start
210: or
211: .Fn paction_cancel ,
212: or before accessing
213: .Fa "*actionp" .
214: If this protocol is followed, then
215: .Fa "*actionp"
216: will be non-NULL if and only if the action is still pending, i.e.,
217: .Fn finish
218: has not yet been invoked.
219: In addition, the
220: .Fa was_canceled
221: argument will always be accurate, i.e., be non-zero if and only if
222: .Fn paction_cancel
223: was called to cancel the action.
224: .Pp
225: Finally,
226: .Fa "mutex"
227: and
228: .Fa "actionp"
229: will not be dereferenced after a call to
230: .Fn paction_cancel ,
231: so it is always safe to destroy the memory pointed to by
232: .Fa "mutex"
233: and
234: .Fa "actionp"
235: after calling
236: .Fn paction_cancel .
237: However,
238: .Fa arg
239: must remain valid until
240: .Fn finish
241: is invoked, which may occur
242: .Em after
243: .Fn paction_cancel
244: returns; alternatively,
245: .Fn finish
246: must not dereference
247: .Fa arg
248: if
249: .Fa was_canceled
250: is non-zero.
251: .Sh RETURN VALUES
252: .Fn paction_start
253: returns -1 if there is an error, with
254: .Va errno
255: set appropriately.
256: In particular, if
257: .Fa "*actionp"
258: is not equal to
259: .Dv NULL ,
260: then
261: .Va errno
262: will be set to
263: .Er EBUSY .
264: .Sh SEE ALSO
265: .Xr libpdel 3 ,
266: .Xr pevent 3 ,
267: .Xr pthread_cancel 3 ,
268: .Xr pthread_create 3
269: .Sh HISTORY
270: The PDEL library was developed at Packet Design, LLC.
271: .Dv "http://www.packetdesign.com/"
272: .Sh AUTHORS
273: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to paction.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