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_MUTEX_H 18251875Speter#define APR_THREAD_MUTEX_H 19251875Speter 20251875Speter/** 21251875Speter * @file apr_thread_mutex.h 22251875Speter * @brief APR Thread Mutex Routines 23251875Speter */ 24251875Speter 25251875Speter#include "apr.h" 26251875Speter#include "apr_errno.h" 27251875Speter 28251875Speter#ifdef __cplusplus 29251875Speterextern "C" { 30251875Speter#endif /* __cplusplus */ 31251875Speter 32251875Speter#if APR_HAS_THREADS || defined(DOXYGEN) 33251875Speter 34251875Speter/** 35251875Speter * @defgroup apr_thread_mutex Thread Mutex Routines 36251875Speter * @ingroup APR 37251875Speter * @{ 38251875Speter */ 39251875Speter 40251875Speter/** Opaque thread-local mutex structure */ 41251875Spetertypedef struct apr_thread_mutex_t apr_thread_mutex_t; 42251875Speter 43251875Speter#define APR_THREAD_MUTEX_DEFAULT 0x0 /**< platform-optimal lock behavior */ 44251875Speter#define APR_THREAD_MUTEX_NESTED 0x1 /**< enable nested (recursive) locks */ 45251875Speter#define APR_THREAD_MUTEX_UNNESTED 0x2 /**< disable nested locks */ 46362181Sdim#define APR_THREAD_MUTEX_TIMED 0x4 /**< enable timed locks */ 47251875Speter 48251875Speter/* Delayed the include to avoid a circular reference */ 49251875Speter#include "apr_pools.h" 50362181Sdim#include "apr_time.h" 51251875Speter 52251875Speter/** 53251875Speter * Create and initialize a mutex that can be used to synchronize threads. 54251875Speter * @param mutex the memory address where the newly created mutex will be 55251875Speter * stored. 56251875Speter * @param flags Or'ed value of: 57251875Speter * <PRE> 58251875Speter * APR_THREAD_MUTEX_DEFAULT platform-optimal lock behavior. 59251875Speter * APR_THREAD_MUTEX_NESTED enable nested (recursive) locks. 60251875Speter * APR_THREAD_MUTEX_UNNESTED disable nested locks (non-recursive). 61251875Speter * </PRE> 62251875Speter * @param pool the pool from which to allocate the mutex. 63251875Speter * @warning Be cautious in using APR_THREAD_MUTEX_DEFAULT. While this is the 64266735Speter * most optimal mutex based on a given platform's performance characteristics, 65251875Speter * it will behave as either a nested or an unnested lock. 66251875Speter */ 67251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_create(apr_thread_mutex_t **mutex, 68251875Speter unsigned int flags, 69251875Speter apr_pool_t *pool); 70251875Speter/** 71251875Speter * Acquire the lock for the given mutex. If the mutex is already locked, 72251875Speter * the current thread will be put to sleep until the lock becomes available. 73251875Speter * @param mutex the mutex on which to acquire the lock. 74251875Speter */ 75251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_lock(apr_thread_mutex_t *mutex); 76251875Speter 77251875Speter/** 78251875Speter * Attempt to acquire the lock for the given mutex. If the mutex has already 79251875Speter * been acquired, the call returns immediately with APR_EBUSY. Note: it 80251875Speter * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine 81251875Speter * if the return value was APR_EBUSY, for portability reasons. 82251875Speter * @param mutex the mutex on which to attempt the lock acquiring. 83251875Speter */ 84251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_trylock(apr_thread_mutex_t *mutex); 85251875Speter 86251875Speter/** 87362181Sdim * Attempt to acquire the lock for the given mutex until timeout expires. 88362181Sdim * If the acquisition time outs, the call returns with APR_TIMEUP. 89362181Sdim * @param mutex the mutex on which to attempt the lock acquiring. 90362181Sdim * @param timeout the relative timeout (microseconds). 91362181Sdim * @note A timeout negative or nul means immediate attempt, returning 92362181Sdim * APR_TIMEUP without blocking if it the lock is already acquired. 93362181Sdim */ 94362181SdimAPR_DECLARE(apr_status_t) apr_thread_mutex_timedlock(apr_thread_mutex_t *mutex, 95362181Sdim apr_interval_time_t timeout); 96362181Sdim 97362181Sdim/** 98251875Speter * Release the lock for the given mutex. 99251875Speter * @param mutex the mutex from which to release the lock. 100251875Speter */ 101251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_unlock(apr_thread_mutex_t *mutex); 102251875Speter 103251875Speter/** 104251875Speter * Destroy the mutex and free the memory associated with the lock. 105251875Speter * @param mutex the mutex to destroy. 106251875Speter */ 107251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_destroy(apr_thread_mutex_t *mutex); 108251875Speter 109251875Speter/** 110251875Speter * Get the pool used by this thread_mutex. 111251875Speter * @return apr_pool_t the pool 112251875Speter */ 113251875SpeterAPR_POOL_DECLARE_ACCESSOR(thread_mutex); 114251875Speter 115251875Speter#endif /* APR_HAS_THREADS */ 116251875Speter 117251875Speter/** @} */ 118251875Speter 119251875Speter#ifdef __cplusplus 120251875Speter} 121251875Speter#endif 122251875Speter 123251875Speter#endif /* ! APR_THREAD_MUTEX_H */ 124