modules/core/mod_watchdog.h - httpd - Git at Google

 /* Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 #ifndef MOD_WATCHDOG_H
 #define MOD_WATCHDOG_H

 /**
  * @file  mod_watchdog.h
  * @brief Watchdog module for Apache
  *
  * @defgroup MOD_WATCHDOG mod_watchdog
  * @ingroup  APACHE_MODS
  * @{
  */

 #include "httpd.h"
 #include "http_config.h"
 #include "http_log.h"
 #include "ap_provider.h"

 #include "apr.h"
 #include "apr_strings.h"
 #include "apr_pools.h"
 #include "apr_shm.h"
 #include "apr_hash.h"
 #include "apr_hooks.h"
 #include "apr_optional.h"
 #include "apr_file_io.h"
 #include "apr_time.h"
 #include "apr_thread_proc.h"
 #include "apr_global_mutex.h"
 #include "apr_thread_mutex.h"

 #ifdef __cplusplus
 extern "C" {
 #endif

 /**
  * Default singleton watchdog instance name.
  * Singleton watchdog is protected by mutex and
  * guaranteed to be run inside a single child process
  * at any time.
  */
 #define AP_WATCHDOG_SINGLETON       "_singleton_"

 /**
  * Default watchdog instance name
  */
 #define AP_WATCHDOG_DEFAULT         "_default_"

 /**
  * Default Watchdog interval
  */
 #define AP_WD_TM_INTERVAL           APR_TIME_C(1000000)  /* 1 second     */

 /**
  * Watchdog thread timer resolution
  */
 #define AP_WD_TM_SLICE              APR_TIME_C(100000)   /* 100 ms       */

 /* State values for callback */
 #define AP_WATCHDOG_STATE_STARTING  1
 #define AP_WATCHDOG_STATE_RUNNING   2
 #define AP_WATCHDOG_STATE_STOPPING  3

 typedef struct ap_watchdog_t ap_watchdog_t;

 /* Create a set of AP_WD_DECLARE(type), AP_WD_DECLARE_NONSTD(type) and
  * AP_WD_DECLARE_DATA with appropriate export and import tags for the platform
  */
 #if !defined(AP_WD_DECLARE)
 #if !defined(WIN32)
 #define AP_WD_DECLARE(type)            type
 #define AP_WD_DECLARE_NONSTD(type)     type
 #define AP_WD_DECLARE_DATA
 #elif defined(AP_WD_DECLARE_STATIC)
 #define AP_WD_DECLARE(type)            type __stdcall
 #define AP_WD_DECLARE_NONSTD(type)     type
 #define AP_WD_DECLARE_DATA
 #elif defined(AP_WD_DECLARE_EXPORT)
 #define AP_WD_DECLARE(type)            __declspec(dllexport) type __stdcall
 #define AP_WD_DECLARE_NONSTD(type)     __declspec(dllexport) type
 #define AP_WD_DECLARE_DATA             __declspec(dllexport)
 #else
 #define AP_WD_DECLARE(type)            __declspec(dllimport) type __stdcall
 #define AP_WD_DECLARE_NONSTD(type)     __declspec(dllimport) type
 #define AP_WD_DECLARE_DATA             __declspec(dllimport)
 #endif
 #endif

 /**
  * Callback function used for watchdog.
  * @param state Watchdog state function. See @p AP_WATCHDOG_STATE_ .
  * @param data is what was passed to @p ap_watchdog_register_callback function.
  * @param pool Temporary callback pool destroyed after the call.
  * @return APR_SUCCESS to continue calling this callback.
  */
 typedef apr_status_t ap_watchdog_callback_fn_t(int state, void *data,
                                                apr_pool_t *pool);

 /**
  * Get watchdog instance.
  * @param watchdog Storage for watchdog instance.
  * @param name Watchdog name.
  * @param parent Non-zero to get the parent process watchdog instance.
  * @param singleton Non-zero to get the singleton watchdog instance.
  * @param p The pool to use.
  * @return APR_SUCCESS if all went well
  * @remark Use @p AP_WATCHDOG_DEFAULT to get default watchdog instance.
  *         If separate watchdog thread is needed provide unique name
  *         and function will create a new watchdog instance.
  *         Note that default client process watchdog works in singleton mode.
  */
 APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_watchdog_get_instance,
                         (ap_watchdog_t **watchdog, const char *name, int parent,
                          int singleton, apr_pool_t *p));

 /**
  * Register watchdog callback.
  * @param watchdog Watchdog to use
  * @param interval Interval on which the callback function will execute.
  * @param callback  The function to call on watchdog event.
  * @param data The data to pass to the callback function.
  * @return APR_SUCCESS if all went well. APR_EEXIST if already registered.
  */
 APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_watchdog_register_callback,
                         (ap_watchdog_t *watchdog, apr_interval_time_t interval,
                          const void *data, ap_watchdog_callback_fn_t *callback));

 /**
  * Update registered watchdog callback interval.
  * @param w Watchdog to use
  * @param interval New interval on which the callback function will execute.
  * @param callback  The function to call on watchdog event.
  * @param data The data to pass to the callback function.
  * @return APR_SUCCESS if all went well. APR_EOF if callback was not found.
  */
 APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_watchdog_set_callback_interval,
                         (ap_watchdog_t *w, apr_interval_time_t interval,
                          const void *data, ap_watchdog_callback_fn_t *callback));

 /**
  * Watchdog require hook.
  * @param s The server record
  * @param name Watchdog name.
  * @param parent Non-zero to indicate the parent process watchdog mode.
  * @param singleton Non-zero to indicate the singleton watchdog mode.
  * @return OK to enable notifications from this watchdog, DECLINED otherwise.
  * @remark This is called in post config phase for all watchdog instances
  *         that have no callbacks registered. Modules using this hook
  *         should ensure that their post_config hook is called after watchdog
  *         post_config.
  */
 APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_need, (server_rec *s,
                           const char *name,
                           int parent, int singleton))


 /**
  * Watchdog initialize hook.
  * It is called after the watchdog thread is initialized.
  * @param s The server record
  * @param name Watchdog name.
  * @param pool The pool used to create the watchdog.
  */
 APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_init, (
                           server_rec *s,
                           const char *name,
                           apr_pool_t *pool))

 /**
  * Watchdog terminate hook.
  * It is called when the watchdog thread is terminated.
  * @param s The server record
  * @param name Watchdog name.
  * @param pool The pool used to create the watchdog.
  */
 APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_exit, (
                           server_rec *s,
                           const char *name,
                           apr_pool_t *pool))

 /**
  * Fixed interval watchdog hook.
  * It is called regularly on @p AP_WD_TM_INTERVAL interval.
  * @param s The server record
  * @param name Watchdog name.
  * @param pool Temporary pool destroyed after the call.
  */
 APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_step, (
                           server_rec *s,
                           const char *name,
                           apr_pool_t *pool))

 #ifdef __cplusplus
 }
 #endif

 #endif /* MOD_WATCHDOG_H */
 /** @} */
	/* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You under the Apache License, Version 2.0
	* (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	#ifndef MOD_WATCHDOG_H
	#define MOD_WATCHDOG_H

	/**
	* @file mod_watchdog.h
	* @brief Watchdog module for Apache
	*
	* @defgroup MOD_WATCHDOG mod_watchdog
	* @ingroup APACHE_MODS
	* @{
	*/

	#include "httpd.h"
	#include "http_config.h"
	#include "http_log.h"
	#include "ap_provider.h"

	#include "apr.h"
	#include "apr_strings.h"
	#include "apr_pools.h"
	#include "apr_shm.h"
	#include "apr_hash.h"
	#include "apr_hooks.h"
	#include "apr_optional.h"
	#include "apr_file_io.h"
	#include "apr_time.h"
	#include "apr_thread_proc.h"
	#include "apr_global_mutex.h"
	#include "apr_thread_mutex.h"

	#ifdef __cplusplus
	extern "C" {
	#endif

	/**
	* Default singleton watchdog instance name.
	* Singleton watchdog is protected by mutex and
	* guaranteed to be run inside a single child process
	* at any time.
	*/
	#define AP_WATCHDOG_SINGLETON "_singleton_"

	/**
	* Default watchdog instance name
	*/
	#define AP_WATCHDOG_DEFAULT "_default_"

	/**
	* Default Watchdog interval
	*/
	#define AP_WD_TM_INTERVAL APR_TIME_C(1000000) /* 1 second */

	/**
	* Watchdog thread timer resolution
	*/
	#define AP_WD_TM_SLICE APR_TIME_C(100000) /* 100 ms */

	/* State values for callback */
	#define AP_WATCHDOG_STATE_STARTING 1
	#define AP_WATCHDOG_STATE_RUNNING 2
	#define AP_WATCHDOG_STATE_STOPPING 3

	typedef struct ap_watchdog_t ap_watchdog_t;

	/* Create a set of AP_WD_DECLARE(type), AP_WD_DECLARE_NONSTD(type) and
	* AP_WD_DECLARE_DATA with appropriate export and import tags for the platform
	*/
	#if !defined(AP_WD_DECLARE)
	#if !defined(WIN32)
	#define AP_WD_DECLARE(type) type
	#define AP_WD_DECLARE_NONSTD(type) type
	#define AP_WD_DECLARE_DATA
	#elif defined(AP_WD_DECLARE_STATIC)
	#define AP_WD_DECLARE(type) type __stdcall
	#define AP_WD_DECLARE_NONSTD(type) type
	#define AP_WD_DECLARE_DATA
	#elif defined(AP_WD_DECLARE_EXPORT)
	#define AP_WD_DECLARE(type) __declspec(dllexport) type __stdcall
	#define AP_WD_DECLARE_NONSTD(type) __declspec(dllexport) type
	#define AP_WD_DECLARE_DATA __declspec(dllexport)
	#else
	#define AP_WD_DECLARE(type) __declspec(dllimport) type __stdcall
	#define AP_WD_DECLARE_NONSTD(type) __declspec(dllimport) type
	#define AP_WD_DECLARE_DATA __declspec(dllimport)
	#endif
	#endif

	/**
	* Callback function used for watchdog.
	* @param state Watchdog state function. See @p AP_WATCHDOG_STATE_ .
	* @param data is what was passed to @p ap_watchdog_register_callback function.
	* @param pool Temporary callback pool destroyed after the call.
	* @return APR_SUCCESS to continue calling this callback.
	*/
	typedef apr_status_t ap_watchdog_callback_fn_t(int state, void *data,
	apr_pool_t *pool);

	/**
	* Get watchdog instance.
	* @param watchdog Storage for watchdog instance.
	* @param name Watchdog name.
	* @param parent Non-zero to get the parent process watchdog instance.
	* @param singleton Non-zero to get the singleton watchdog instance.
	* @param p The pool to use.
	* @return APR_SUCCESS if all went well
	* @remark Use @p AP_WATCHDOG_DEFAULT to get default watchdog instance.
	* If separate watchdog thread is needed provide unique name
	* and function will create a new watchdog instance.
	* Note that default client process watchdog works in singleton mode.
	*/
	APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_watchdog_get_instance,
	(ap_watchdog_t *watchdog, const char name, int parent,
	int singleton, apr_pool_t *p));

	/**
	* Register watchdog callback.
	* @param watchdog Watchdog to use
	* @param interval Interval on which the callback function will execute.
	* @param callback The function to call on watchdog event.
	* @param data The data to pass to the callback function.
	* @return APR_SUCCESS if all went well. APR_EEXIST if already registered.
	*/
	APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_watchdog_register_callback,
	(ap_watchdog_t *watchdog, apr_interval_time_t interval,
	const void data, ap_watchdog_callback_fn_t callback));

	/**
	* Update registered watchdog callback interval.
	* @param w Watchdog to use
	* @param interval New interval on which the callback function will execute.
	* @param callback The function to call on watchdog event.
	* @param data The data to pass to the callback function.
	* @return APR_SUCCESS if all went well. APR_EOF if callback was not found.
	*/
	APR_DECLARE_OPTIONAL_FN(apr_status_t, ap_watchdog_set_callback_interval,
	(ap_watchdog_t *w, apr_interval_time_t interval,
	const void data, ap_watchdog_callback_fn_t callback));

	/**
	* Watchdog require hook.
	* @param s The server record
	* @param name Watchdog name.
	* @param parent Non-zero to indicate the parent process watchdog mode.
	* @param singleton Non-zero to indicate the singleton watchdog mode.
	* @return OK to enable notifications from this watchdog, DECLINED otherwise.
	* @remark This is called in post config phase for all watchdog instances
	* that have no callbacks registered. Modules using this hook
	* should ensure that their post_config hook is called after watchdog
	* post_config.
	*/
	APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_need, (server_rec *s,
	const char *name,
	int parent, int singleton))


	/**
	* Watchdog initialize hook.
	* It is called after the watchdog thread is initialized.
	* @param s The server record
	* @param name Watchdog name.
	* @param pool The pool used to create the watchdog.
	*/
	APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_init, (
	server_rec *s,
	const char *name,
	apr_pool_t *pool))

	/**
	* Watchdog terminate hook.
	* It is called when the watchdog thread is terminated.
	* @param s The server record
	* @param name Watchdog name.
	* @param pool The pool used to create the watchdog.
	*/
	APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_exit, (
	server_rec *s,
	const char *name,
	apr_pool_t *pool))

	/**
	* Fixed interval watchdog hook.
	* It is called regularly on @p AP_WD_TM_INTERVAL interval.
	* @param s The server record
	* @param name Watchdog name.
	* @param pool Temporary pool destroyed after the call.
	*/
	APR_DECLARE_EXTERNAL_HOOK(ap, AP_WD, int, watchdog_step, (
	server_rec *s,
	const char *name,
	apr_pool_t *pool))

	#ifdef __cplusplus
	}
	#endif

	#endif /* MOD_WATCHDOG_H */
	/** @} */