| /* 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. |
| */ |
| |
| /** |
| * @file util_mutex.h |
| * @brief Apache Mutex support library |
| * |
| * @defgroup APACHE_CORE_MUTEX Mutex Library |
| * @ingroup APACHE_CORE |
| * @{ |
| */ |
| |
| #ifndef UTIL_MUTEX_H |
| #define UTIL_MUTEX_H |
| |
| #include "httpd.h" |
| #include "http_config.h" |
| #include "apr_global_mutex.h" |
| |
| #if APR_HAS_FLOCK_SERIALIZE |
| # define AP_LIST_FLOCK_SERIALIZE ", 'flock:/path/to/file'" |
| #else |
| # define AP_LIST_FLOCK_SERIALIZE |
| #endif |
| #if APR_HAS_FCNTL_SERIALIZE |
| # define AP_LIST_FCNTL_SERIALIZE ", 'fcntl:/path/to/file'" |
| #else |
| # define AP_LIST_FCNTL_SERIALIZE |
| #endif |
| #if APR_HAS_SYSVSEM_SERIALIZE |
| # define AP_LIST_SYSVSEM_SERIALIZE ", 'sysvsem'" |
| #else |
| # define AP_LIST_SYSVSEM_SERIALIZE |
| #endif |
| #if APR_HAS_POSIXSEM_SERIALIZE |
| # define AP_LIST_POSIXSEM_SERIALIZE ", 'posixsem'" |
| #else |
| # define AP_LIST_POSIXSEM_SERIALIZE |
| #endif |
| #if APR_HAS_PROC_PTHREAD_SERIALIZE |
| # define AP_LIST_PTHREAD_SERIALIZE ", 'pthread'" |
| #else |
| # define AP_LIST_PTHREAD_SERIALIZE |
| #endif |
| #if APR_HAS_FLOCK_SERIALIZE || APR_HAS_FCNTL_SERIALIZE |
| # define AP_LIST_FILE_SERIALIZE ", 'file:/path/to/file'" |
| #else |
| # define AP_LIST_FILE_SERIALIZE |
| #endif |
| #if APR_HAS_SYSVSEM_SERIALIZE || APR_HAS_POSIXSEM_SERIALIZE |
| # define AP_LIST_SEM_SERIALIZE ", 'sem'" |
| #else |
| # define AP_LIST_SEM_SERIALIZE |
| #endif |
| |
| #define AP_ALL_AVAILABLE_MUTEXES_STRING \ |
| "Mutex mechanisms are: 'none', 'default'" \ |
| AP_LIST_FLOCK_SERIALIZE AP_LIST_FCNTL_SERIALIZE \ |
| AP_LIST_FILE_SERIALIZE AP_LIST_PTHREAD_SERIALIZE \ |
| AP_LIST_SYSVSEM_SERIALIZE AP_LIST_POSIXSEM_SERIALIZE \ |
| AP_LIST_SEM_SERIALIZE |
| |
| #define AP_AVAILABLE_MUTEXES_STRING \ |
| "Mutex mechanisms are: 'default'" \ |
| AP_LIST_FLOCK_SERIALIZE AP_LIST_FCNTL_SERIALIZE \ |
| AP_LIST_FILE_SERIALIZE AP_LIST_PTHREAD_SERIALIZE \ |
| AP_LIST_SYSVSEM_SERIALIZE AP_LIST_POSIXSEM_SERIALIZE \ |
| AP_LIST_SEM_SERIALIZE |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * Get Mutex config data and parse it |
| * @param arg The mutex config string |
| * @param pool The allocation pool |
| * @param mutexmech The APR mutex locking mechanism |
| * @param mutexfile The lockfile to use as required |
| * @return APR status code |
| * @fn apr_status_t ap_parse_mutex(const char *arg, apr_pool_t *pool, |
| apr_lockmech_e *mutexmech, |
| const char **mutexfile) |
| */ |
| AP_DECLARE(apr_status_t) ap_parse_mutex(const char *arg, apr_pool_t *pool, |
| apr_lockmech_e *mutexmech, |
| const char **mutexfile); |
| |
| /* private function to process the Mutex directive */ |
| AP_DECLARE_NONSTD(const char *) ap_set_mutex(cmd_parms *cmd, void *dummy, |
| const char *arg); |
| |
| /* private function to initialize Mutex infrastructure */ |
| AP_DECLARE_NONSTD(void) ap_mutex_init(apr_pool_t *p); |
| |
| /** |
| * option flags for ap_mutex_register(), ap_global_mutex_create(), and |
| * ap_proc_mutex_create() |
| */ |
| #define AP_MUTEX_ALLOW_NONE 1 /* allow "none" as mutex implementation; |
| * respected only on ap_mutex_register() |
| */ |
| #define AP_MUTEX_DEFAULT_NONE 2 /* default to "none" for this mutex; |
| * respected only on ap_mutex_register() |
| */ |
| |
| /** |
| * Register a module's mutex type with core to allow configuration |
| * with the Mutex directive. This must be called in the pre_config |
| * hook; otherwise, configuration directives referencing this mutex |
| * type will be rejected. |
| * |
| * The default_dir and default_mech parameters allow a module to set |
| * defaults for the lock file directory and mechanism. These could |
| * be based on compile-time settings. These aren't required except |
| * in special circumstances. |
| * |
| * The order of precedence for the choice of mechanism and lock file |
| * directory is: |
| * |
| * 1. Mutex directive specifically for this mutex |
| * e.g., Mutex mpm-default flock:/tmp/mpmlocks |
| * 2. Mutex directive for global default |
| * e.g., Mutex default flock:/tmp/httpdlocks |
| * 3. Defaults for this mutex provided on the ap_mutex_register() |
| * 4. Built-in defaults for all mutexes, which are |
| * APR_LOCK_DEFAULT and DEFAULT_REL_RUNTIMEDIR. |
| * |
| * @param pconf The pconf pool |
| * @param type The type name of the mutex, used as the basename of the |
| * file associated with the mutex, if any. This must be unique among |
| * all mutex types (mutex creation accommodates multi-instance mutex |
| * types); mod_foo might have mutex types "foo-pipe" and "foo-shm" |
| * @param default_dir Default dir for any lock file required for this |
| * lock, to override built-in defaults; should be NULL for most |
| * modules, to respect built-in defaults |
| * @param default_mech Default mechanism for this lock, to override |
| * built-in defaults; should be APR_LOCK_DEFAULT for most modules, to |
| * respect built-in defaults |
| * or NULL if there are no defaults for this mutex. |
| * @param options combination of AP_MUTEX_* constants, or 0 for defaults |
| */ |
| AP_DECLARE(apr_status_t) ap_mutex_register(apr_pool_t *pconf, |
| const char *type, |
| const char *default_dir, |
| apr_lockmech_e default_mech, |
| apr_int32_t options); |
| |
| /** |
| * Create an APR global mutex that has been registered previously with |
| * ap_mutex_register(). Mutex files, permissions, and error logging will |
| * be handled internally. |
| * @param mutex The memory address where the newly created mutex will be |
| * stored. If this mutex is disabled, mutex will be set to NULL on |
| * output. (That is allowed only if the AP_MUTEX_ALLOW_NONE flag is |
| * passed to ap_mutex_register().) |
| * @param name The generated filename of the created mutex, or NULL if |
| * no file was created. Pass NULL if this result is not needed. |
| * @param type The type name of the mutex, matching the type name passed |
| * to ap_mutex_register(). |
| * @param instance_id A unique string to be used in the lock filename IFF |
| * this mutex type is multi-instance, NULL otherwise. |
| * @param server server_rec of main server |
| * @param pool pool lifetime of the mutex |
| * @param options combination of AP_MUTEX_* constants, or 0 for defaults |
| * (currently none are defined for this function) |
| */ |
| AP_DECLARE(apr_status_t) ap_global_mutex_create(apr_global_mutex_t **mutex, |
| const char **name, |
| const char *type, |
| const char *instance_id, |
| server_rec *server, |
| apr_pool_t *pool, |
| apr_int32_t options); |
| |
| /** |
| * Create an APR proc mutex that has been registered previously with |
| * ap_mutex_register(). Mutex files, permissions, and error logging will |
| * be handled internally. |
| * @param mutex The memory address where the newly created mutex will be |
| * stored. If this mutex is disabled, mutex will be set to NULL on |
| * output. (That is allowed only if the AP_MUTEX_ALLOW_NONE flag is |
| * passed to ap_mutex_register().) |
| * @param name The generated filename of the created mutex, or NULL if |
| * no file was created. Pass NULL if this result is not needed. |
| * @param type The type name of the mutex, matching the type name passed |
| * to ap_mutex_register(). |
| * @param instance_id A unique string to be used in the lock filename IFF |
| * this mutex type is multi-instance, NULL otherwise. |
| * @param server server_rec of main server |
| * @param pool pool lifetime of the mutex |
| * @param options combination of AP_MUTEX_* constants, or 0 for defaults |
| * (currently none are defined for this function) |
| */ |
| AP_DECLARE(apr_status_t) ap_proc_mutex_create(apr_proc_mutex_t **mutex, |
| const char **name, |
| const char *type, |
| const char *instance_id, |
| server_rec *server, |
| apr_pool_t *pool, |
| apr_int32_t options); |
| |
| AP_CORE_DECLARE(void) ap_dump_mutexes(apr_pool_t *p, server_rec *s, apr_file_t *out); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* UTIL_MUTEX_H */ |
| /** @} */ |