"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/isc/include/isc/app.h" (7 Sep 2020, 10477 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


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