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