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 Thu Sep 16 13:47:10 2004 for Apache Portable Runtime by doxygen 1.3.7