1251875Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251875Speter * contributor license agreements. See the NOTICE file distributed with 3251875Speter * this work for additional information regarding copyright ownership. 4251875Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251875Speter * (the "License"); you may not use this file except in compliance with 6251875Speter * the License. You may obtain a copy of the License at 7251875Speter * 8251875Speter * http://www.apache.org/licenses/LICENSE-2.0 9251875Speter * 10251875Speter * Unless required by applicable law or agreed to in writing, software 11251875Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251875Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251875Speter * See the License for the specific language governing permissions and 14251875Speter * limitations under the License. 15251875Speter */ 16251875Speter 17251875Speter#ifndef APR_THREAD_RWLOCK_H 18251875Speter#define APR_THREAD_RWLOCK_H 19251875Speter 20251875Speter/** 21251875Speter * @file apr_thread_rwlock.h 22251875Speter * @brief APR Reader/Writer Lock Routines 23251875Speter */ 24251875Speter 25251875Speter#include "apr.h" 26251875Speter#include "apr_pools.h" 27251875Speter#include "apr_errno.h" 28251875Speter 29251875Speter#ifdef __cplusplus 30251875Speterextern "C" { 31251875Speter#endif /* __cplusplus */ 32251875Speter 33251875Speter#if APR_HAS_THREADS 34251875Speter 35251875Speter/** 36251875Speter * @defgroup apr_thread_rwlock Reader/Writer Lock Routines 37251875Speter * @ingroup APR 38251875Speter * @{ 39251875Speter */ 40251875Speter 41251875Speter/** Opaque read-write thread-safe lock. */ 42251875Spetertypedef struct apr_thread_rwlock_t apr_thread_rwlock_t; 43251875Speter 44251875Speter/** 45251875Speter * Note: The following operations have undefined results: unlocking a 46251875Speter * read-write lock which is not locked in the calling thread; write 47251875Speter * locking a read-write lock which is already locked by the calling 48251875Speter * thread; destroying a read-write lock more than once; clearing or 49251875Speter * destroying the pool from which a <b>locked</b> read-write lock is 50251875Speter * allocated. 51251875Speter */ 52251875Speter 53251875Speter/** 54251875Speter * Create and initialize a read-write lock that can be used to synchronize 55251875Speter * threads. 56251875Speter * @param rwlock the memory address where the newly created readwrite lock 57251875Speter * will be stored. 58251875Speter * @param pool the pool from which to allocate the mutex. 59251875Speter */ 60251875SpeterAPR_DECLARE(apr_status_t) apr_thread_rwlock_create(apr_thread_rwlock_t **rwlock, 61251875Speter apr_pool_t *pool); 62251875Speter/** 63251875Speter * Acquire a shared-read lock on the given read-write lock. This will allow 64251875Speter * multiple threads to enter the same critical section while they have acquired 65251875Speter * the read lock. 66251875Speter * @param rwlock the read-write lock on which to acquire the shared read. 67251875Speter */ 68251875SpeterAPR_DECLARE(apr_status_t) apr_thread_rwlock_rdlock(apr_thread_rwlock_t *rwlock); 69251875Speter 70251875Speter/** 71251875Speter * Attempt to acquire the shared-read lock on the given read-write lock. This 72251875Speter * is the same as apr_thread_rwlock_rdlock(), only that the function fails 73251875Speter * if there is another thread holding the write lock, or if there are any 74251875Speter * write threads blocking on the lock. If the function fails for this case, 75251875Speter * APR_EBUSY will be returned. Note: it is important that the 76251875Speter * APR_STATUS_IS_EBUSY(s) macro be used to determine if the return value was 77251875Speter * APR_EBUSY, for portability reasons. 78251875Speter * @param rwlock the rwlock on which to attempt the shared read. 79251875Speter */ 80251875SpeterAPR_DECLARE(apr_status_t) apr_thread_rwlock_tryrdlock(apr_thread_rwlock_t *rwlock); 81251875Speter 82251875Speter/** 83251875Speter * Acquire an exclusive-write lock on the given read-write lock. This will 84251875Speter * allow only one single thread to enter the critical sections. If there 85251875Speter * are any threads currently holding the read-lock, this thread is put to 86251875Speter * sleep until it can have exclusive access to the lock. 87251875Speter * @param rwlock the read-write lock on which to acquire the exclusive write. 88251875Speter */ 89251875SpeterAPR_DECLARE(apr_status_t) apr_thread_rwlock_wrlock(apr_thread_rwlock_t *rwlock); 90251875Speter 91251875Speter/** 92251875Speter * Attempt to acquire the exclusive-write lock on the given read-write lock. 93251875Speter * This is the same as apr_thread_rwlock_wrlock(), only that the function fails 94251875Speter * if there is any other thread holding the lock (for reading or writing), 95251875Speter * in which case the function will return APR_EBUSY. Note: it is important 96251875Speter * that the APR_STATUS_IS_EBUSY(s) macro be used to determine if the return 97251875Speter * value was APR_EBUSY, for portability reasons. 98251875Speter * @param rwlock the rwlock on which to attempt the exclusive write. 99251875Speter */ 100251875SpeterAPR_DECLARE(apr_status_t) apr_thread_rwlock_trywrlock(apr_thread_rwlock_t *rwlock); 101251875Speter 102251875Speter/** 103251875Speter * Release either the read or write lock currently held by the calling thread 104251875Speter * associated with the given read-write lock. 105251875Speter * @param rwlock the read-write lock to be released (unlocked). 106251875Speter */ 107251875SpeterAPR_DECLARE(apr_status_t) apr_thread_rwlock_unlock(apr_thread_rwlock_t *rwlock); 108251875Speter 109251875Speter/** 110251875Speter * Destroy the read-write lock and free the associated memory. 111251875Speter * @param rwlock the rwlock to destroy. 112251875Speter */ 113251875SpeterAPR_DECLARE(apr_status_t) apr_thread_rwlock_destroy(apr_thread_rwlock_t *rwlock); 114251875Speter 115251875Speter/** 116251875Speter * Get the pool used by this thread_rwlock. 117251875Speter * @return apr_pool_t the pool 118251875Speter */ 119251875SpeterAPR_POOL_DECLARE_ACCESSOR(thread_rwlock); 120251875Speter 121251875Speter#endif /* APR_HAS_THREADS */ 122251875Speter 123251875Speter/** @} */ 124251875Speter 125251875Speter#ifdef __cplusplus 126251875Speter} 127251875Speter#endif 128251875Speter 129251875Speter#endif /* ! APR_THREAD_RWLOCK_H */ 130