00001 /* Copyright 2000-2004 The Apache Software Foundation 00002 * 00003 * Licensed under the Apache License, Version 2.0 (the "License"); 00004 * you may not use this file except in compliance with the License. 00005 * You may obtain a copy of the License at 00006 * 00007 * http://www.apache.org/licenses/LICENSE-2.0 00008 * 00009 * Unless required by applicable law or agreed to in writing, software 00010 * distributed under the License is distributed on an "AS IS" BASIS, 00011 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00012 * See the License for the specific language governing permissions and 00013 * limitations under the License. 00014 */ 00015 00016 #ifndef APR_PROC_MUTEX_H 00017 #define APR_PROC_MUTEX_H 00018 00019 /** 00020 * @file apr_proc_mutex.h 00021 * @brief APR Process Locking Routines 00022 */ 00023 00024 #include "apr.h" 00025 #include "apr_pools.h" 00026 #include "apr_errno.h" 00027 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif /* __cplusplus */ 00031 00032 /** 00033 * @defgroup apr_proc_mutex Process Locking Routines 00034 * @ingroup APR 00035 * @{ 00036 */ 00037 00038 /** 00039 * Enumerated potential types for APR process locking methods 00040 * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports 00041 * APR_LOCK_foo. Only APR_LOCK_DEFAULT is portable. 00042 */ 00043 typedef enum { 00044 APR_LOCK_FCNTL, /**< fcntl() */ 00045 APR_LOCK_FLOCK, /**< flock() */ 00046 APR_LOCK_SYSVSEM, /**< System V Semaphores */ 00047 APR_LOCK_PROC_PTHREAD, /**< POSIX pthread process-based locking */ 00048 APR_LOCK_POSIXSEM, /**< POSIX semaphore process-based locking */ 00049 APR_LOCK_DEFAULT /**< Use the default process lock */ 00050 } apr_lockmech_e; 00051 00052 /** Opaque structure representing a process mutex. */ 00053 typedef struct apr_proc_mutex_t apr_proc_mutex_t; 00054 00055 /* Function definitions */ 00056 00057 /** 00058 * Create and initialize a mutex that can be used to synchronize processes. 00059 * @param mutex the memory address where the newly created mutex will be 00060 * stored. 00061 * @param fname A file name to use if the lock mechanism requires one. This 00062 * argument should always be provided. The lock code itself will 00063 * determine if it should be used. 00064 * @param mech The mechanism to use for the interprocess lock, if any; one of 00065 * <PRE> 00066 * APR_LOCK_FCNTL 00067 * APR_LOCK_FLOCK 00068 * APR_LOCK_SYSVSEM 00069 * APR_LOCK_POSIXSEM 00070 * APR_LOCK_PROC_PTHREAD 00071 * APR_LOCK_DEFAULT pick the default mechanism for the platform 00072 * </PRE> 00073 * @param pool the pool from which to allocate the mutex. 00074 * @see apr_lockmech_e 00075 * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports 00076 * APR_LOCK_foo. Only APR_LOCK_DEFAULT is portable. 00077 */ 00078 APR_DECLARE(apr_status_t) apr_proc_mutex_create(apr_proc_mutex_t **mutex, 00079 const char *fname, 00080 apr_lockmech_e mech, 00081 apr_pool_t *pool); 00082 00083 /** 00084 * Re-open a mutex in a child process. 00085 * @param mutex The newly re-opened mutex structure. 00086 * @param fname A file name to use if the mutex mechanism requires one. This 00087 * argument should always be provided. The mutex code itself will 00088 * determine if it should be used. This filename should be the 00089 * same one that was passed to apr_proc_mutex_create(). 00090 * @param pool The pool to operate on. 00091 * @remark This function must be called to maintain portability, even 00092 * if the underlying lock mechanism does not require it. 00093 */ 00094 APR_DECLARE(apr_status_t) apr_proc_mutex_child_init(apr_proc_mutex_t **mutex, 00095 const char *fname, 00096 apr_pool_t *pool); 00097 00098 /** 00099 * Acquire the lock for the given mutex. If the mutex is already locked, 00100 * the current thread will be put to sleep until the lock becomes available. 00101 * @param mutex the mutex on which to acquire the lock. 00102 */ 00103 APR_DECLARE(apr_status_t) apr_proc_mutex_lock(apr_proc_mutex_t *mutex); 00104 00105 /** 00106 * Attempt to acquire the lock for the given mutex. If the mutex has already 00107 * been acquired, the call returns immediately with APR_EBUSY. Note: it 00108 * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine 00109 * if the return value was APR_EBUSY, for portability reasons. 00110 * @param mutex the mutex on which to attempt the lock acquiring. 00111 */ 00112 APR_DECLARE(apr_status_t) apr_proc_mutex_trylock(apr_proc_mutex_t *mutex); 00113 00114 /** 00115 * Release the lock for the given mutex. 00116 * @param mutex the mutex from which to release the lock. 00117 */ 00118 APR_DECLARE(apr_status_t) apr_proc_mutex_unlock(apr_proc_mutex_t *mutex); 00119 00120 /** 00121 * Destroy the mutex and free the memory associated with the lock. 00122 * @param mutex the mutex to destroy. 00123 */ 00124 APR_DECLARE(apr_status_t) apr_proc_mutex_destroy(apr_proc_mutex_t *mutex); 00125 00126 /** 00127 * Destroy the mutex and free the memory associated with the lock. 00128 * @param mutex the mutex to destroy. 00129 * @note This function is generally used to kill a cleanup on an already 00130 * created mutex 00131 */ 00132 APR_DECLARE(apr_status_t) apr_proc_mutex_cleanup(void *mutex); 00133 00134 /** 00135 * Return the name of the lockfile for the mutex, or NULL 00136 * if the mutex doesn't use a lock file 00137 */ 00138 00139 APR_DECLARE(const char *) apr_proc_mutex_lockfile(apr_proc_mutex_t *mutex); 00140 00141 /** 00142 * Display the name of the mutex, as it relates to the actual method used. 00143 * This matches the valid options for Apache's AcceptMutex directive 00144 * @param mutex the name of the mutex 00145 */ 00146 APR_DECLARE(const char *) apr_proc_mutex_name(apr_proc_mutex_t *mutex); 00147 00148 /** 00149 * Display the name of the default mutex: APR_LOCK_DEFAULT 00150 */ 00151 APR_DECLARE(const char *) apr_proc_mutex_defname(void); 00152 00153 /** 00154 * Get the pool used by this proc_mutex. 00155 * @return apr_pool_t the pool 00156 */ 00157 APR_POOL_DECLARE_ACCESSOR(proc_mutex); 00158 00159 /** @} */ 00160 00161 #ifdef __cplusplus 00162 } 00163 #endif 00164 00165 #endif /* ! APR_PROC_MUTEX_H */