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

apr_proc_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_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 */

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