1/*	$NetBSD: ondestroy.h,v 1.6 2020/05/25 20:47:21 christos Exp $	*/
2
3/*
4 * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
5 * Copyright (C) 2000, 2001  Internet Software Consortium.
6 *
7 * Permission to use, copy, modify, and/or distribute this software for any
8 * purpose with or without fee is hereby granted, provided that the above
9 * copyright notice and this permission notice appear in all copies.
10 *
11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
13 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17 * PERFORMANCE OF THIS SOFTWARE.
18 */
19
20/* Id: ondestroy.h,v 1.14 2007/06/19 23:47:18 tbox Exp  */
21
22#ifndef ISC_ONDESTROY_H
23#define ISC_ONDESTROY_H 1
24
25#include <isc/lang.h>
26#include <isc/types.h>
27
28ISC_LANG_BEGINDECLS
29
30/*! \file isc/ondestroy.h
31 * ondestroy handling.
32 *
33 * Any class ``X'' of objects that wants to send out notifications
34 * on its destruction should declare a field of type isc_ondestroy_t
35 * (call it 'ondest').
36 *
37 * \code
38 * 	typedef struct {
39 * 		...
40 * 		isc_ondestroy_t	ondest;
41 * 		...
42 * 	} X;
43 * \endcode
44 *
45 * When an object ``A'' of type X is created
46 * it must initialize the field ondest with a call to
47 *
48 * \code
49 * 	isc_ondestroy_init(&A->ondest).
50 * \endcode
51 *
52 * X should also provide a registration function for third-party
53 * objects to call to register their interest in being told about
54 * the destruction of a particular instance of X.
55 *
56 * \code
57 *	isc_result_t
58 * 	X_ondestroy(X *instance, isc_task_t *task,
59 * 		     isc_event_t **eventp) {
60 * 		return(isc_ondestroy_register(&instance->ondest, task,eventp));
61 * 	}
62 * \endcode
63 *
64 *	Note: locking of the ondestory structure embedded inside of X, is
65 * 	X's responsibility.
66 *
67 * When an instance of X is destroyed, a call to  isc_ondestroy_notify()
68 * sends the notifications:
69 *
70 * \code
71 *	X *instance;
72 *	isc_ondestroy_t ondest = instance->ondest;
73 *
74 *	... completely cleanup 'instance' here...
75 *
76 * 	isc_ondestroy_notify(&ondest, instance);
77 * \endcode
78 *
79 *
80 * see lib/dns/zone.c for an ifdef'd-out example.
81 */
82
83struct isc_ondestroy {
84	unsigned int magic;
85	isc_eventlist_t events;
86};
87
88void
89isc_ondestroy_init(isc_ondestroy_t *ondest);
90/*%<
91 * Initialize the on ondest structure. *must* be called before first call
92 * to isc_ondestroy_register().
93 */
94
95isc_result_t
96isc_ondestroy_register(isc_ondestroy_t *ondest, isc_task_t *task,
97		       isc_event_t **eventp);
98
99/*%<
100 * Stores task and *eventp away inside *ondest.  Ownership of **event is
101 * taken from the caller (and *eventp is set to NULL). The task is attached
102 * to.
103 */
104
105void
106isc_ondestroy_notify(isc_ondestroy_t *ondest, void *sender);
107/*%<
108 * Dispatches the event(s) to the task(s) that were given in
109 * isc_ondestroy_register call(s) (done via calls to
110 * isc_task_sendanddetach()).  Before dispatch, the sender value of each
111 * event structure is set to the value of the sender paramater. The
112 * internal structures of the ondest parameter are cleaned out, so no other
113 * cleanup is needed.
114 */
115
116ISC_LANG_ENDDECLS
117
118#endif /* ISC_ONDESTROY_H */
119