Home | History | Annotate | Line # | Download | only in isc 
      1 /*	$NetBSD: ondestroy.h,v 1.2 2024/08/18 20:47:14 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