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