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