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