1/*
2 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 2000, 2001  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: ondestroy.h,v 1.14 2007/06/19 23:47:18 tbox Exp $ */
19
20#ifndef ISC_ONDESTROY_H
21#define ISC_ONDESTROY_H 1
22
23#include <isc/lang.h>
24#include <isc/types.h>
25
26ISC_LANG_BEGINDECLS
27
28/*! \file isc/ondestroy.h
29 * ondestroy handling.
30 *
31 * Any class ``X'' of objects that wants to send out notifications
32 * on its destruction should declare a field of type isc_ondestroy_t
33 * (call it 'ondest').
34 *
35 * \code
36 * 	typedef struct {
37 * 		...
38 * 		isc_ondestroy_t	ondest;
39 * 		...
40 * 	} X;
41 * \endcode
42 *
43 * When an object ``A'' of type X is created
44 * it must initialize the field ondest with a call to
45 *
46 * \code
47 * 	isc_ondestroy_init(&A->ondest).
48 * \endcode
49 *
50 * X should also provide a registration function for third-party
51 * objects to call to register their interest in being told about
52 * the destruction of a particular instance of X.
53 *
54 * \code
55 *	isc_result_t
56 * 	X_ondestroy(X *instance, isc_task_t *task,
57 * 		     isc_event_t **eventp) {
58 * 		return(isc_ondestroy_register(&instance->ondest, task,eventp));
59 * 	}
60 * \endcode
61 *
62 *	Note: locking of the ondestory structure embedded inside of X, is
63 * 	X's responsibility.
64 *
65 * When an instance of X is destroyed, a call to  isc_ondestroy_notify()
66 * sends the notifications:
67 *
68 * \code
69 *	X *instance;
70 *	isc_ondestroy_t ondest = instance->ondest;
71 *
72 *	... completely cleanup 'instance' here...
73 *
74 * 	isc_ondestroy_notify(&ondest, instance);
75 * \endcode
76 *
77 *
78 * see lib/dns/zone.c for an ifdef'd-out example.
79 */
80
81struct isc_ondestroy {
82	unsigned int magic;
83	isc_eventlist_t events;
84};
85
86void
87isc_ondestroy_init(isc_ondestroy_t *ondest);
88/*%<
89 * Initialize the on ondest structure. *must* be called before first call
90 * to isc_ondestroy_register().
91 */
92
93isc_result_t
94isc_ondestroy_register(isc_ondestroy_t *ondest, isc_task_t *task,
95		       isc_event_t **eventp);
96
97/*%<
98 * Stores task and *eventp away inside *ondest.  Ownership of **event is
99 * taken from the caller (and *eventp is set to NULL). The task is attached
100 * to.
101 */
102
103void
104isc_ondestroy_notify(isc_ondestroy_t *ondest, void *sender);
105/*%<
106 * Dispatches the event(s) to the task(s) that were given in
107 * isc_ondestroy_register call(s) (done via calls to
108 * isc_task_sendanddetach()).  Before dispatch, the sender value of each
109 * event structure is set to the value of the sender paramater. The
110 * internal structures of the ondest parameter are cleaned out, so no other
111 * cleanup is needed.
112 */
113
114ISC_LANG_ENDDECLS
115
116#endif /* ISC_ONDESTROY_H */
117