1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef MOD_WATCHDOG_H 18#define MOD_WATCHDOG_H 19 20/** 21 * @file mod_watchdog.h 22 * @brief Watchdog module for Apache 23 * 24 * @defgroup MOD_WATCHDOG watchdog 25 * @ingroup APACHE_MODS 26 * \@{ 27 */ 28 29#include "httpd.h" 30#include "http_config.h" 31#include "http_log.h" 32#include "ap_provider.h" 33 34#include "apr.h" 35#include "apr_strings.h" 36#include "apr_pools.h" 37#include "apr_shm.h" 38#include "apr_hash.h" 39#include "apr_hooks.h" 40#include "apr_optional.h" 41#include "apr_file_io.h" 42#include "apr_time.h" 43#include "apr_thread_proc.h" 44#include "apr_global_mutex.h" 45#include "apr_thread_mutex.h" 46 47#ifdef __cplusplus 48extern "C" { 49#endif 50 51/** 52 * Default singleton watchdog instance name. 53 * Singleton watchdog is protected by mutex and 54 * guaranteed to be run inside a single child process 55 * at any time. 56 */ 57#define AP_WATCHDOG_SINGLETON "_singleton_" 58 59/** 60 * Default watchdog instance name 61 */ 62#define AP_WATCHDOG_DEFAULT "_default_" 63 64/** 65 * Default Watchdog interval 66 */ 67#define AP_WD_TM_INTERVAL APR_TIME_C(1000000) /* 1 second */ 68 69/** 70 * Watchdog thread timer resolution 71 */ 72#define AP_WD_TM_SLICE APR_TIME_C(100000) /* 100 ms */ 73 74/* State values for callback */ 75#define AP_WATCHDOG_STATE_STARTING 1 76#define AP_WATCHDOG_STATE_RUNNING 2 77#define AP_WATCHDOG_STATE_STOPPING 3 78 79typedef struct ap_watchdog_t ap_watchdog_t; 80 81/* Create a set of AP_WD_DECLARE(type), AP_WD_DECLARE_NONSTD(type) and 82 * AP_WD_DECLARE_DATA with appropriate export and import tags for the platform 83 */ 84#if !defined(AP_WD_DECLARE) 85#if !defined(WIN32) 86#define AP_WD_DECLARE(type) type 87#define AP_WD_DECLARE_NONSTD(type) type 88#define AP_WD_DECLARE_DATA 89#elif defined(AP_WD_DECLARE_STATIC) 90#define AP_WD_DECLARE(type) type __stdcall 91#define AP_WD_DECLARE_NONSTD(type) type 92#define AP_WD_DECLARE_DATA 93#elif defined(AP_WD_DECLARE_EXPORT) 94#define AP_WD_DECLARE(type) __declspec(dllexport) type __stdcall 95#define AP_WD_DECLARE_NONSTD(type) __declspec(dllexport) type 96#define AP_WD_DECLARE_DATA __declspec(dllexport) 97#else 98#define AP_WD_DECLARE(type) __declspec(dllimport) type __stdcall 99#define AP_WD_DECLARE_NONSTD(type) __declspec(dllimport) type 100#define AP_WD_DECLARE_DATA __declspec(dllimport) 101#endif 102#endif 103 104/** 105 * Callback function used for watchdog. 106 * @param state Watchdog state function. See @p AP_WATCHDOG_STATE_ . 107 * @param data is what was passed to @p ap_watchdog_register_callback function. 108 * @param pool Temporary callback pool destroyed after the call. 109 * @return APR_SUCCESS to continue calling this callback. 110 */ 111typedef apr_status_t ap_watchdog_callback_fn_t(int state, void *data, 112 apr_pool_t *pool); 113 114/** 115 * Get watchdog instance. 116 * @param watchdog Storage for watchdog instance. 117 * @param name Watchdog name. 118 * @param parent Non-zero to get the parent process watchdog instance. 119 * @param singleton Non-zero to get the singleton watchdog instance. 120 * @param p The pool to use. 121 * @return APR_SUCCESS if all went well 122 * @remark Use @p AP_WATCHDOG_DEFAULT to get default watchdog instance. 123 * If separate watchdog thread is needed provide unique name 124 * and function will create a new watchdog instance. 125 * Note that default client process watchdog works in singleton mode. 126 */ 127APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_watchdog_get_instance, 128 (ap_watchdog_t **watchdog, const char *name, int parent, 129 int singleton, apr_pool_t *p)); 130 131/** 132 * Register watchdog callback. 133 * @param watchdog Watchdog to use 134 * @param interval Interval on which the callback function will execute. 135 * @param callback The function to call on watchdog event. 136 * @param data The data to pass to the callback function. 137 * @return APR_SUCCESS if all went well. APR_EEXIST if already registered. 138 */ 139APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_watchdog_register_callback, 140 (ap_watchdog_t *watchdog, apr_interval_time_t interval, 141 const void *data, ap_watchdog_callback_fn_t *callback)); 142 143/** 144 * Update registered watchdog callback interval. 145 * @param w Watchdog to use 146 * @param interval New interval on which the callback function will execute. 147 * @param callback The function to call on watchdog event. 148 * @param data The data to pass to the callback function. 149 * @return APR_SUCCESS if all went well. APR_EOF if callback was not found. 150 */ 151APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_watchdog_set_callback_interval, 152 (ap_watchdog_t *w, apr_interval_time_t interval, 153 const void *data, ap_watchdog_callback_fn_t *callback)); 154 155/** 156 * Watchdog require hook. 157 * @param s The server record 158 * @param name Watchdog name. 159 * @param parent Non-zero to indicate the parent process watchdog mode. 160 * @param singleton Non-zero to indicate the singleton watchdog mode. 161 * @return OK to enable notifications from this watchdog, DECLINED otherwise. 162 * @remark This is called in post config phase for all watchdog instances 163 * that have no callbacks registered. Modules using this hook 164 * should ensure that their post_config hook is called after watchdog 165 * post_config. 166 */ 167APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_need, (server_rec *s, 168 const char *name, 169 int parent, int singleton)) 170 171 172/** 173 * Watchdog initialize hook. 174 * It is called after the watchdog thread is initialized. 175 * @param s The server record 176 * @param name Watchdog name. 177 * @param pool The pool used to create the watchdog. 178 */ 179APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_init, ( 180 server_rec *s, 181 const char *name, 182 apr_pool_t *pool)) 183 184/** 185 * Watchdog terminate hook. 186 * It is called when the watchdog thread is terminated. 187 * @param s The server record 188 * @param name Watchdog name. 189 * @param pool The pool used to create the watchdog. 190 */ 191APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_exit, ( 192 server_rec *s, 193 const char *name, 194 apr_pool_t *pool)) 195 196/** 197 * Fixed interval watchdog hook. 198 * It is called regularly on @p AP_WD_TM_INTERVAL interval. 199 * @param s The server record 200 * @param name Watchdog name. 201 * @param pool Temporary pool destroyed after the call. 202 */ 203APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_step, ( 204 server_rec *s, 205 const char *name, 206 apr_pool_t *pool)) 207 208#ifdef __cplusplus 209} 210#endif 211 212#endif /* MOD_WATCHDOG_H */ 213/** \@} */ 214