1 /* $NetBSD: app.h,v 1.1.1.1 2009/12/13 16:54:28 kardel Exp $ */ 2 3 /* 4 * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 1999-2001 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id: app.h,v 1.8 2007/06/19 23:47:18 tbox Exp */ 21 22 #ifndef ISC_APP_H 23 #define ISC_APP_H 1 24 25 /***** 26 ***** Module Info 27 *****/ 28 29 /*! \file isc/app.h 30 * \brief 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 *\li isc_app_start(); Call very early in main(), before 38 * any other threads have been created. 39 * 40 *\li 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 *\li 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 * \li 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 * \li Reliability: 66 * No anticipated impact. 67 * 68 * \li Resources: 69 * None. 70 * 71 * \li Security: 72 * No anticipated impact. 73 * 74 * \li 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 * \brief 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 * \brief 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 * \brief Run an ISC library application. 118 * 119 * Notes: 120 *\li 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 *\li isc_app_start() has been called. 126 * 127 * Ensures: 128 *\li Any events requested via isc_app_onrun() will have been posted (in 129 * FIFO order) before isc_app_run() blocks. 130 * 131 * Returns: 132 *\li ISC_R_SUCCESS Shutdown has been requested. 133 *\li ISC_R_RELOAD Reload has been requested. 134 */ 135 136 isc_result_t 137 isc_app_shutdown(void); 138 /*!< 139 * \brief Request application shutdown. 140 * 141 * Notes: 142 *\li It is safe to call isc_app_shutdown() multiple times. Shutdown will 143 * only be triggered once. 144 * 145 * Requires: 146 *\li isc_app_run() has been called. 147 * 148 * Returns: 149 *\li ISC_R_SUCCESS 150 *\li ISC_R_UNEXPECTED 151 */ 152 153 isc_result_t 154 isc_app_reload(void); 155 /*!< 156 * \brief Request application reload. 157 * 158 * Requires: 159 *\li isc_app_run() has been called. 160 * 161 * Returns: 162 *\li ISC_R_SUCCESS 163 *\li ISC_R_UNEXPECTED 164 */ 165 166 void 167 isc_app_finish(void); 168 /*!< 169 * \brief Finish an ISC library application. 170 * 171 * Notes: 172 *\li This call should be made at or near the end of main(). 173 * 174 * Requires: 175 *\li isc_app_start() has been called. 176 * 177 * Ensures: 178 *\li Any resources allocated by isc_app_start() have been released. 179 */ 180 181 void 182 isc_app_block(void); 183 /*!< 184 * \brief Indicate that a blocking operation will be performed. 185 * 186 * Notes: 187 *\li 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 * \li isc_app_start() has been called. 193 * \li No other blocking operations are in progress. 194 */ 195 196 void 197 isc_app_unblock(void); 198 /*!< 199 * \brief Indicate that a blocking operation is complete. 200 * 201 * Notes: 202 * \li 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 * \li isc_app_start() has been called. 208 * \li isc_app_block() has been called by the same thread. 209 */ 210 211 212 ISC_LANG_ENDDECLS 213 214 #endif /* ISC_APP_H */ 215