"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.16.7/lib/isc/include/isc/app.h" (4 Sep 2020, 7558 Bytes) of package /linux/misc/dns/bind9/9.16.7/bind-9.16.7.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "app.h" see the Fossies "Dox" file reference documentation.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 #ifndef ISC_APP_H
   13 #define ISC_APP_H 1
   14 
   15 /*****
   16 ***** Module Info
   17 *****/
   18 
   19 /*! \file isc/app.h
   20  * \brief ISC Application Support
   21  *
   22  * Dealing with program termination can be difficult, especially in a
   23  * multithreaded program.  The routines in this module help coordinate
   24  * the shutdown process.  They are used as follows by the initial (main)
   25  * thread of the application:
   26  *
   27  *\li       isc_app_start();    Call very early in main(), before
   28  *                  any other threads have been created.
   29  *
   30  *\li       isc_app_run();      This will post any on-run events,
   31  *                  and then block until application
   32  *                  shutdown is requested.  A shutdown
   33  *                  request is made by calling
   34  *                  isc_app_shutdown(), or by sending
   35  *                  SIGINT or SIGTERM to the process.
   36  *                  After isc_app_run() returns, the
   37  *                  application should shutdown itself.
   38  *
   39  *\li       isc_app_finish();   Call very late in main().
   40  *
   41  * Applications that want to use SIGHUP/isc_app_reload() to trigger reloading
   42  * should check the result of isc_app_run() and call the reload routine if
   43  * the result is ISC_R_RELOAD.  They should then call isc_app_run() again
   44  * to resume waiting for reload or termination.
   45  *
   46  * Use of this module is not required.  In particular, isc_app_start() is
   47  * NOT an ISC library initialization routine.
   48  *
   49  * This module also supports per-thread 'application contexts'.  With this
   50  * mode, a thread-based application will have a separate context, in which
   51  * it uses other ISC library services such as tasks or timers.  Signals are
   52  * not caught in this mode, so that the application can handle the signals
   53  * in its preferred way.
   54  *
   55  * \li MP:
   56  *  Clients must ensure that isc_app_start(), isc_app_run(), and
   57  *  isc_app_finish() are called at most once.  isc_app_shutdown()
   58  *  is safe to use by any thread (provided isc_app_start() has been
   59  *  called previously).
   60  *
   61  *  The same note applies to isc_app_ctxXXX() functions, but in this case
   62  *  it's a per-thread restriction.  For example, a thread with an
   63  *  application context must ensure that isc_app_ctxstart() with the
   64  *  context is called at most once.
   65  *
   66  * \li Reliability:
   67  *  No anticipated impact.
   68  *
   69  * \li Resources:
   70  *  None.
   71  *
   72  * \li Security:
   73  *  No anticipated impact.
   74  *
   75  * \li Standards:
   76  *  None.
   77  */
   78 
   79 #include <stdbool.h>
   80 
   81 #include <isc/eventclass.h>
   82 #include <isc/lang.h>
   83 #include <isc/magic.h>
   84 #include <isc/result.h>
   85 
   86 /***
   87  *** Types
   88  ***/
   89 
   90 typedef isc_event_t isc_appevent_t;
   91 
   92 #define ISC_APPEVENT_FIRSTEVENT (ISC_EVENTCLASS_APP + 0)
   93 #define ISC_APPEVENT_SHUTDOWN   (ISC_EVENTCLASS_APP + 1)
   94 #define ISC_APPEVENT_LASTEVENT  (ISC_EVENTCLASS_APP + 65535)
   95 
   96 /*%
   97  * This structure is actually just the common prefix of an application context
   98  * implementation's version of an isc_appctx_t.
   99  * \brief
  100  * Direct use of this structure by clients is forbidden.  app implementations
  101  * may change the structure.  'magic' must be ISCAPI_APPCTX_MAGIC for any
  102  * of the isc_app_ routines to work.  app implementations must maintain
  103  * all app context invariants.
  104  */
  105 struct isc_appctx;
  106 
  107 ISC_LANG_BEGINDECLS
  108 
  109 isc_result_t
  110 isc_app_ctxstart(isc_appctx_t *ctx);
  111 
  112 isc_result_t
  113 isc_app_start(void);
  114 /*!<
  115  * \brief Start an ISC library application.
  116  *
  117  * Notes:
  118  *  This call should be made before any other ISC library call, and as
  119  *  close to the beginning of the application as possible.
  120  *
  121  * Requires:
  122  *\li   'ctx' is a valid application context (for app_ctxstart()).
  123  */
  124 
  125 isc_result_t
  126 isc_app_ctxonrun(isc_appctx_t *ctx, isc_mem_t *mctx, isc_task_t *task,
  127          isc_taskaction_t action, void *arg);
  128 isc_result_t
  129 isc_app_onrun(isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action,
  130           void *arg);
  131 /*!<
  132  * \brief Request delivery of an event when the application is run.
  133  *
  134  * Requires:
  135  *\li   isc_app_start() has been called.
  136  *\li   'ctx' is a valid application context (for app_ctxonrun()).
  137  *
  138  * Returns:
  139  *  ISC_R_SUCCESS
  140  *  ISC_R_NOMEMORY
  141  */
  142 
  143 isc_result_t
  144 isc_app_ctxrun(isc_appctx_t *ctx);
  145 
  146 isc_result_t
  147 isc_app_run(void);
  148 /*!<
  149  * \brief Run an ISC library application.
  150  *
  151  * Notes:
  152  *\li   The caller (typically the initial thread of an application) will
  153  *  block until shutdown is requested.  When the call returns, the
  154  *  caller should start shutting down the application.
  155  *
  156  * Requires:
  157  *\li   isc_app_[ctx]start() has been called.
  158  *
  159  * Ensures:
  160  *\li   Any events requested via isc_app_onrun() will have been posted (in
  161  *  FIFO order) before isc_app_run() blocks.
  162  *\li   'ctx' is a valid application context (for app_ctxrun()).
  163  *
  164  * Returns:
  165  *\li   ISC_R_SUCCESS           Shutdown has been requested.
  166  *\li   ISC_R_RELOAD            Reload has been requested.
  167  */
  168 
  169 bool
  170 isc_app_isrunning(void);
  171 /*!<
  172  * \brief Return if the ISC library application is running.
  173  *
  174  * Returns:
  175  *\li   true    App is running.
  176  *\li   false   App is not running.
  177  */
  178 
  179 void
  180 isc_app_ctxshutdown(isc_appctx_t *ctx);
  181 
  182 void
  183 isc_app_shutdown(void);
  184 /*!<
  185  * \brief Request application shutdown.
  186  *
  187  * Notes:
  188  *\li   It is safe to call isc_app_shutdown() multiple times.  Shutdown will
  189  *  only be triggered once.
  190  *
  191  * Requires:
  192  *\li   isc_app_[ctx]run() has been called.
  193  *\li   'ctx' is a valid application context (for app_ctxshutdown()).
  194  *
  195  * Returns:
  196  *\li   ISC_R_SUCCESS
  197  *\li   ISC_R_UNEXPECTED
  198  */
  199 
  200 void
  201 isc_app_ctxsuspend(isc_appctx_t *ctx);
  202 /*!<
  203  * \brief This has the same behavior as isc_app_ctxsuspend().
  204  */
  205 
  206 void
  207 isc_app_reload(void);
  208 /*!<
  209  * \brief Request application reload.
  210  *
  211  * Requires:
  212  *\li   isc_app_run() has been called.
  213  *
  214  * Returns:
  215  *\li   ISC_R_SUCCESS
  216  *\li   ISC_R_UNEXPECTED
  217  */
  218 
  219 void
  220 isc_app_ctxfinish(isc_appctx_t *ctx);
  221 
  222 void
  223 isc_app_finish(void);
  224 /*!<
  225  * \brief Finish an ISC library application.
  226  *
  227  * Notes:
  228  *\li   This call should be made at or near the end of main().
  229  *
  230  * Requires:
  231  *\li   isc_app_start() has been called.
  232  *\li   'ctx' is a valid application context (for app_ctxfinish()).
  233  *
  234  * Ensures:
  235  *\li   Any resources allocated by isc_app_start() have been released.
  236  */
  237 
  238 void
  239 isc_app_block(void);
  240 /*!<
  241  * \brief Indicate that a blocking operation will be performed.
  242  *
  243  * Notes:
  244  *\li   If a blocking operation is in process, a call to isc_app_shutdown()
  245  *  or an external signal will abort the program, rather than allowing
  246  *  clean shutdown.  This is primarily useful for reading user input.
  247  *
  248  * Requires:
  249  * \li  isc_app_start() has been called.
  250  * \li  No other blocking operations are in progress.
  251  */
  252 
  253 void
  254 isc_app_unblock(void);
  255 /*!<
  256  * \brief Indicate that a blocking operation is complete.
  257  *
  258  * Notes:
  259  * \li  When a blocking operation has completed, return the program to a
  260  *  state where a call to isc_app_shutdown() or an external signal will
  261  *  shutdown normally.
  262  *
  263  * Requires:
  264  * \li  isc_app_start() has been called.
  265  * \li  isc_app_block() has been called by the same thread.
  266  */
  267 
  268 isc_result_t
  269 isc_appctx_create(isc_mem_t *mctx, isc_appctx_t **ctxp);
  270 /*!<
  271  * \brief Create an application context.
  272  *
  273  * Requires:
  274  *\li   'mctx' is a valid memory context.
  275  *\li   'ctxp' != NULL && *ctxp == NULL.
  276  */
  277 
  278 void
  279 isc_appctx_destroy(isc_appctx_t **ctxp);
  280 /*!<
  281  * \brief Destroy an application context.
  282  *
  283  * Requires:
  284  *\li   '*ctxp' is a valid application context.
  285  *
  286  * Ensures:
  287  *\li   *ctxp == NULL.
  288  */
  289 
  290 ISC_LANG_ENDDECLS
  291 
  292 #endif /* ISC_APP_H */