1 /* $NetBSD: ondestroy.h,v 1.4 2014/12/10 04:38:00 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 28 ISC_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 83 struct isc_ondestroy { 84 unsigned int magic; 85 isc_eventlist_t events; 86 }; 87 88 void 89 isc_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 95 isc_result_t 96 isc_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 105 void 106 isc_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 116 ISC_LANG_ENDDECLS 117 118 #endif /* ISC_ONDESTROY_H */ 119