Annotation of embedaddon/libpdel/util/pevent.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: pevent.3,v 1.8 2004/06/02 17:24:39 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt PEVENT 3
42: .Os
43: .Sh NAME
44: .Nm pevent
45: .Nd pthread event library
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In pthread.h
50: .In pdel/util/pevent.h
51: .Ft "struct pevent_ctx *"
52: .Fn pevent_ctx_create "const char *mtype" "const pthread_attr_t *attr"
53: .Ft void
54: .Fn pevent_ctx_destroy "struct pevent_ctx **ctxp"
55: .Ft u_int
56: .Fn pevent_ctx_count "struct pevent_ctx *ctx"
57: .Ft int
58: .Fn pevent_register "struct pevent_ctx *ctx" "struct pevent **peventp" "int flags" "pthread_mutex_t *mutex" "pevent_handler_t *handler" "void *arg" "enum pevent_type type" "..."
59: .Ft void
60: .Fn pevent_unregister "struct pevent **eventp"
61: .Ft void
62: .Fn pevent_trigger "struct pevent *event"
63: .Ft int
64: .Fn pevent_get_info "struct pevent *event" "struct pevent_info *info"
65: .Sh DESCRIPTION
66: These functions support event-driven programming.
67: Event-driven programming is simpler and more efficient than threaded
68: programming because only a single thread is created to handle all
69: blocking operations, rather than a new thread per operation.
70: However, because the thread's stack cannot be used to store information
71: between events, each event must be handled to completion, i.e., the
72: event handlers must not block before returning.
73: .Pp
74: Event handlers that block may also be used with these routines, but only
75: if a separate thread is spawned for the handler (see below).
76: .\"
77: .Ss Event contexts
78: .\"
79: .Fn pevent_ctx_create
80: creates a new event context, which is used to register events.
81: All events registered with the same event context will be serviced by
82: the single thread associated with that event context.
83: .Pp
84: The scheduling attributes contained in
85: .Fa "*attr"
86: are used when creating this thread; if
87: .Fa attr
88: is
89: .Dv NULL
90: then the default thread attributes are used.
91: Since
92: .Fn pevent_ctx_create
93: makes a copy of these attributes,
94: .Fa attr
95: may be discarded when
96: .Fn pevent_ctx_create
97: returns.
98: .Pp
99: .Fa mtype
100: is the
101: .Xr typed_mem 3
102: memory type used when allocating memory for the event context.
103: .Pp
104: .Fn pevent_ctx_destroy
105: destroys an event context.
106: Any events still registered are automatically unregistered.
107: Upon return,
108: .Fa "*ctxp"
109: is set to
110: .Dv NULL .
111: If
112: .Fa "*ctxp"
113: is already
114: .Dv NULL
115: when
116: .Fn pevent_ctx_destroy
117: is invoked, nothing happens.
118: .Pp
119: It is safe to call
120: .Fn pevent_ctx_destroy
121: from within an event handler function.
122: .Pp
123: .Fn pevent_ctx_count
124: returns the number of events currently registered with
125: .Fa ctx .
126: .\"
127: .Ss Events
128: .\"
129: .Fn pevent_register
130: creates a new event and registers it with
131: .Fa ctx .
132: If successful, zero is returned and a non-
133: .Dv NULL
134: reference to the event is stored in
135: .Fa "*peventp" .
136: When
137: .Fn pevent_register
138: is invoked,
139: .Fa "*peventp"
140: must be
141: .Dv NULL
142: or else an error will be returned with
143: .Va errno
144: set to
145: .Er EBUSY .
146: If
147: .Fn pevent_register
148: returns an error,
149: .Fa "*peventp"
150: will be unmodified.
151: .Pp
152: .Fa handler
153: must point to a function having this type:
154: .Bd -literal -offset 3n
155: typedef void pevent_handler_t(void *arg);
156: .Ed
157: .Pp
158: When the event occurs,
159: .Fa "*peventp"
160: is set to
161: .Dv NULL
162: and then
163: .Fn handler arg
164: is invoked.
165: Therefore,
166: .Fa "*peventp"
167: is not equal to
168: .Dv NULL
169: if and only if the event is still pending.
170: For this to work,
171: .Fa "*peventp"
172: must remain valid and unmodified while the event is pending,
173: and the user code must initialize
174: .Fa peventp
175: to
176: .Dv NULL
177: before the first call to
178: .Fn pevent_register .
179: .Pp
180: The
181: .Fa type
182: and subsequent argument(s) define the event itself;
183: .Fa type
184: may have be one of the following values:
185: .Bl -tag -offset 3n -width PEVENT_MESG_PORT
186: .It Dv PEVENT_READ
187: Readable condition on a file descriptor.
188: The next argument must have type
189: .Li int .
190: .It Dv PEVENT_WRITE
191: Writable condition on a file descriptor.
192: The next argument must have type
193: .Li int .
194: .It Dv PEVENT_TIME
195: Time passage.
196: The next argument must have type
197: .Li int ,
198: and it is the relative time delay in milliseconds.
199: Negative delay values are silently converted to zero.
200: .It Dv PEVENT_MESG_PORT
201: Message(s) available on a message port.
202: The next argument must have type
203: .Li "struct mesg_port *".
204: .It Dv PEVENT_USER
205: User-triggered event.
206: No further arguments are required.
207: .El
208: .Pp
209: The
210: .Fa flags
211: parameter may contain any of the following values OR'd together:
212: .Pp
213: .Bl -tag -offset 3n -width PEVENT_OWN_THREADX
214: .It Li PEVENT_RECURRING
215: The event is recurring.
216: .It Li PEVENT_OWN_THREAD
217: Invoke
218: .Fn handler
219: in a separate thread.
220: .El
221: .Pp
222: .Dv PEVENT_RECURRING
223: causes the event to be automatically re-registered just before
224: each invocation of
225: .Fn handler .
226: In particular, this means that
227: .Fa "*peventp"
228: will not be
229: .Dv NULL
230: when
231: .Fn handler
232: is invoked.
233: .Pp
234: .Dv PEVENT_OWN_THREAD
235: causes a new thread to be spawned for each invocation of
236: .Fn handler ;
237: this thread may block, exit, or be canceled, and is by default not joinable.
238: If this flag is not set,
239: .Fn handler
240: will execute in the event context's main thread, in which case
241: .Fn handler
242: .Em "must not"
243: block or exit and the thread
244: .Em "must not"
245: be canceled.
246: .Pp
247: .Fn pevent_unregister
248: unregisters the event referenced by
249: .Fa "*peventp" .
250: Upon return,
251: .Fa "*peventp"
252: is set to
253: .Dv NULL .
254: If
255: .Fa "*peventp"
256: is already
257: .Dv NULL
258: when
259: .Fn pevent_unregister
260: is invoked, nothing happens.
261: .Pp
262: .Fn pevent_trigger
263: manually triggers an event, causing its handler to be invoked.
264: Although intended for use with
265: .Dv PEVENT_USER
266: events, it will work with any event.
267: The
268: .Fa event
269: may be
270: .Dv NULL ,
271: in which case nothing happens.
272: .Pp
273: .Fn pevent_get_info
274: returns the type and parameters associated with
275: .Fa event
276: by filling in the
277: .Li "struct pevent_info"
278: structure pointed to by
279: .Fa info :
280: .Bd -literal -offset 3n
281: struct pevent_info {
282: enum pevent_type type; /* event type */
283: union {
284: int fd; /* file descriptor (READ, WRITE) */
285: int millis; /* delay in milliseconds (TIME) */
286: struct mesg_port *port; /* message port (MESG_PORT) */
287: }; u;
288: };
289: .Ed
290: .\"
291: .Ss Synchronization
292: .\"
293: .Fn pevent_ctx_count ,
294: .Fn pevent_register ,
295: .Fn pevent_unregister ,
296: .Fn pevent_trigger ,
297: and
298: .Fn pevent_get_info
299: may all safely be called from different threads simultaneously.
300: However, there are inherent race conditions between an event's
301: .Fn handler
302: being invoked and reading the value of
303: .Fa "*peventp"
304: or unregistering the event with
305: .Fn pevent_unregister .
306: The
307: .Fa mutex
308: parameter to
309: .Fn pevent_register
310: can be used to avoid these problems.
311: .Pp
312: If a non-
313: .Dv NULL
314: .Fa mutex
315: is provided to
316: .Fn pevent_register ,
317: then
318: .Nm pevent
319: will acquire
320: .Fa "*mutex"
321: just before setting
322: .Fa "*pevent"
323: to
324: .Dv NULL
325: and invoking
326: .Fn handler ,
327: and
328: .Fa "*mutex"
329: will be automatically released when
330: .Fn handler
331: returns (or, in the case of
332: .Dv PEVENT_OWN_THREAD ,
333: the handler thread exits by any means).
334: If the user code acquires this mutex before any calls to
335: .Fn pevent_register
336: or
337: .Fn pevent_unregister ,
338: or before accessing
339: .Fa "*eventp" ,
340: then
341: .Fa "*eventp"
342: will always reflect the 'registered' state of the event and
343: .Fn handler
344: is guaranteed to never be invoked after
345: .Fn pevent_unregister
346: returns.
347: .Sh RETURN VALUES
348: .Fn pevent_ctx_create ,
349: .Fn pevent_register ,
350: and
351: .Fn pevent_get_info
352: return
353: .Dv NULL
354: or -1 to indicate an error,
355: with
356: .Va errno
357: set appropriately.
358: .Sh SEE ALSO
359: .Xr libpdel 3 ,
360: .Xr mesg_port 3 ,
361: .Xr paction 3 ,
362: .Xr pthread 3 ,
363: .Xr typed_mem 3
364: .Sh HISTORY
365: The PDEL library was developed at Packet Design, LLC.
366: .Dv "http://www.packetdesign.com/"
367: .Sh AUTHORS
368: .An Archie Cobbs Aq archie@freebsd.org
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pevent.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