contrib/bind-9.2.4rc7/lib/isc/include/isc/ondestroy.h

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and 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.7.2.1 2004/03/09 06:11:59 marka 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 /*
  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  *      typedef struct {
  36  *              ...
  37  *              isc_ondestroy_t ondest;
  38  *              ...
  39  *      } X;
  40  *
  41  * When an object ``A'' of type X is created
  42  * it must initialize the field ondest with a call to
  43  *
  44  *      isc_ondestroy_init(&A->ondest).
  45  *
  46  * X should also provide a registration function for third-party
  47  * objects to call to register their interest in being told about
  48  * the destruction of a particular instance of X.
  49  *
  50  *      isc_result_t
  51  *      X_ondestroy(X *instance, isc_task_t *task,
  52  *                   isc_event_t **eventp) {
  53  *              return(isc_ondestroy_register(&instance->ondest, task,eventp));
  54  *      }
  55  *
  56  *      Note: locking of the ondestory structure embedded inside of X, is
  57  *      X's responsibility.
  58  *
  59  * When an instance of X is destroyed, a call to  isc_ondestroy_notify()
  60  * sends the notifications:
  61  *
  62  *      X *instance;
  63  *      isc_ondestroy_t ondest = instance->ondest;
  64  *
  65  *      ... completely cleanup 'instance' here...
  66  *
  67  *      isc_ondestroy_notify(&ondest, instance);
  68  *
  69  *
  70  * see dns/zone.c for an ifdef'd-out example.
  71  */
  72
  73 struct isc_ondestroy {
  74         unsigned int magic;
  75         isc_eventlist_t events;
  76 };
  77
  78 void
  79 isc_ondestroy_init(isc_ondestroy_t *ondest);
  80 /*
  81  * Initialize the on ondest structure. *must* be called before first call
  82  * to isc_ondestroy_register().
  83  */
  84
  85 isc_result_t
  86 isc_ondestroy_register(isc_ondestroy_t *ondest, isc_task_t *task,
  87                        isc_event_t **eventp);
  88
  89 /*
  90  * Stores task and *eventp away inside *ondest.  Ownership of **event is
  91  * taken from the caller (and *eventp is set to NULL). The task is attached
  92  * to.
  93  */
  94
  95 void
  96 isc_ondestroy_notify(isc_ondestroy_t *ondest, void *sender);
  97 /*
  98  * Dispatches the event(s) to the task(s) that were given in
  99  * isc_ondestroy_register call(s) (done via calls to
 100  * isc_task_sendanddetach()).  Before dispatch, the sender value of each
 101  * event structure is set to the value of the sender paramater. The
 102  * internal structures of the ondest parameter are cleaned out, so no other
 103  * cleanup is needed.
 104  */
 105
 106 ISC_LANG_ENDDECLS
 107
 108 #endif /* ISC_ONDESTROY_H */