granicus.if.org Git - apache/blob - include/util_mutex.h

   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
  84 extern "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  */
  98 AP_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 */
 103 AP_DECLARE_NONSTD(const char *) ap_set_mutex(cmd_parms *cmd, void *dummy,
 104                                              const char *arg);
 105
 106 /* private function to initialize Mutex infrastructure */
 107 AP_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  */
 156 AP_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  */
 181 AP_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  */
 208 AP_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
 216 AP_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 /** @} */