granicus.if.org Git - apache/blob - modules/core/mod_watchdog.h

   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
  48 extern "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
  79 typedef 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  */
 111 typedef 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  */
 127 APR_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  */
 139 APR_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  */
 151 APR_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  */
 167 APR_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  */
 179 APR_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  */
 191 APR_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  */
 203 APR_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 /** \@} */