/* 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 */

/** @} */