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

apr_thread_rwlock.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_RWLOCK_H
00017 #define APR_THREAD_RWLOCK_H
00018 
00019 /**
00020  * @file apr_thread_rwlock.h
00021  * @brief APR Reader/Writer Lock 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 #if APR_HAS_THREADS
00033 
00034 /**
00035  * @defgroup apr_thread_rwlock Reader/Writer Lock Routines
00036  * @ingroup APR 
00037  * @{
00038  */
00039 
00040 /** Opaque read-write thread-safe lock. */
00041 typedef struct apr_thread_rwlock_t apr_thread_rwlock_t;
00042 
00043 /**
00044  * Note: The following operations have undefined results: unlocking a
00045  * read-write lock which is not locked in the calling thread; write
00046  * locking a read-write lock which is already locked by the calling
00047  * thread; destroying a read-write lock more than once; clearing or
00048  * destroying the pool from which a <b>locked</b> read-write lock is
00049  * allocated.
00050  */
00051 
00052 /**
00053  * Create and initialize a read-write lock that can be used to synchronize
00054  * threads.
00055  * @param rwlock the memory address where the newly created readwrite lock
00056  *        will be stored.
00057  * @param pool the pool from which to allocate the mutex.
00058  */
00059 APR_DECLARE(apr_status_t) apr_thread_rwlock_create(apr_thread_rwlock_t **rwlock,
00060                                                    apr_pool_t *pool);
00061 /**
00062  * Acquire a shared-read lock on the given read-write lock. This will allow
00063  * multiple threads to enter the same critical section while they have acquired
00064  * the read lock.
00065  * @param rwlock the read-write lock on which to acquire the shared read.
00066  */
00067 APR_DECLARE(apr_status_t) apr_thread_rwlock_rdlock(apr_thread_rwlock_t *rwlock);
00068 
00069 /**
00070  * Attempt to acquire the shared-read lock on the given read-write lock. This
00071  * is the same as apr_thread_rwlock_rdlock(), only that the function fails
00072  * if there is another thread holding the write lock, or if there are any
00073  * write threads blocking on the lock. If the function fails for this case,
00074  * APR_EBUSY will be returned. Note: it is important that the
00075  * APR_STATUS_IS_EBUSY(s) macro be used to determine if the return value was
00076  * APR_EBUSY, for portability reasons.
00077  * @param rwlock the rwlock on which to attempt the shared read.
00078  */
00079 APR_DECLARE(apr_status_t) apr_thread_rwlock_tryrdlock(apr_thread_rwlock_t *rwlock);
00080 
00081 /**
00082  * Acquire an exclusive-write lock on the given read-write lock. This will
00083  * allow only one single thread to enter the critical sections. If there
00084  * are any threads currently holding the read-lock, this thread is put to
00085  * sleep until it can have exclusive access to the lock.
00086  * @param rwlock the read-write lock on which to acquire the exclusive write.
00087  */
00088 APR_DECLARE(apr_status_t) apr_thread_rwlock_wrlock(apr_thread_rwlock_t *rwlock);
00089 
00090 /**
00091  * Attempt to acquire the exclusive-write lock on the given read-write lock. 
00092  * This is the same as apr_thread_rwlock_wrlock(), only that the function fails
00093  * if there is any other thread holding the lock (for reading or writing),
00094  * in which case the function will return APR_EBUSY. Note: it is important
00095  * that the APR_STATUS_IS_EBUSY(s) macro be used to determine if the return
00096  * value was APR_EBUSY, for portability reasons.
00097  * @param rwlock the rwlock on which to attempt the exclusive write.
00098  */
00099 APR_DECLARE(apr_status_t) apr_thread_rwlock_trywrlock(apr_thread_rwlock_t *rwlock);
00100 
00101 /**
00102  * Release either the read or write lock currently held by the calling thread
00103  * associated with the given read-write lock.
00104  * @param rwlock the read-write lock to be released (unlocked).
00105  */
00106 APR_DECLARE(apr_status_t) apr_thread_rwlock_unlock(apr_thread_rwlock_t *rwlock);
00107 
00108 /**
00109  * Destroy the read-write lock and free the associated memory.
00110  * @param rwlock the rwlock to destroy.
00111  */
00112 APR_DECLARE(apr_status_t) apr_thread_rwlock_destroy(apr_thread_rwlock_t *rwlock);
00113 
00114 /**
00115  * Get the pool used by this thread_rwlock.
00116  * @return apr_pool_t the pool
00117  */
00118 APR_POOL_DECLARE_ACCESSOR(thread_rwlock);
00119 
00120 #endif  /* APR_HAS_THREADS */
00121 
00122 /** @} */
00123 
00124 #ifdef __cplusplus
00125 }
00126 #endif
00127 
00128 #endif  /* ! APR_THREAD_RWLOCK_H */

Generated on Sun Mar 20 19:52:26 2005 for Apache Portable Runtime by  doxygen 1.3.9.1