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

   1 /*
   2  * Copyright (C) 2004-2007  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-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: app.h,v 1.8 2007/06/19 23:47:18 tbox Exp $ */
  19
  20 #ifndef ISC_APP_H
  21 #define ISC_APP_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file isc/app.h
  28  * \brief ISC Application Support
  29  *
  30  * Dealing with program termination can be difficult, especially in a
  31  * multithreaded program.  The routines in this module help coordinate
  32  * the shutdown process.  They are used as follows by the initial (main)
  33  * thread of the application:
  34  *
  35  *\li           isc_app_start();        Call very early in main(), before
  36  *                                      any other threads have been created.
  37  *
  38  *\li           isc_app_run();          This will post any on-run events,
  39  *                                      and then block until application
  40  *                                      shutdown is requested.  A shutdown
  41  *                                      request is made by calling
  42  *                                      isc_app_shutdown(), or by sending
  43  *                                      SIGINT or SIGTERM to the process.
  44  *                                      After isc_app_run() returns, the
  45  *                                      application should shutdown itself.
  46  *
  47  *\li           isc_app_finish();       Call very late in main().
  48  *
  49  * Applications that want to use SIGHUP/isc_app_reload() to trigger reloading
  50  * should check the result of isc_app_run() and call the reload routine if
  51  * the result is ISC_R_RELOAD.  They should then call isc_app_run() again
  52  * to resume waiting for reload or termination.
  53  *
  54  * Use of this module is not required.  In particular, isc_app_start() is
  55  * NOT an ISC library initialization routine.
  56  *
  57  * \li MP:
  58  *      Clients must ensure that isc_app_start(), isc_app_run(), and
  59  *      isc_app_finish() are called at most once.  isc_app_shutdown()
  60  *      is safe to use by any thread (provided isc_app_start() has been
  61  *      called previously).
  62  *
  63  * \li Reliability:
  64  *      No anticipated impact.
  65  *
  66  * \li Resources:
  67  *      None.
  68  *
  69  * \li Security:
  70  *      No anticipated impact.
  71  *
  72  * \li Standards:
  73  *      None.
  74  */
  75
  76 #include <isc/eventclass.h>
  77 #include <isc/lang.h>
  78 #include <isc/result.h>
  79
  80 typedef isc_event_t isc_appevent_t;
  81
  82 #define ISC_APPEVENT_FIRSTEVENT         (ISC_EVENTCLASS_APP + 0)
  83 #define ISC_APPEVENT_SHUTDOWN           (ISC_EVENTCLASS_APP + 1)
  84 #define ISC_APPEVENT_LASTEVENT          (ISC_EVENTCLASS_APP + 65535)
  85
  86 ISC_LANG_BEGINDECLS
  87
  88 isc_result_t
  89 isc_app_start(void);
  90 /*!<
  91  * \brief Start an ISC library application.
  92  *
  93  * Notes:
  94  *      This call should be made before any other ISC library call, and as
  95  *      close to the beginning of the application as possible.
  96  */
  97
  98 isc_result_t
  99 isc_app_onrun(isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action,
 100               void *arg);
 101 /*!<
 102  * \brief Request delivery of an event when the application is run.
 103  *
 104  * Requires:
 105  *      isc_app_start() has been called.
 106  *
 107  * Returns:
 108  *      ISC_R_SUCCESS
 109  *      ISC_R_NOMEMORY
 110  */
 111
 112 isc_result_t
 113 isc_app_run(void);
 114 /*!<
 115  * \brief Run an ISC library application.
 116  *
 117  * Notes:
 118  *\li   The caller (typically the initial thread of an application) will
 119  *      block until shutdown is requested.  When the call returns, the
 120  *      caller should start shutting down the application.
 121  *
 122  * Requires:
 123  *\li   isc_app_start() has been called.
 124  *
 125  * Ensures:
 126  *\li   Any events requested via isc_app_onrun() will have been posted (in
 127  *      FIFO order) before isc_app_run() blocks.
 128  *
 129  * Returns:
 130  *\li   ISC_R_SUCCESS                   Shutdown has been requested.
 131  *\li   ISC_R_RELOAD                    Reload has been requested.
 132  */
 133
 134 isc_result_t
 135 isc_app_shutdown(void);
 136 /*!<
 137  * \brief Request application shutdown.
 138  *
 139  * Notes:
 140  *\li   It is safe to call isc_app_shutdown() multiple times.  Shutdown will
 141  *      only be triggered once.
 142  *
 143  * Requires:
 144  *\li   isc_app_run() has been called.
 145  *
 146  * Returns:
 147  *\li   ISC_R_SUCCESS
 148  *\li   ISC_R_UNEXPECTED
 149  */
 150
 151 isc_result_t
 152 isc_app_reload(void);
 153 /*!<
 154  * \brief Request application reload.
 155  *
 156  * Requires:
 157  *\li   isc_app_run() has been called.
 158  *
 159  * Returns:
 160  *\li   ISC_R_SUCCESS
 161  *\li   ISC_R_UNEXPECTED
 162  */
 163
 164 void
 165 isc_app_finish(void);
 166 /*!<
 167  * \brief Finish an ISC library application.
 168  *
 169  * Notes:
 170  *\li   This call should be made at or near the end of main().
 171  *
 172  * Requires:
 173  *\li   isc_app_start() has been called.
 174  *
 175  * Ensures:
 176  *\li   Any resources allocated by isc_app_start() have been released.
 177  */
 178
 179 void
 180 isc_app_block(void);
 181 /*!<
 182  * \brief Indicate that a blocking operation will be performed.
 183  *
 184  * Notes:
 185  *\li   If a blocking operation is in process, a call to isc_app_shutdown()
 186  *      or an external signal will abort the program, rather than allowing
 187  *      clean shutdown.  This is primarily useful for reading user input.
 188  *
 189  * Requires:
 190  * \li  isc_app_start() has been called.
 191  * \li  No other blocking operations are in progress.
 192  */
 193
 194 void
 195 isc_app_unblock(void);
 196 /*!<
 197  * \brief Indicate that a blocking operation is complete.
 198  *
 199  * Notes:
 200  * \li  When a blocking operation has completed, return the program to a
 201  *      state where a call to isc_app_shutdown() or an external signal will
 202  *      shutdown normally.
 203  *
 204  * Requires:
 205  * \li  isc_app_start() has been called.
 206  * \li  isc_app_block() has been called by the same thread.
 207  */
 208
 209
 210 ISC_LANG_ENDDECLS
 211
 212 #endif /* ISC_APP_H */