contrib/bind9/lib/isc/include/isc/app.h

   1 /*
   2  * Copyright (C) 2004-2007, 2009, 2013  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.11 2009/09/02 23:48:03 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  * This module also supports per-thread 'application contexts'.  With this
  58  * mode, a thread-based application will have a separate context, in which
  59  * it uses other ISC library services such as tasks or timers.  Signals are
  60  * not caught in this mode, so that the application can handle the signals
  61  * in its preferred way.
  62  *
  63  * \li MP:
  64  *      Clients must ensure that isc_app_start(), isc_app_run(), and
  65  *      isc_app_finish() are called at most once.  isc_app_shutdown()
  66  *      is safe to use by any thread (provided isc_app_start() has been
  67  *      called previously).
  68  *
  69  *      The same note applies to isc_app_ctxXXX() functions, but in this case
  70  *      it's a per-thread restriction.  For example, a thread with an
  71  *      application context must ensure that isc_app_ctxstart() with the
  72  *      context is called at most once.
  73  *
  74  * \li Reliability:
  75  *      No anticipated impact.
  76  *
  77  * \li Resources:
  78  *      None.
  79  *
  80  * \li Security:
  81  *      No anticipated impact.
  82  *
  83  * \li Standards:
  84  *      None.
  85  */
  86
  87 #include <isc/eventclass.h>
  88 #include <isc/lang.h>
  89 #include <isc/magic.h>
  90 #include <isc/result.h>
  91
  92 /***
  93  *** Types
  94  ***/
  95
  96 typedef isc_event_t isc_appevent_t;
  97
  98 #define ISC_APPEVENT_FIRSTEVENT         (ISC_EVENTCLASS_APP + 0)
  99 #define ISC_APPEVENT_SHUTDOWN           (ISC_EVENTCLASS_APP + 1)
 100 #define ISC_APPEVENT_LASTEVENT          (ISC_EVENTCLASS_APP + 65535)
 101
 102 /*%
 103  * app module methods.  Only app driver implementations use this structure.
 104  * Other clients should use the top-level interfaces (i.e., isc_app_xxx
 105  * functions).  magic must be ISCAPI_APPMETHODS_MAGIC.
 106  */
 107 typedef struct isc_appmethods {
 108         void            (*ctxdestroy)(isc_appctx_t **ctxp);
 109         isc_result_t    (*ctxstart)(isc_appctx_t *ctx);
 110         isc_result_t    (*ctxrun)(isc_appctx_t *ctx);
 111         isc_result_t    (*ctxsuspend)(isc_appctx_t *ctx);
 112         isc_result_t    (*ctxshutdown)(isc_appctx_t *ctx);
 113         void            (*ctxfinish)(isc_appctx_t *ctx);
 114         void            (*settaskmgr)(isc_appctx_t *ctx,
 115                                       isc_taskmgr_t *timermgr);
 116         void            (*setsocketmgr)(isc_appctx_t *ctx,
 117                                         isc_socketmgr_t *timermgr);
 118         void            (*settimermgr)(isc_appctx_t *ctx,
 119                                        isc_timermgr_t *timermgr);
 120         isc_result_t    (*ctxonrun)(isc_appctx_t *ctx, isc_mem_t *mctx,
 121                                     isc_task_t *task, isc_taskaction_t action,
 122                                     void *arg);
 123 } isc_appmethods_t;
 124
 125 /*%
 126  * This structure is actually just the common prefix of an application context
 127  * implementation's version of an isc_appctx_t.
 128  * \brief
 129  * Direct use of this structure by clients is forbidden.  app implementations
 130  * may change the structure.  'magic' must be ISCAPI_APPCTX_MAGIC for any
 131  * of the isc_app_ routines to work.  app implementations must maintain
 132  * all app context invariants.
 133  */
 134 struct isc_appctx {
 135         unsigned int            impmagic;
 136         unsigned int            magic;
 137         isc_appmethods_t        *methods;
 138 };
 139
 140 #define ISCAPI_APPCTX_MAGIC             ISC_MAGIC('A','a','p','c')
 141 #define ISCAPI_APPCTX_VALID(c)          ((c) != NULL && \
 142                                          (c)->magic == ISCAPI_APPCTX_MAGIC)
 143
 144 ISC_LANG_BEGINDECLS
 145
 146 isc_result_t
 147 isc_app_ctxstart(isc_appctx_t *ctx);
 148
 149 isc_result_t
 150 isc_app_start(void);
 151 /*!<
 152  * \brief Start an ISC library application.
 153  *
 154  * Notes:
 155  *      This call should be made before any other ISC library call, and as
 156  *      close to the beginning of the application as possible.
 157  *
 158  * Requires:
 159  *\li   'ctx' is a valid application context (for app_ctxstart()).
 160  */
 161
 162 isc_result_t
 163 isc_app_ctxonrun(isc_appctx_t *ctx, isc_mem_t *mctx, isc_task_t *task,
 164                  isc_taskaction_t action, void *arg);
 165 isc_result_t
 166 isc_app_onrun(isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action,
 167               void *arg);
 168 /*!<
 169  * \brief Request delivery of an event when the application is run.
 170  *
 171  * Requires:
 172  *\li   isc_app_start() has been called.
 173  *\li   'ctx' is a valid application context (for app_ctxonrun()).
 174  *
 175  * Returns:
 176  *      ISC_R_SUCCESS
 177  *      ISC_R_NOMEMORY
 178  */
 179
 180 isc_result_t
 181 isc_app_ctxrun(isc_appctx_t *ctx);
 182
 183 isc_result_t
 184 isc_app_run(void);
 185 /*!<
 186  * \brief Run an ISC library application.
 187  *
 188  * Notes:
 189  *\li   The caller (typically the initial thread of an application) will
 190  *      block until shutdown is requested.  When the call returns, the
 191  *      caller should start shutting down the application.
 192  *
 193  * Requires:
 194  *\li   isc_app_[ctx]start() has been called.
 195  *
 196  * Ensures:
 197  *\li   Any events requested via isc_app_onrun() will have been posted (in
 198  *      FIFO order) before isc_app_run() blocks.
 199  *\li   'ctx' is a valid application context (for app_ctxrun()).
 200  *
 201  * Returns:
 202  *\li   ISC_R_SUCCESS                   Shutdown has been requested.
 203  *\li   ISC_R_RELOAD                    Reload has been requested.
 204  */
 205
 206 isc_result_t
 207 isc_app_ctxshutdown(isc_appctx_t *ctx);
 208
 209 isc_result_t
 210 isc_app_shutdown(void);
 211 /*!<
 212  * \brief Request application shutdown.
 213  *
 214  * Notes:
 215  *\li   It is safe to call isc_app_shutdown() multiple times.  Shutdown will
 216  *      only be triggered once.
 217  *
 218  * Requires:
 219  *\li   isc_app_[ctx]run() has been called.
 220  *\li   'ctx' is a valid application context (for app_ctxshutdown()).
 221  *
 222  * Returns:
 223  *\li   ISC_R_SUCCESS
 224  *\li   ISC_R_UNEXPECTED
 225  */
 226
 227 isc_result_t
 228 isc_app_ctxsuspend(isc_appctx_t *ctx);
 229 /*!<
 230  * \brief This has the same behavior as isc_app_ctxsuspend().
 231  */
 232
 233 isc_result_t
 234 isc_app_reload(void);
 235 /*!<
 236  * \brief Request application reload.
 237  *
 238  * Requires:
 239  *\li   isc_app_run() has been called.
 240  *
 241  * Returns:
 242  *\li   ISC_R_SUCCESS
 243  *\li   ISC_R_UNEXPECTED
 244  */
 245
 246 void
 247 isc_app_ctxfinish(isc_appctx_t *ctx);
 248
 249 void
 250 isc_app_finish(void);
 251 /*!<
 252  * \brief Finish an ISC library application.
 253  *
 254  * Notes:
 255  *\li   This call should be made at or near the end of main().
 256  *
 257  * Requires:
 258  *\li   isc_app_start() has been called.
 259  *\li   'ctx' is a valid application context (for app_ctxfinish()).
 260  *
 261  * Ensures:
 262  *\li   Any resources allocated by isc_app_start() have been released.
 263  */
 264
 265 void
 266 isc_app_block(void);
 267 /*!<
 268  * \brief Indicate that a blocking operation will be performed.
 269  *
 270  * Notes:
 271  *\li   If a blocking operation is in process, a call to isc_app_shutdown()
 272  *      or an external signal will abort the program, rather than allowing
 273  *      clean shutdown.  This is primarily useful for reading user input.
 274  *
 275  * Requires:
 276  * \li  isc_app_start() has been called.
 277  * \li  No other blocking operations are in progress.
 278  */
 279
 280 void
 281 isc_app_unblock(void);
 282 /*!<
 283  * \brief Indicate that a blocking operation is complete.
 284  *
 285  * Notes:
 286  * \li  When a blocking operation has completed, return the program to a
 287  *      state where a call to isc_app_shutdown() or an external signal will
 288  *      shutdown normally.
 289  *
 290  * Requires:
 291  * \li  isc_app_start() has been called.
 292  * \li  isc_app_block() has been called by the same thread.
 293  */
 294
 295 isc_result_t
 296 isc_appctx_create(isc_mem_t *mctx, isc_appctx_t **ctxp);
 297 /*!<
 298  * \brief Create an application context.
 299  *
 300  * Requires:
 301  *\li   'mctx' is a valid memory context.
 302  *\li   'ctxp' != NULL && *ctxp == NULL.
 303  */
 304
 305 void
 306 isc_appctx_destroy(isc_appctx_t **ctxp);
 307 /*!<
 308  * \brief Destroy an application context.
 309  *
 310  * Requires:
 311  *\li   '*ctxp' is a valid application context.
 312  *
 313  * Ensures:
 314  *\li   *ctxp == NULL.
 315  */
 316
 317 void
 318 isc_appctx_settaskmgr(isc_appctx_t *ctx, isc_taskmgr_t *taskmgr);
 319 /*!<
 320  * \brief Associate a task manager with an application context.
 321  *
 322  * This must be done before running tasks within the application context.
 323  *
 324  * Requires:
 325  *\li   'ctx' is a valid application context.
 326  *\li   'taskmgr' is a valid task manager.
 327  */
 328
 329 void
 330 isc_appctx_setsocketmgr(isc_appctx_t *ctx, isc_socketmgr_t *socketmgr);
 331 /*!<
 332  * \brief Associate a socket manager with an application context.
 333  *
 334  * This must be done before handling socket events within the application
 335  * context.
 336  *
 337  * Requires:
 338  *\li   'ctx' is a valid application context.
 339  *\li   'socketmgr' is a valid socket manager.
 340  */
 341
 342 void
 343 isc_appctx_settimermgr(isc_appctx_t *ctx, isc_timermgr_t *timermgr);
 344 /*!<
 345  * \brief Associate a socket timer with an application context.
 346  *
 347  * This must be done before handling timer events within the application
 348  * context.
 349  *
 350  * Requires:
 351  *\li   'ctx' is a valid application context.
 352  *\li   'timermgr' is a valid timer manager.
 353  */
 354
 355 #ifdef USE_APPIMPREGISTER
 356 /*%<
 357  * See isc_appctx_create() above.
 358  */
 359 typedef isc_result_t
 360 (*isc_appctxcreatefunc_t)(isc_mem_t *mctx, isc_appctx_t **ctxp);
 361
 362 isc_result_t
 363 isc_app_register(isc_appctxcreatefunc_t createfunc);
 364 /*%<
 365  * Register a new application implementation and add it to the list of
 366  * supported implementations.  This function must be called when a different
 367  * event library is used than the one contained in the ISC library.
 368  */
 369
 370 isc_result_t
 371 isc__app_register(void);
 372 /*%<
 373  * A short cut function that specifies the application module in the ISC
 374  * library for isc_app_register().  An application that uses the ISC library
 375  * usually do not have to care about this function: it would call
 376  * isc_lib_register(), which internally calls this function.
 377  */
 378 #endif /* USE_APPIMPREGISTER */
 379
 380 ISC_LANG_ENDDECLS
 381
 382 #endif /* ISC_APP_H */