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

apr_thread_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_THREAD_MUTEX_H
00017 #define APR_THREAD_MUTEX_H
00018 
00019 /**
00020  * @file apr_thread_mutex.h
00021  * @brief APR Thread Mutex Routines
00022  */
00023 
00024 #include "apr.h"
00025 #include "apr_errno.h"
00026 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif /* __cplusplus */
00030 
00031 #if APR_HAS_THREADS || defined(DOXYGEN)
00032 
00033 /**
00034  * @defgroup apr_thread_mutex Thread Mutex Routines
00035  * @ingroup APR 
00036  * @{
00037  */
00038 
00039 /** Opaque thread-local mutex structure */
00040 typedef struct apr_thread_mutex_t apr_thread_mutex_t;
00041 
00042 #define APR_THREAD_MUTEX_DEFAULT  0x0   /**< platform-optimal lock behavior */
00043 #define APR_THREAD_MUTEX_NESTED   0x1   /**< enable nested (recursive) locks */
00044 #define APR_THREAD_MUTEX_UNNESTED 0x2   /**< disable nested locks */
00045 
00046 /* Delayed the include to avoid a circular reference */
00047 #include "apr_pools.h"
00048 
00049 /**
00050  * Create and initialize a mutex that can be used to synchronize threads.
00051  * @param mutex the memory address where the newly created mutex will be
00052  *        stored.
00053  * @param flags Or'ed value of:
00054  * <PRE>
00055  *           APR_THREAD_MUTEX_DEFAULT   platform-optimal lock behavior.
00056  *           APR_THREAD_MUTEX_NESTED    enable nested (recursive) locks.
00057  *           APR_THREAD_MUTEX_UNNESTED  disable nested locks (non-recursive).
00058  * </PRE>
00059  * @param pool the pool from which to allocate the mutex.
00060  * @warning Be cautious in using APR_THREAD_MUTEX_DEFAULT.  While this is the
00061  * most optimial mutex based on a given platform's performance charateristics,
00062  * it will behave as either a nested or an unnested lock.
00063  */
00064 APR_DECLARE(apr_status_t) apr_thread_mutex_create(apr_thread_mutex_t **mutex,
00065                                                   unsigned int flags,
00066                                                   apr_pool_t *pool);
00067 /**
00068  * Acquire the lock for the given mutex. If the mutex is already locked,
00069  * the current thread will be put to sleep until the lock becomes available.
00070  * @param mutex the mutex on which to acquire the lock.
00071  */
00072 APR_DECLARE(apr_status_t) apr_thread_mutex_lock(apr_thread_mutex_t *mutex);
00073 
00074 /**
00075  * Attempt to acquire the lock for the given mutex. If the mutex has already
00076  * been acquired, the call returns immediately with APR_EBUSY. Note: it
00077  * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine
00078  * if the return value was APR_EBUSY, for portability reasons.
00079  * @param mutex the mutex on which to attempt the lock acquiring.
00080  */
00081 APR_DECLARE(apr_status_t) apr_thread_mutex_trylock(apr_thread_mutex_t *mutex);
00082 
00083 /**
00084  * Release the lock for the given mutex.
00085  * @param mutex the mutex from which to release the lock.
00086  */
00087 APR_DECLARE(apr_status_t) apr_thread_mutex_unlock(apr_thread_mutex_t *mutex);
00088 
00089 /**
00090  * Destroy the mutex and free the memory associated with the lock.
00091  * @param mutex the mutex to destroy.
00092  */
00093 APR_DECLARE(apr_status_t) apr_thread_mutex_destroy(apr_thread_mutex_t *mutex);
00094 
00095 /**
00096  * Get the pool used by this thread_mutex.
00097  * @return apr_pool_t the pool
00098  */
00099 APR_POOL_DECLARE_ACCESSOR(thread_mutex);
00100 
00101 #endif /* APR_HAS_THREADS */
00102 
00103 /** @} */
00104 
00105 #ifdef __cplusplus
00106 }
00107 #endif
00108 
00109 #endif  /* ! APR_THREAD_MUTEX_H */

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