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/** 18 * @file util_mutex.h 19 * @brief Apache Mutex support library 20 * 21 * @defgroup APACHE_CORE_MUTEX Mutex Library 22 * @ingroup APACHE_CORE 23 * @{ 24 */ 25 26#ifndef UTIL_MUTEX_H 27#define UTIL_MUTEX_H 28 29#include "httpd.h" 30#include "http_config.h" 31#include "apr_global_mutex.h" 32 33#if APR_HAS_FLOCK_SERIALIZE 34# define AP_LIST_FLOCK_SERIALIZE ", 'flock:/path/to/file'" 35#else 36# define AP_LIST_FLOCK_SERIALIZE 37#endif 38#if APR_HAS_FCNTL_SERIALIZE 39# define AP_LIST_FCNTL_SERIALIZE ", 'fcntl:/path/to/file'" 40#else 41# define AP_LIST_FCNTL_SERIALIZE 42#endif 43#if APR_HAS_SYSVSEM_SERIALIZE 44# define AP_LIST_SYSVSEM_SERIALIZE ", 'sysvsem'" 45#else 46# define AP_LIST_SYSVSEM_SERIALIZE 47#endif 48#if APR_HAS_POSIXSEM_SERIALIZE 49# define AP_LIST_POSIXSEM_SERIALIZE ", 'posixsem'" 50#else 51# define AP_LIST_POSIXSEM_SERIALIZE 52#endif 53#if APR_HAS_PROC_PTHREAD_SERIALIZE 54# define AP_LIST_PTHREAD_SERIALIZE ", 'pthread'" 55#else 56# define AP_LIST_PTHREAD_SERIALIZE 57#endif 58#if APR_HAS_FLOCK_SERIALIZE || APR_HAS_FCNTL_SERIALIZE 59# define AP_LIST_FILE_SERIALIZE ", 'file:/path/to/file'" 60#else 61# define AP_LIST_FILE_SERIALIZE 62#endif 63#if APR_HAS_SYSVSEM_SERIALIZE || APR_HAS_POSIXSEM_SERIALIZE 64# define AP_LIST_SEM_SERIALIZE ", 'sem'" 65#else 66# define AP_LIST_SEM_SERIALIZE 67#endif 68 69#define AP_ALL_AVAILABLE_MUTEXES_STRING \ 70 "Mutex mechanisms are: 'none', 'default'" \ 71 AP_LIST_FLOCK_SERIALIZE AP_LIST_FCNTL_SERIALIZE \ 72 AP_LIST_FILE_SERIALIZE AP_LIST_PTHREAD_SERIALIZE \ 73 AP_LIST_SYSVSEM_SERIALIZE AP_LIST_POSIXSEM_SERIALIZE \ 74 AP_LIST_SEM_SERIALIZE 75 76#define AP_AVAILABLE_MUTEXES_STRING \ 77 "Mutex mechanisms are: 'default'" \ 78 AP_LIST_FLOCK_SERIALIZE AP_LIST_FCNTL_SERIALIZE \ 79 AP_LIST_FILE_SERIALIZE AP_LIST_PTHREAD_SERIALIZE \ 80 AP_LIST_SYSVSEM_SERIALIZE AP_LIST_POSIXSEM_SERIALIZE \ 81 AP_LIST_SEM_SERIALIZE 82 83#ifdef __cplusplus 84extern "C" { 85#endif 86 87/** 88 * Get Mutex config data and parse it 89 * @param arg The mutex config string 90 * @param pool The allocation pool 91 * @param mutexmech The APR mutex locking mechanism 92 * @param mutexfile The lockfile to use as required 93 * @return APR status code 94 * @fn apr_status_t ap_parse_mutex(const char *arg, apr_pool_t *pool, 95 apr_lockmech_e *mutexmech, 96 const char **mutexfile) 97 */ 98AP_DECLARE(apr_status_t) ap_parse_mutex(const char *arg, apr_pool_t *pool, 99 apr_lockmech_e *mutexmech, 100 const char **mutexfile); 101 102/* private function to process the Mutex directive */ 103AP_DECLARE_NONSTD(const char *) ap_set_mutex(cmd_parms *cmd, void *dummy, 104 const char *arg); 105 106/* private function to initialize Mutex infrastructure */ 107AP_DECLARE_NONSTD(void) ap_mutex_init(apr_pool_t *p); 108 109/** 110 * option flags for ap_mutex_register(), ap_global_mutex_create(), and 111 * ap_proc_mutex_create() 112 */ 113#define AP_MUTEX_ALLOW_NONE 1 /* allow "none" as mutex implementation; 114 * respected only on ap_mutex_register() 115 */ 116#define AP_MUTEX_DEFAULT_NONE 2 /* default to "none" for this mutex; 117 * respected only on ap_mutex_register() 118 */ 119 120/** 121 * Register a module's mutex type with core to allow configuration 122 * with the Mutex directive. This must be called in the pre_config 123 * hook; otherwise, configuration directives referencing this mutex 124 * type will be rejected. 125 * 126 * The default_dir and default_mech parameters allow a module to set 127 * defaults for the lock file directory and mechanism. These could 128 * be based on compile-time settings. These aren't required except 129 * in special circumstances. 130 * 131 * The order of precedence for the choice of mechanism and lock file 132 * directory is: 133 * 134 * 1. Mutex directive specifically for this mutex 135 * e.g., Mutex mpm-default flock:/tmp/mpmlocks 136 * 2. Mutex directive for global default 137 * e.g., Mutex default flock:/tmp/httpdlocks 138 * 3. Defaults for this mutex provided on the ap_mutex_register() 139 * 4. Built-in defaults for all mutexes, which are 140 * APR_LOCK_DEFAULT and DEFAULT_REL_RUNTIMEDIR. 141 * 142 * @param pconf The pconf pool 143 * @param type The type name of the mutex, used as the basename of the 144 * file associated with the mutex, if any. This must be unique among 145 * all mutex types (mutex creation accommodates multi-instance mutex 146 * types); mod_foo might have mutex types "foo-pipe" and "foo-shm" 147 * @param default_dir Default dir for any lock file required for this 148 * lock, to override built-in defaults; should be NULL for most 149 * modules, to respect built-in defaults 150 * @param default_mech Default mechanism for this lock, to override 151 * built-in defaults; should be APR_LOCK_DEFAULT for most modules, to 152 * respect built-in defaults 153 * or NULL if there are no defaults for this mutex. 154 * @param options combination of AP_MUTEX_* constants, or 0 for defaults 155 */ 156AP_DECLARE(apr_status_t) ap_mutex_register(apr_pool_t *pconf, 157 const char *type, 158 const char *default_dir, 159 apr_lockmech_e default_mech, 160 apr_int32_t options); 161 162/** 163 * Create an APR global mutex that has been registered previously with 164 * ap_mutex_register(). Mutex files, permissions, and error logging will 165 * be handled internally. 166 * @param mutex The memory address where the newly created mutex will be 167 * stored. If this mutex is disabled, mutex will be set to NULL on 168 * output. (That is allowed only if the AP_MUTEX_ALLOW_NONE flag is 169 * passed to ap_mutex_register().) 170 * @param name The generated filename of the created mutex, or NULL if 171 * no file was created. Pass NULL if this result is not needed. 172 * @param type The type name of the mutex, matching the type name passed 173 * to ap_mutex_register(). 174 * @param instance_id A unique string to be used in the lock filename IFF 175 * this mutex type is multi-instance, NULL otherwise. 176 * @param server server_rec of main server 177 * @param pool pool lifetime of the mutex 178 * @param options combination of AP_MUTEX_* constants, or 0 for defaults 179 * (currently none are defined for this function) 180 */ 181AP_DECLARE(apr_status_t) ap_global_mutex_create(apr_global_mutex_t **mutex, 182 const char **name, 183 const char *type, 184 const char *instance_id, 185 server_rec *server, 186 apr_pool_t *pool, 187 apr_int32_t options); 188 189/** 190 * Create an APR proc mutex that has been registered previously with 191 * ap_mutex_register(). Mutex files, permissions, and error logging will 192 * be handled internally. 193 * @param mutex The memory address where the newly created mutex will be 194 * stored. If this mutex is disabled, mutex will be set to NULL on 195 * output. (That is allowed only if the AP_MUTEX_ALLOW_NONE flag is 196 * passed to ap_mutex_register().) 197 * @param name The generated filename of the created mutex, or NULL if 198 * no file was created. Pass NULL if this result is not needed. 199 * @param type The type name of the mutex, matching the type name passed 200 * to ap_mutex_register(). 201 * @param instance_id A unique string to be used in the lock filename IFF 202 * this mutex type is multi-instance, NULL otherwise. 203 * @param server server_rec of main server 204 * @param pool pool lifetime of the mutex 205 * @param options combination of AP_MUTEX_* constants, or 0 for defaults 206 * (currently none are defined for this function) 207 */ 208AP_DECLARE(apr_status_t) ap_proc_mutex_create(apr_proc_mutex_t **mutex, 209 const char **name, 210 const char *type, 211 const char *instance_id, 212 server_rec *server, 213 apr_pool_t *pool, 214 apr_int32_t options); 215 216AP_CORE_DECLARE(void) ap_dump_mutexes(apr_pool_t *p, server_rec *s, apr_file_t *out); 217 218#ifdef __cplusplus 219} 220#endif 221 222#endif /* UTIL_MUTEX_H */ 223/** @} */ 224