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