1258945Sroberto/* 2258945Sroberto * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC") 3258945Sroberto * Copyright (C) 2000, 2001 Internet Software Consortium. 4258945Sroberto * 5258945Sroberto * Permission to use, copy, modify, and/or distribute this software for any 6258945Sroberto * purpose with or without fee is hereby granted, provided that the above 7258945Sroberto * copyright notice and this permission notice appear in all copies. 8258945Sroberto * 9258945Sroberto * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10258945Sroberto * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11258945Sroberto * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12258945Sroberto * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13258945Sroberto * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14258945Sroberto * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15258945Sroberto * PERFORMANCE OF THIS SOFTWARE. 16258945Sroberto */ 17258945Sroberto 18258945Sroberto/* $Id: ondestroy.h,v 1.14 2007/06/19 23:47:18 tbox Exp $ */ 19258945Sroberto 20258945Sroberto#ifndef ISC_ONDESTROY_H 21258945Sroberto#define ISC_ONDESTROY_H 1 22258945Sroberto 23258945Sroberto#include <isc/lang.h> 24258945Sroberto#include <isc/types.h> 25258945Sroberto 26258945SrobertoISC_LANG_BEGINDECLS 27258945Sroberto 28258945Sroberto/*! \file isc/ondestroy.h 29258945Sroberto * ondestroy handling. 30258945Sroberto * 31258945Sroberto * Any class ``X'' of objects that wants to send out notifications 32258945Sroberto * on its destruction should declare a field of type isc_ondestroy_t 33258945Sroberto * (call it 'ondest'). 34258945Sroberto * 35258945Sroberto * \code 36258945Sroberto * typedef struct { 37258945Sroberto * ... 38258945Sroberto * isc_ondestroy_t ondest; 39258945Sroberto * ... 40258945Sroberto * } X; 41258945Sroberto * \endcode 42258945Sroberto * 43258945Sroberto * When an object ``A'' of type X is created 44258945Sroberto * it must initialize the field ondest with a call to 45258945Sroberto * 46258945Sroberto * \code 47258945Sroberto * isc_ondestroy_init(&A->ondest). 48258945Sroberto * \endcode 49258945Sroberto * 50258945Sroberto * X should also provide a registration function for third-party 51258945Sroberto * objects to call to register their interest in being told about 52258945Sroberto * the destruction of a particular instance of X. 53258945Sroberto * 54258945Sroberto * \code 55258945Sroberto * isc_result_t 56258945Sroberto * X_ondestroy(X *instance, isc_task_t *task, 57258945Sroberto * isc_event_t **eventp) { 58258945Sroberto * return(isc_ondestroy_register(&instance->ondest, task,eventp)); 59258945Sroberto * } 60258945Sroberto * \endcode 61258945Sroberto * 62258945Sroberto * Note: locking of the ondestory structure embedded inside of X, is 63258945Sroberto * X's responsibility. 64258945Sroberto * 65258945Sroberto * When an instance of X is destroyed, a call to isc_ondestroy_notify() 66258945Sroberto * sends the notifications: 67258945Sroberto * 68258945Sroberto * \code 69258945Sroberto * X *instance; 70258945Sroberto * isc_ondestroy_t ondest = instance->ondest; 71258945Sroberto * 72258945Sroberto * ... completely cleanup 'instance' here... 73258945Sroberto * 74258945Sroberto * isc_ondestroy_notify(&ondest, instance); 75258945Sroberto * \endcode 76258945Sroberto * 77258945Sroberto * 78258945Sroberto * see lib/dns/zone.c for an ifdef'd-out example. 79258945Sroberto */ 80258945Sroberto 81258945Srobertostruct isc_ondestroy { 82258945Sroberto unsigned int magic; 83258945Sroberto isc_eventlist_t events; 84258945Sroberto}; 85258945Sroberto 86258945Srobertovoid 87258945Srobertoisc_ondestroy_init(isc_ondestroy_t *ondest); 88258945Sroberto/*%< 89258945Sroberto * Initialize the on ondest structure. *must* be called before first call 90258945Sroberto * to isc_ondestroy_register(). 91258945Sroberto */ 92258945Sroberto 93258945Srobertoisc_result_t 94258945Srobertoisc_ondestroy_register(isc_ondestroy_t *ondest, isc_task_t *task, 95258945Sroberto isc_event_t **eventp); 96258945Sroberto 97258945Sroberto/*%< 98258945Sroberto * Stores task and *eventp away inside *ondest. Ownership of **event is 99258945Sroberto * taken from the caller (and *eventp is set to NULL). The task is attached 100258945Sroberto * to. 101258945Sroberto */ 102258945Sroberto 103258945Srobertovoid 104258945Srobertoisc_ondestroy_notify(isc_ondestroy_t *ondest, void *sender); 105258945Sroberto/*%< 106258945Sroberto * Dispatches the event(s) to the task(s) that were given in 107258945Sroberto * isc_ondestroy_register call(s) (done via calls to 108258945Sroberto * isc_task_sendanddetach()). Before dispatch, the sender value of each 109258945Sroberto * event structure is set to the value of the sender paramater. The 110258945Sroberto * internal structures of the ondest parameter are cleaned out, so no other 111258945Sroberto * cleanup is needed. 112258945Sroberto */ 113258945Sroberto 114258945SrobertoISC_LANG_ENDDECLS 115258945Sroberto 116258945Sroberto#endif /* ISC_ONDESTROY_H */ 117