/contrib/bind9/lib/isc/include/isc/event.h

  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 */