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