Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

apr_global_mutex.h

Go to the documentation of this file.
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_GLOBAL_MUTEX_H
00017 #define APR_GLOBAL_MUTEX_H
00018 
00019 /**
00020  * @file apr_global_mutex.h
00021  * @brief APR Global Locking Routines
00022  */
00023 
00024 #include "apr.h"
00025 #include "apr_proc_mutex.h"    /* only for apr_lockmech_e */
00026 #include "apr_pools.h"
00027 #include "apr_errno.h"
00028 #if APR_PROC_MUTEX_IS_GLOBAL
00029 #include "apr_proc_mutex.h"
00030 #endif
00031 
00032 #ifdef __cplusplus
00033 extern "C" {
00034 #endif /* __cplusplus */
00035 
00036 /**
00037  * @defgroup APR_GlobalMutex Global Locking Routines
00038  * @ingroup APR 
00039  * @{
00040  */
00041 
00042 #if !APR_PROC_MUTEX_IS_GLOBAL || defined(DOXYGEN)
00043 
00044 /** Opaque global mutex structure. */
00045 typedef struct apr_global_mutex_t apr_global_mutex_t;
00046 
00047 /*   Function definitions */
00048 
00049 /**
00050  * Create and initialize a mutex that can be used to synchronize both
00051  * processes and threads. Note: There is considerable overhead in using
00052  * this API if only cross-process or cross-thread mutual exclusion is
00053  * required. See apr_proc_mutex.h and apr_thread_mutex.h for more
00054  * specialized lock routines.
00055  * @param mutex the memory address where the newly created mutex will be
00056  *        stored.
00057  * @param fname A file name to use if the lock mechanism requires one.  This
00058  *        argument should always be provided.  The lock code itself will
00059  *        determine if it should be used.
00060  * @param mech The mechanism to use for the interprocess lock, if any; one of
00061  * <PRE>
00062  *            APR_LOCK_FCNTL
00063  *            APR_LOCK_FLOCK
00064  *            APR_LOCK_SYSVSEM
00065  *            APR_LOCK_POSIXSEM
00066  *            APR_LOCK_PROC_PTHREAD
00067  *            APR_LOCK_DEFAULT     pick the default mechanism for the platform
00068  * </PRE>
00069  * @param pool the pool from which to allocate the mutex.
00070  * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
00071  *          APR_LOCK_foo.  Only APR_LOCK_DEFAULT is portable.
00072  */
00073 APR_DECLARE(apr_status_t) apr_global_mutex_create(apr_global_mutex_t **mutex,
00074                                                   const char *fname,
00075                                                   apr_lockmech_e mech,
00076                                                   apr_pool_t *pool);
00077 
00078 /**
00079  * Re-open a mutex in a child process.
00080  * @param mutex The newly re-opened mutex structure.
00081  * @param fname A file name to use if the mutex mechanism requires one.  This
00082  *              argument should always be provided.  The mutex code itself will
00083  *              determine if it should be used.  This filename should be the 
00084  *              same one that was passed to apr_global_mutex_create().
00085  * @param pool The pool to operate on.
00086  * @remark This function must be called to maintain portability, even
00087  *         if the underlying lock mechanism does not require it.
00088  */
00089 APR_DECLARE(apr_status_t) apr_global_mutex_child_init(
00090                               apr_global_mutex_t **mutex,
00091                               const char *fname,
00092                               apr_pool_t *pool);
00093 
00094 /**
00095  * Acquire the lock for the given mutex. If the mutex is already locked,
00096  * the current thread will be put to sleep until the lock becomes available.
00097  * @param mutex the mutex on which to acquire the lock.
00098  */
00099 APR_DECLARE(apr_status_t) apr_global_mutex_lock(apr_global_mutex_t *mutex);
00100 
00101 /**
00102  * Attempt to acquire the lock for the given mutex. If the mutex has already
00103  * been acquired, the call returns immediately with APR_EBUSY. Note: it
00104  * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine
00105  * if the return value was APR_EBUSY, for portability reasons.
00106  * @param mutex the mutex on which to attempt the lock acquiring.
00107  */
00108 APR_DECLARE(apr_status_t) apr_global_mutex_trylock(apr_global_mutex_t *mutex);
00109 
00110 /**
00111  * Release the lock for the given mutex.
00112  * @param mutex the mutex from which to release the lock.
00113  */
00114 APR_DECLARE(apr_status_t) apr_global_mutex_unlock(apr_global_mutex_t *mutex);
00115 
00116 /**
00117  * Destroy the mutex and free the memory associated with the lock.
00118  * @param mutex the mutex to destroy.
00119  */
00120 APR_DECLARE(apr_status_t) apr_global_mutex_destroy(apr_global_mutex_t *mutex);
00121 
00122 /**
00123  * Get the pool used by this global_mutex.
00124  * @return apr_pool_t the pool
00125  */
00126 APR_POOL_DECLARE_ACCESSOR(global_mutex);
00127 
00128 #else /* APR_PROC_MUTEX_IS_GLOBAL */
00129 
00130 /* Some platforms [e.g. Win32] have cross process locks that are truly
00131  * global locks, since there isn't the concept of cross-process locks.
00132  * Define these platforms in terms of an apr_proc_mutex_t.
00133  */
00134 
00135 #define apr_global_mutex_t          apr_proc_mutex_t
00136 #define apr_global_mutex_create     apr_proc_mutex_create
00137 #define apr_global_mutex_child_init apr_proc_mutex_child_init
00138 #define apr_global_mutex_lock       apr_proc_mutex_lock
00139 #define apr_global_mutex_trylock    apr_proc_mutex_trylock
00140 #define apr_global_mutex_unlock     apr_proc_mutex_unlock
00141 #define apr_global_mutex_destroy    apr_proc_mutex_destroy
00142 #define apr_global_mutex_pool_get   apr_proc_mutex_pool_get
00143 
00144 #endif
00145 
00146 /** @} */
00147 
00148 #ifdef __cplusplus
00149 }
00150 #endif
00151 
00152 #endif  /* ndef APR_GLOBAL_MUTEX_H */

Generated on Tue May 10 04:19:07 2005 for Apache Portable Runtime by  doxygen 1.3.9.1