util_mutex.h 9.07 KB
Newer Older
powelld's avatar
powelld committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
/* 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 */
/** @} */