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 
00029 #ifdef __cplusplus
00030 extern "C" {
00031 #endif /* __cplusplus */
00032 
00033 /**
00034  * @defgroup apr_proc_mutex Process Locking Routines
00035  * @ingroup APR 
00036  * @{
00037  */
00038 
00039 /** 
00040  * Enumerated potential types for APR process locking methods
00041  * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
00042  *          APR_LOCK_foo.  Only APR_LOCK_DEFAULT is portable.
00043  */
00044 typedef enum {
00045     APR_LOCK_FCNTL,         /**< fcntl() */
00046     APR_LOCK_FLOCK,         /**< flock() */
00047     APR_LOCK_SYSVSEM,       /**< System V Semaphores */
00048     APR_LOCK_PROC_PTHREAD,  /**< POSIX pthread process-based locking */
00049     APR_LOCK_POSIXSEM,      /**< POSIX semaphore process-based locking */
00050     APR_LOCK_DEFAULT        /**< Use the default process lock */
00051 } apr_lockmech_e;
00052 
00053 /** Opaque structure representing a process mutex. */
00054 typedef struct apr_proc_mutex_t apr_proc_mutex_t;
00055 
00056 /*   Function definitions */
00057 
00058 /**
00059  * Create and initialize a mutex that can be used to synchronize processes.
00060  * @param mutex the memory address where the newly created mutex will be
00061  *        stored.
00062  * @param fname A file name to use if the lock mechanism requires one.  This
00063  *        argument should always be provided.  The lock code itself will
00064  *        determine if it should be used.
00065  * @param mech The mechanism to use for the interprocess lock, if any; one of
00066  * <PRE>
00067  *            APR_LOCK_FCNTL
00068  *            APR_LOCK_FLOCK
00069  *            APR_LOCK_SYSVSEM
00070  *            APR_LOCK_POSIXSEM
00071  *            APR_LOCK_PROC_PTHREAD
00072  *            APR_LOCK_DEFAULT     pick the default mechanism for the platform
00073  * </PRE>
00074  * @param pool the pool from which to allocate the mutex.
00075  * @see apr_lockmech_e
00076  * @warning Check APR_HAS_foo_SERIALIZE defines to see if the platform supports
00077  *          APR_LOCK_foo.  Only APR_LOCK_DEFAULT is portable.
00078  */
00079 APR_DECLARE(apr_status_t) apr_proc_mutex_create(apr_proc_mutex_t **mutex,
00080                                                 const char *fname,
00081                                                 apr_lockmech_e mech,
00082                                                 apr_pool_t *pool);
00083 
00084 /**
00085  * Re-open a mutex in a child process.
00086  * @param mutex The newly re-opened mutex structure.
00087  * @param fname A file name to use if the mutex mechanism requires one.  This
00088  *              argument should always be provided.  The mutex code itself will
00089  *              determine if it should be used.  This filename should be the 
00090  *              same one that was passed to apr_proc_mutex_create().
00091  * @param pool The pool to operate on.
00092  * @remark This function must be called to maintain portability, even
00093  *         if the underlying lock mechanism does not require it.
00094  */
00095 APR_DECLARE(apr_status_t) apr_proc_mutex_child_init(apr_proc_mutex_t **mutex,
00096                                                     const char *fname,
00097                                                     apr_pool_t *pool);
00098 
00099 /**
00100  * Acquire the lock for the given mutex. If the mutex is already locked,
00101  * the current thread will be put to sleep until the lock becomes available.
00102  * @param mutex the mutex on which to acquire the lock.
00103  */
00104 APR_DECLARE(apr_status_t) apr_proc_mutex_lock(apr_proc_mutex_t *mutex);
00105 
00106 /**
00107  * Attempt to acquire the lock for the given mutex. If the mutex has already
00108  * been acquired, the call returns immediately with APR_EBUSY. Note: it
00109  * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine
00110  * if the return value was APR_EBUSY, for portability reasons.
00111  * @param mutex the mutex on which to attempt the lock acquiring.
00112  */
00113 APR_DECLARE(apr_status_t) apr_proc_mutex_trylock(apr_proc_mutex_t *mutex);
00114 
00115 /**
00116  * Release the lock for the given mutex.
00117  * @param mutex the mutex from which to release the lock.
00118  */
00119 APR_DECLARE(apr_status_t) apr_proc_mutex_unlock(apr_proc_mutex_t *mutex);
00120 
00121 /**
00122  * Destroy the mutex and free the memory associated with the lock.
00123  * @param mutex the mutex to destroy.
00124  */
00125 APR_DECLARE(apr_status_t) apr_proc_mutex_destroy(apr_proc_mutex_t *mutex);
00126 
00127 /**
00128  * Destroy the mutex and free the memory associated with the lock.
00129  * @param mutex the mutex to destroy.
00130  * @note This function is generally used to kill a cleanup on an already
00131  *       created mutex
00132  */
00133 APR_DECLARE(apr_status_t) apr_proc_mutex_cleanup(void *mutex);
00134 
00135 /**
00136  * Return the name of the lockfile for the mutex, or NULL
00137  * if the mutex doesn't use a lock file
00138  */
00139 
00140 APR_DECLARE(const char *) apr_proc_mutex_lockfile(apr_proc_mutex_t *mutex);
00141 
00142 /**
00143  * Display the name of the mutex, as it relates to the actual method used.
00144  * This matches the valid options for Apache's AcceptMutex directive
00145  * @param mutex the name of the mutex
00146  */
00147 APR_DECLARE(const char *) apr_proc_mutex_name(apr_proc_mutex_t *mutex);
00148 
00149 /**
00150  * Display the name of the default mutex: APR_LOCK_DEFAULT
00151  */
00152 APR_DECLARE(const char *) apr_proc_mutex_defname(void);
00153 
00154 /**
00155  * Get the pool used by this proc_mutex.
00156  * @return apr_pool_t the pool
00157  */
00158 APR_POOL_DECLARE_ACCESSOR(proc_mutex);
00159 
00160 /** @} */
00161 
00162 #ifdef __cplusplus
00163 }
00164 #endif
00165 
00166 #endif  /* ! APR_PROC_MUTEX_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines