Apache Portable Runtime
apr_proc_mutex.h
Go to the documentation of this file.
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 #ifndef APR_PROC_MUTEX_H
18 #define APR_PROC_MUTEX_H
19 
20 /**
21  * @file apr_proc_mutex.h
22  * @brief APR Process Locking Routines
23  */
24 
25 #include "apr.h"
26 #include "apr_pools.h"
27 #include "apr_errno.h"
28 #include "apr_perms_set.h"
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif /* __cplusplus */
33 
34 /**
35  * @defgroup apr_proc_mutex Process Locking Routines
36  * @ingroup APR
37  * @{
38  */
39 
40 /**
41  * Enumerated potential types for APR process locking methods
42  * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
43  * APR_LOCK_foo. Only APR_LOCK_DEFAULT is portable.
44  */
45 typedef enum {
46  APR_LOCK_FCNTL, /**< fcntl() */
47  APR_LOCK_FLOCK, /**< flock() */
48  APR_LOCK_SYSVSEM, /**< System V Semaphores */
49  APR_LOCK_PROC_PTHREAD, /**< POSIX pthread process-based locking */
50  APR_LOCK_POSIXSEM, /**< POSIX semaphore process-based locking */
51  APR_LOCK_DEFAULT /**< Use the default process lock */
53 
54 /** Opaque structure representing a process mutex. */
56 
57 /* Function definitions */
58 
59 /**
60  * Create and initialize a mutex that can be used to synchronize processes.
61  * @param mutex the memory address where the newly created mutex will be
62  * stored.
63  * @param fname A file name to use if the lock mechanism requires one. This
64  * argument should always be provided. The lock code itself will
65  * determine if it should be used.
66  * @param mech The mechanism to use for the interprocess lock, if any; one of
67  * <PRE>
68  * APR_LOCK_FCNTL
69  * APR_LOCK_FLOCK
70  * APR_LOCK_SYSVSEM
71  * APR_LOCK_POSIXSEM
72  * APR_LOCK_PROC_PTHREAD
73  * APR_LOCK_DEFAULT pick the default mechanism for the platform
74  * </PRE>
75  * @param pool the pool from which to allocate the mutex.
76  * @see apr_lockmech_e
77  * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
78  * APR_LOCK_foo. Only APR_LOCK_DEFAULT is portable.
79  */
81  const char *fname,
82  apr_lockmech_e mech,
83  apr_pool_t *pool);
84 
85 /**
86  * Re-open a mutex in a child process.
87  * @param mutex The newly re-opened mutex structure.
88  * @param fname A file name to use if the mutex mechanism requires one. This
89  * argument should always be provided. The mutex code itself will
90  * determine if it should be used. This filename should be the
91  * same one that was passed to apr_proc_mutex_create().
92  * @param pool The pool to operate on.
93  * @remark This function must be called to maintain portability, even
94  * if the underlying lock mechanism does not require it.
95  */
97  const char *fname,
98  apr_pool_t *pool);
99 
100 /**
101  * Acquire the lock for the given mutex. If the mutex is already locked,
102  * the current thread will be put to sleep until the lock becomes available.
103  * @param mutex the mutex on which to acquire the lock.
104  */
106 
107 /**
108  * Attempt to acquire the lock for the given mutex. If the mutex has already
109  * been acquired, the call returns immediately with APR_EBUSY. Note: it
110  * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine
111  * if the return value was APR_EBUSY, for portability reasons.
112  * @param mutex the mutex on which to attempt the lock acquiring.
113  */
115 
116 /**
117  * Release the lock for the given mutex.
118  * @param mutex the mutex from which to release the lock.
119  */
121 
122 /**
123  * Destroy the mutex and free the memory associated with the lock.
124  * @param mutex the mutex to destroy.
125  */
127 
128 /**
129  * Destroy the mutex and free the memory associated with the lock.
130  * @param mutex the mutex to destroy.
131  * @note This function is generally used to kill a cleanup on an already
132  * created mutex
133  */
135 
136 /**
137  * Return the name of the lockfile for the mutex, or NULL
138  * if the mutex doesn't use a lock file
139  */
140 
142 
143 /**
144  * Get the mechanism of the mutex, as it relates to the actual method
145  * used for the underlying apr_proc_mutex_t.
146  * @param mutex the mutex to get the mechanism from.
147  */
148 APR_DECLARE(apr_lockmech_e) apr_proc_mutex_mech(apr_proc_mutex_t *mutex);
149 
150 /**
151  * Get the mechanism's name of the mutex, as it relates to the actual method
152  * used for the underlying apr_proc_mutex_t.
153  * @param mutex the mutex to get the mechanism's name from.
154  */
155 APR_DECLARE(const char *) apr_proc_mutex_name(apr_proc_mutex_t *mutex);
156 
157 /**
158  * Display the name of the default mutex: APR_LOCK_DEFAULT
159  */
160 APR_DECLARE(const char *) apr_proc_mutex_defname(void);
161 
162 /**
163  * Set mutex permissions.
164  */
165 APR_PERMS_SET_IMPLEMENT(proc_mutex);
166 
167 /**
168  * Get the pool used by this proc_mutex.
169  * @return apr_pool_t the pool
170  */
171 APR_POOL_DECLARE_ACCESSOR(proc_mutex);
172 
173 /** @} */
174 
175 #ifdef __cplusplus
176 }
177 #endif
178 
179 #endif /* ! APR_PROC_MUTEX_H */
Definition: apr_proc_mutex.h:48
APR Process Locking Routines.
const char * apr_proc_mutex_lockfile(apr_proc_mutex_t *mutex)
Definition: apr_proc_mutex.h:50
Definition: apr_proc_mutex.h:49
Definition: apr_proc_mutex.h:46
Definition: apr_proc_mutex.h:51
const char * apr_proc_mutex_defname(void)
#define APR_DECLARE(type)
Definition: apr.h:480
apr_status_t apr_proc_mutex_child_init(apr_proc_mutex_t **mutex, const char *fname, apr_pool_t *pool)
Definition: apr_proc_mutex.h:47
struct apr_proc_mutex_t apr_proc_mutex_t
Definition: apr_proc_mutex.h:55
APR memory allocation.
apr_status_t apr_proc_mutex_lock(apr_proc_mutex_t *mutex)
apr_status_t apr_proc_mutex_create(apr_proc_mutex_t **mutex, const char *fname, apr_lockmech_e mech, apr_pool_t *pool)
APR Error Codes.
apr_lockmech_e
Definition: apr_proc_mutex.h:45
APR Platform Definitions.
const char * apr_proc_mutex_name(apr_proc_mutex_t *mutex)
APR_PERMS_SET_IMPLEMENT(proc_mutex)
apr_status_t apr_proc_mutex_unlock(apr_proc_mutex_t *mutex)
struct apr_pool_t apr_pool_t
Definition: apr_pools.h:60
apr_status_t apr_proc_mutex_destroy(apr_proc_mutex_t *mutex)
int apr_status_t
Definition: apr_errno.h:44
apr_lockmech_e apr_proc_mutex_mech(apr_proc_mutex_t *mutex)
apr_status_t apr_proc_mutex_cleanup(void *mutex)
apr_status_t apr_proc_mutex_trylock(apr_proc_mutex_t *mutex)
#define APR_POOL_DECLARE_ACCESSOR(type)
Definition: apr_pools.h:81