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 26 ISC_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 81 struct isc_ondestroy { 82 unsigned int magic; 83 isc_eventlist_t events; 84 }; 85 86 void 87 isc_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 93 isc_result_t 94 isc_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 103 void 104 isc_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 114 ISC_LANG_ENDDECLS 115 116 #endif /* ISC_ONDESTROY_H */ 117