1/* 2 * Copyright (C) 2004-2007 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.8 2007/06/19 23:47:18 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 * \li MP: 58 * Clients must ensure that isc_app_start(), isc_app_run(), and 59 * isc_app_finish() are called at most once. isc_app_shutdown() 60 * is safe to use by any thread (provided isc_app_start() has been 61 * called previously). 62 * 63 * \li Reliability: 64 * No anticipated impact. 65 * 66 * \li Resources: 67 * None. 68 * 69 * \li Security: 70 * No anticipated impact. 71 * 72 * \li Standards: 73 * None. 74 */ 75 76#include <isc/eventclass.h> 77#include <isc/lang.h> 78#include <isc/result.h> 79 80typedef isc_event_t isc_appevent_t; 81 82#define ISC_APPEVENT_FIRSTEVENT (ISC_EVENTCLASS_APP + 0) 83#define ISC_APPEVENT_SHUTDOWN (ISC_EVENTCLASS_APP + 1) 84#define ISC_APPEVENT_LASTEVENT (ISC_EVENTCLASS_APP + 65535) 85 86ISC_LANG_BEGINDECLS 87 88isc_result_t 89isc_app_start(void); 90/*!< 91 * \brief Start an ISC library application. 92 * 93 * Notes: 94 * This call should be made before any other ISC library call, and as 95 * close to the beginning of the application as possible. 96 */ 97 98isc_result_t 99isc_app_onrun(isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action, 100 void *arg); 101/*!< 102 * \brief Request delivery of an event when the application is run. 103 * 104 * Requires: 105 * isc_app_start() has been called. 106 * 107 * Returns: 108 * ISC_R_SUCCESS 109 * ISC_R_NOMEMORY 110 */ 111 112isc_result_t 113isc_app_run(void); 114/*!< 115 * \brief Run an ISC library application. 116 * 117 * Notes: 118 *\li The caller (typically the initial thread of an application) will 119 * block until shutdown is requested. When the call returns, the 120 * caller should start shutting down the application. 121 * 122 * Requires: 123 *\li isc_app_start() has been called. 124 * 125 * Ensures: 126 *\li Any events requested via isc_app_onrun() will have been posted (in 127 * FIFO order) before isc_app_run() blocks. 128 * 129 * Returns: 130 *\li ISC_R_SUCCESS Shutdown has been requested. 131 *\li ISC_R_RELOAD Reload has been requested. 132 */ 133 134isc_result_t 135isc_app_shutdown(void); 136/*!< 137 * \brief Request application shutdown. 138 * 139 * Notes: 140 *\li It is safe to call isc_app_shutdown() multiple times. Shutdown will 141 * only be triggered once. 142 * 143 * Requires: 144 *\li isc_app_run() has been called. 145 * 146 * Returns: 147 *\li ISC_R_SUCCESS 148 *\li ISC_R_UNEXPECTED 149 */ 150 151isc_result_t 152isc_app_reload(void); 153/*!< 154 * \brief Request application reload. 155 * 156 * Requires: 157 *\li isc_app_run() has been called. 158 * 159 * Returns: 160 *\li ISC_R_SUCCESS 161 *\li ISC_R_UNEXPECTED 162 */ 163 164void 165isc_app_finish(void); 166/*!< 167 * \brief Finish an ISC library application. 168 * 169 * Notes: 170 *\li This call should be made at or near the end of main(). 171 * 172 * Requires: 173 *\li isc_app_start() has been called. 174 * 175 * Ensures: 176 *\li Any resources allocated by isc_app_start() have been released. 177 */ 178 179void 180isc_app_block(void); 181/*!< 182 * \brief Indicate that a blocking operation will be performed. 183 * 184 * Notes: 185 *\li If a blocking operation is in process, a call to isc_app_shutdown() 186 * or an external signal will abort the program, rather than allowing 187 * clean shutdown. This is primarily useful for reading user input. 188 * 189 * Requires: 190 * \li isc_app_start() has been called. 191 * \li No other blocking operations are in progress. 192 */ 193 194void 195isc_app_unblock(void); 196/*!< 197 * \brief Indicate that a blocking operation is complete. 198 * 199 * Notes: 200 * \li When a blocking operation has completed, return the program to a 201 * state where a call to isc_app_shutdown() or an external signal will 202 * shutdown normally. 203 * 204 * Requires: 205 * \li isc_app_start() has been called. 206 * \li isc_app_block() has been called by the same thread. 207 */ 208 209 210ISC_LANG_ENDDECLS 211 212#endif /* ISC_APP_H */ 213