contrib/bind-9.5.2/lib/isc/include/isc/ondestroy.h

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