1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef APR_THREAD_RWLOCK_H 18#define APR_THREAD_RWLOCK_H 19 20/** 21 * @file apr_thread_rwlock.h 22 * @brief APR Reader/Writer Lock Routines 23 */ 24 25#include "apr.h" 26#include "apr_pools.h" 27#include "apr_errno.h" 28 29#ifdef __cplusplus 30extern "C" { 31#endif /* __cplusplus */ 32 33#if APR_HAS_THREADS 34 35/** 36 * @defgroup apr_thread_rwlock Reader/Writer Lock Routines 37 * @ingroup APR 38 * @{ 39 */ 40 41/** Opaque read-write thread-safe lock. */ 42typedef struct apr_thread_rwlock_t apr_thread_rwlock_t; 43 44/** 45 * Note: The following operations have undefined results: unlocking a 46 * read-write lock which is not locked in the calling thread; write 47 * locking a read-write lock which is already locked by the calling 48 * thread; destroying a read-write lock more than once; clearing or 49 * destroying the pool from which a <b>locked</b> read-write lock is 50 * allocated. 51 */ 52 53/** 54 * Create and initialize a read-write lock that can be used to synchronize 55 * threads. 56 * @param rwlock the memory address where the newly created readwrite lock 57 * will be stored. 58 * @param pool the pool from which to allocate the mutex. 59 */ 60APR_DECLARE(apr_status_t) apr_thread_rwlock_create(apr_thread_rwlock_t **rwlock, 61 apr_pool_t *pool); 62/** 63 * Acquire a shared-read lock on the given read-write lock. This will allow 64 * multiple threads to enter the same critical section while they have acquired 65 * the read lock. 66 * @param rwlock the read-write lock on which to acquire the shared read. 67 */ 68APR_DECLARE(apr_status_t) apr_thread_rwlock_rdlock(apr_thread_rwlock_t *rwlock); 69 70/** 71 * Attempt to acquire the shared-read lock on the given read-write lock. This 72 * is the same as apr_thread_rwlock_rdlock(), only that the function fails 73 * if there is another thread holding the write lock, or if there are any 74 * write threads blocking on the lock. If the function fails for this case, 75 * APR_EBUSY will be returned. Note: it is important that the 76 * APR_STATUS_IS_EBUSY(s) macro be used to determine if the return value was 77 * APR_EBUSY, for portability reasons. 78 * @param rwlock the rwlock on which to attempt the shared read. 79 */ 80APR_DECLARE(apr_status_t) apr_thread_rwlock_tryrdlock(apr_thread_rwlock_t *rwlock); 81 82/** 83 * Acquire an exclusive-write lock on the given read-write lock. This will 84 * allow only one single thread to enter the critical sections. If there 85 * are any threads currently holding the read-lock, this thread is put to 86 * sleep until it can have exclusive access to the lock. 87 * @param rwlock the read-write lock on which to acquire the exclusive write. 88 */ 89APR_DECLARE(apr_status_t) apr_thread_rwlock_wrlock(apr_thread_rwlock_t *rwlock); 90 91/** 92 * Attempt to acquire the exclusive-write lock on the given read-write lock. 93 * This is the same as apr_thread_rwlock_wrlock(), only that the function fails 94 * if there is any other thread holding the lock (for reading or writing), 95 * in which case the function will return APR_EBUSY. Note: it is important 96 * that the APR_STATUS_IS_EBUSY(s) macro be used to determine if the return 97 * value was APR_EBUSY, for portability reasons. 98 * @param rwlock the rwlock on which to attempt the exclusive write. 99 */ 100APR_DECLARE(apr_status_t) apr_thread_rwlock_trywrlock(apr_thread_rwlock_t *rwlock); 101 102/** 103 * Release either the read or write lock currently held by the calling thread 104 * associated with the given read-write lock. 105 * @param rwlock the read-write lock to be released (unlocked). 106 */ 107APR_DECLARE(apr_status_t) apr_thread_rwlock_unlock(apr_thread_rwlock_t *rwlock); 108 109/** 110 * Destroy the read-write lock and free the associated memory. 111 * @param rwlock the rwlock to destroy. 112 */ 113APR_DECLARE(apr_status_t) apr_thread_rwlock_destroy(apr_thread_rwlock_t *rwlock); 114 115/** 116 * Get the pool used by this thread_rwlock. 117 * @return apr_pool_t the pool 118 */ 119APR_POOL_DECLARE_ACCESSOR(thread_rwlock); 120 121#endif /* APR_HAS_THREADS */ 122 123/** @} */ 124 125#ifdef __cplusplus 126} 127#endif 128 129#endif /* ! APR_THREAD_RWLOCK_H */ 130