1135446Strhodes/*
2193149Sdougb * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
3135446Strhodes * Copyright (C) 2000, 2001  Internet Software Consortium.
4135446Strhodes *
5193149Sdougb * Permission to use, copy, modify, and/or distribute this software for any
6135446Strhodes * purpose with or without fee is hereby granted, provided that the above
7135446Strhodes * copyright notice and this permission notice appear in all copies.
8135446Strhodes *
9135446Strhodes * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10135446Strhodes * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11135446Strhodes * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12135446Strhodes * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13135446Strhodes * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14135446Strhodes * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15135446Strhodes * PERFORMANCE OF THIS SOFTWARE.
16135446Strhodes */
17135446Strhodes
18234010Sdougb/* $Id: ondestroy.h,v 1.14 2007/06/19 23:47:18 tbox Exp $ */
19135446Strhodes
20135446Strhodes#ifndef ISC_ONDESTROY_H
21135446Strhodes#define ISC_ONDESTROY_H 1
22135446Strhodes
23135446Strhodes#include <isc/lang.h>
24135446Strhodes#include <isc/types.h>
25135446Strhodes
26135446StrhodesISC_LANG_BEGINDECLS
27135446Strhodes
28193149Sdougb/*! \file isc/ondestroy.h
29135446Strhodes * ondestroy handling.
30135446Strhodes *
31135446Strhodes * Any class ``X'' of objects that wants to send out notifications
32135446Strhodes * on its destruction should declare a field of type isc_ondestroy_t
33135446Strhodes * (call it 'ondest').
34135446Strhodes *
35170222Sdougb * \code
36135446Strhodes * 	typedef struct {
37135446Strhodes * 		...
38135446Strhodes * 		isc_ondestroy_t	ondest;
39135446Strhodes * 		...
40135446Strhodes * 	} X;
41170222Sdougb * \endcode
42135446Strhodes *
43135446Strhodes * When an object ``A'' of type X is created
44135446Strhodes * it must initialize the field ondest with a call to
45135446Strhodes *
46170222Sdougb * \code
47135446Strhodes * 	isc_ondestroy_init(&A->ondest).
48170222Sdougb * \endcode
49135446Strhodes *
50135446Strhodes * X should also provide a registration function for third-party
51135446Strhodes * objects to call to register their interest in being told about
52135446Strhodes * the destruction of a particular instance of X.
53135446Strhodes *
54170222Sdougb * \code
55135446Strhodes *	isc_result_t
56135446Strhodes * 	X_ondestroy(X *instance, isc_task_t *task,
57135446Strhodes * 		     isc_event_t **eventp) {
58135446Strhodes * 		return(isc_ondestroy_register(&instance->ondest, task,eventp));
59135446Strhodes * 	}
60170222Sdougb * \endcode
61135446Strhodes *
62135446Strhodes *	Note: locking of the ondestory structure embedded inside of X, is
63135446Strhodes * 	X's responsibility.
64135446Strhodes *
65135446Strhodes * When an instance of X is destroyed, a call to  isc_ondestroy_notify()
66135446Strhodes * sends the notifications:
67135446Strhodes *
68170222Sdougb * \code
69135446Strhodes *	X *instance;
70135446Strhodes *	isc_ondestroy_t ondest = instance->ondest;
71135446Strhodes *
72135446Strhodes *	... completely cleanup 'instance' here...
73135446Strhodes *
74135446Strhodes * 	isc_ondestroy_notify(&ondest, instance);
75170222Sdougb * \endcode
76135446Strhodes *
77135446Strhodes *
78170222Sdougb * see lib/dns/zone.c for an ifdef'd-out example.
79135446Strhodes */
80135446Strhodes
81135446Strhodesstruct isc_ondestroy {
82135446Strhodes	unsigned int magic;
83135446Strhodes	isc_eventlist_t events;
84135446Strhodes};
85135446Strhodes
86135446Strhodesvoid
87135446Strhodesisc_ondestroy_init(isc_ondestroy_t *ondest);
88170222Sdougb/*%<
89135446Strhodes * Initialize the on ondest structure. *must* be called before first call
90135446Strhodes * to isc_ondestroy_register().
91135446Strhodes */
92135446Strhodes
93135446Strhodesisc_result_t
94135446Strhodesisc_ondestroy_register(isc_ondestroy_t *ondest, isc_task_t *task,
95135446Strhodes		       isc_event_t **eventp);
96135446Strhodes
97170222Sdougb/*%<
98135446Strhodes * Stores task and *eventp away inside *ondest.  Ownership of **event is
99135446Strhodes * taken from the caller (and *eventp is set to NULL). The task is attached
100135446Strhodes * to.
101135446Strhodes */
102135446Strhodes
103135446Strhodesvoid
104135446Strhodesisc_ondestroy_notify(isc_ondestroy_t *ondest, void *sender);
105170222Sdougb/*%<
106135446Strhodes * Dispatches the event(s) to the task(s) that were given in
107135446Strhodes * isc_ondestroy_register call(s) (done via calls to
108135446Strhodes * isc_task_sendanddetach()).  Before dispatch, the sender value of each
109135446Strhodes * event structure is set to the value of the sender paramater. The
110135446Strhodes * internal structures of the ondest parameter are cleaned out, so no other
111135446Strhodes * cleanup is needed.
112135446Strhodes */
113135446Strhodes
114135446StrhodesISC_LANG_ENDDECLS
115135446Strhodes
116135446Strhodes#endif /* ISC_ONDESTROY_H */
117