1/*
2 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1998-2002  Internet Software Consortium.
4 *
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
16 */
17
18/* $Id: event.h,v 1.34 2007/06/19 23:47:18 tbox Exp $ */
19
20#ifndef ISC_EVENT_H
21#define ISC_EVENT_H 1
22
23/*! \file isc/event.h */
24
25#include <isc/lang.h>
26#include <isc/types.h>
27
28/*****
29 ***** Events.
30 *****/
31
32typedef void (*isc_eventdestructor_t)(isc_event_t *);
33
34#define ISC_EVENT_COMMON(ltype)		\
35	size_t				ev_size; \
36	unsigned int			ev_attributes; \
37	void *				ev_tag; \
38	isc_eventtype_t			ev_type; \
39	isc_taskaction_t		ev_action; \
40	void *				ev_arg; \
41	void *				ev_sender; \
42	isc_eventdestructor_t		ev_destroy; \
43	void *				ev_destroy_arg; \
44	ISC_LINK(ltype)			ev_link
45
46/*%
47 * Attributes matching a mask of 0x000000ff are reserved for the task library's
48 * definition.  Attributes of 0xffffff00 may be used by the application
49 * or non-ISC libraries.
50 */
51#define ISC_EVENTATTR_NOPURGE		0x00000001
52
53/*%
54 * The ISC_EVENTATTR_CANCELED attribute is intended to indicate
55 * that an event is delivered as a result of a canceled operation
56 * rather than successful completion, by mutual agreement
57 * between the sender and receiver.  It is not set or used by
58 * the task system.
59 */
60#define ISC_EVENTATTR_CANCELED		0x00000002
61
62#define ISC_EVENT_INIT(event, sz, at, ta, ty, ac, ar, sn, df, da) \
63do { \
64	(event)->ev_size = (sz); \
65	(event)->ev_attributes = (at); \
66	(event)->ev_tag = (ta); \
67	(event)->ev_type = (ty); \
68	(event)->ev_action = (ac); \
69	(event)->ev_arg = (ar); \
70	(event)->ev_sender = (sn); \
71	(event)->ev_destroy = (df); \
72	(event)->ev_destroy_arg = (da); \
73	ISC_LINK_INIT((event), ev_link); \
74} while (0)
75
76/*%
77 * This structure is public because "subclassing" it may be useful when
78 * defining new event types.
79 */
80struct isc_event {
81	ISC_EVENT_COMMON(struct isc_event);
82};
83
84#define ISC_EVENTTYPE_FIRSTEVENT	0x00000000
85#define ISC_EVENTTYPE_LASTEVENT		0xffffffff
86
87#define ISC_EVENT_PTR(p) ((isc_event_t **)(void *)(p))
88
89ISC_LANG_BEGINDECLS
90
91isc_event_t *
92isc_event_allocate(isc_mem_t *mctx, void *sender, isc_eventtype_t type,
93		   isc_taskaction_t action, const void *arg, size_t size);
94/*%<
95 * Allocate an event structure.
96 *
97 * Allocate and initialize in a structure with initial elements
98 * defined by:
99 *
100 * \code
101 *	struct {
102 *		ISC_EVENT_COMMON(struct isc_event);
103 *		...
104 *	};
105 * \endcode
106 *
107 * Requires:
108 *\li	'size' >= sizeof(struct isc_event)
109 *\li	'action' to be non NULL
110 *
111 * Returns:
112 *\li	a pointer to a initialized structure of the requested size.
113 *\li	NULL if unable to allocate memory.
114 */
115
116void
117isc_event_free(isc_event_t **);
118
119ISC_LANG_ENDDECLS
120
121#endif /* ISC_EVENT_H */
122