apr_thread_rwlock.h revision 251875
11553Srgrimes/* Licensed to the Apache Software Foundation (ASF) under one or more 21553Srgrimes * contributor license agreements. See the NOTICE file distributed with 31553Srgrimes * this work for additional information regarding copyright ownership. 41553Srgrimes * The ASF licenses this file to You under the Apache License, Version 2.0 51553Srgrimes * (the "License"); you may not use this file except in compliance with 61553Srgrimes * the License. You may obtain a copy of the License at 71553Srgrimes * 81553Srgrimes * http://www.apache.org/licenses/LICENSE-2.0 91553Srgrimes * 101553Srgrimes * Unless required by applicable law or agreed to in writing, software 111553Srgrimes * distributed under the License is distributed on an "AS IS" BASIS, 121553Srgrimes * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 131553Srgrimes * See the License for the specific language governing permissions and 141553Srgrimes * limitations under the License. 151553Srgrimes */ 161553Srgrimes 171553Srgrimes#ifndef APR_THREAD_RWLOCK_H 181553Srgrimes#define APR_THREAD_RWLOCK_H 191553Srgrimes 201553Srgrimes/** 211553Srgrimes * @file apr_thread_rwlock.h 221553Srgrimes * @brief APR Reader/Writer Lock Routines 231553Srgrimes */ 241553Srgrimes 251553Srgrimes#include "apr.h" 261553Srgrimes#include "apr_pools.h" 271553Srgrimes#include "apr_errno.h" 282657Scsgr 2950479Speter#ifdef __cplusplus 301553Srgrimesextern "C" { 31175254Smaxim#endif /* __cplusplus */ 321553Srgrimes 3379537Sru#if APR_HAS_THREADS 341553Srgrimes 351553Srgrimes/** 361553Srgrimes * @defgroup apr_thread_rwlock Reader/Writer Lock Routines 371553Srgrimes * @ingroup APR 381553Srgrimes * @{ 3968965Sru */ 401553Srgrimes 412659Scsgr/** Opaque read-write thread-safe lock. */ 4248697Ssheldonhtypedef struct apr_thread_rwlock_t apr_thread_rwlock_t; 4348697Ssheldonh 4433794Spst/** 4533794Spst * Note: The following operations have undefined results: unlocking a 4671898Sru * read-write lock which is not locked in the calling thread; write 4717482Sjulian * locking a read-write lock which is already locked by the calling 4833794Spst * thread; destroying a read-write lock more than once; clearing or 49101474Sume * destroying the pool from which a <b>locked</b> read-write lock is 501553Srgrimes * allocated. 511553Srgrimes */ 521553Srgrimes 5329602Scharnier/** 5499968Scharnier * Create and initialize a read-write lock that can be used to synchronize 551553Srgrimes * threads. 561553Srgrimes * @param rwlock the memory address where the newly created readwrite lock 571553Srgrimes * will be stored. 581553Srgrimes * @param pool the pool from which to allocate the mutex. 59131500Sru */ 60131500SruAPR_DECLARE(apr_status_t) apr_thread_rwlock_create(apr_thread_rwlock_t **rwlock, 611553Srgrimes apr_pool_t *pool); 621553Srgrimes/** 631553Srgrimes * Acquire a shared-read lock on the given read-write lock. This will allow 641553Srgrimes * multiple threads to enter the same critical section while they have acquired 651553Srgrimes * the read lock. 661553Srgrimes * @param rwlock the read-write lock on which to acquire the shared read. 6729602Scharnier */ 681553SrgrimesAPR_DECLARE(apr_status_t) apr_thread_rwlock_rdlock(apr_thread_rwlock_t *rwlock); 69131500Sru 70131500Sru/** 7129602Scharnier * Attempt to acquire the shared-read lock on the given read-write lock. This 721553Srgrimes * is the same as apr_thread_rwlock_rdlock(), only that the function fails 731553Srgrimes * if there is another thread holding the write lock, or if there are any 741553Srgrimes * write threads blocking on the lock. If the function fails for this case, 7529602Scharnier * APR_EBUSY will be returned. Note: it is important that the 7629602Scharnier * APR_STATUS_IS_EBUSY(s) macro be used to determine if the return value was 771553Srgrimes * APR_EBUSY, for portability reasons. 7829602Scharnier * @param rwlock the rwlock on which to attempt the shared read. 792659Scsgr */ 8057652SsheldonhAPR_DECLARE(apr_status_t) apr_thread_rwlock_tryrdlock(apr_thread_rwlock_t *rwlock); 8148279Ssheldonh 8257630Ssheldonh/** 8357630Ssheldonh * Acquire an exclusive-write lock on the given read-write lock. This will 8448279Ssheldonh * allow only one single thread to enter the critical sections. If there 8548279Ssheldonh * are any threads currently holding the read-lock, this thread is put to 8648697Ssheldonh * sleep until it can have exclusive access to the lock. 8748697Ssheldonh * @param rwlock the read-write lock on which to acquire the exclusive write. 8868965Sru */ 8933794SpstAPR_DECLARE(apr_status_t) apr_thread_rwlock_wrlock(apr_thread_rwlock_t *rwlock); 9064197Sdwmalone 9164197Sdwmalone/** 9264197Sdwmalone * Attempt to acquire the exclusive-write lock on the given read-write lock. 9333794Spst * This is the same as apr_thread_rwlock_wrlock(), only that the function fails 9433794Spst * if there is any other thread holding the lock (for reading or writing), 9533794Spst * in which case the function will return APR_EBUSY. Note: it is important 9633794Spst * that the APR_STATUS_IS_EBUSY(s) macro be used to determine if the return 9733794Spst * value was APR_EBUSY, for portability reasons. 9833794Spst * @param rwlock the rwlock on which to attempt the exclusive write. 9933794Spst */ 1001553SrgrimesAPR_DECLARE(apr_status_t) apr_thread_rwlock_trywrlock(apr_thread_rwlock_t *rwlock); 10129602Scharnier 10211379Sdg/** 10364197Sdwmalone * Release either the read or write lock currently held by the calling thread 104101474Sume * associated with the given read-write lock. 105101474Sume * @param rwlock the read-write lock to be released (unlocked). 106101474Sume */ 107101474SumeAPR_DECLARE(apr_status_t) apr_thread_rwlock_unlock(apr_thread_rwlock_t *rwlock); 108101474Sume 109101474Sume/** 11017482Sjulian * Destroy the read-write lock and free the associated memory. 11167881Sn_hibma * @param rwlock the rwlock to destroy. 11256731Ssheldonh */ 11356731SsheldonhAPR_DECLARE(apr_status_t) apr_thread_rwlock_destroy(apr_thread_rwlock_t *rwlock); 11456731Ssheldonh 11556731Ssheldonh/** 11656731Ssheldonh * Get the pool used by this thread_rwlock. 11756731Ssheldonh * @return apr_pool_t the pool 11856590Sshin */ 119155318SceriAPR_POOL_DECLARE_ACCESSOR(thread_rwlock); 12056731Ssheldonh 12156731Ssheldonh#endif /* APR_HAS_THREADS */ 12256731Ssheldonh 123155318Sceri/** @} */ 12456731Ssheldonh 12556731Ssheldonh#ifdef __cplusplus 12656731Ssheldonh} 12756731Ssheldonh#endif 12856731Ssheldonh 12956731Ssheldonh#endif /* ! APR_THREAD_RWLOCK_H */ 13056590Sshin