dist/ntp/include/isc/app.h

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