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 */ 46251875Speter 47251875Speter/* Delayed the include to avoid a circular reference */ 48251875Speter#include "apr_pools.h" 49251875Speter 50251875Speter/** 51251875Speter * Create and initialize a mutex that can be used to synchronize threads. 52251875Speter * @param mutex the memory address where the newly created mutex will be 53251875Speter * stored. 54251875Speter * @param flags Or'ed value of: 55251875Speter * <PRE> 56251875Speter * APR_THREAD_MUTEX_DEFAULT platform-optimal lock behavior. 57251875Speter * APR_THREAD_MUTEX_NESTED enable nested (recursive) locks. 58251875Speter * APR_THREAD_MUTEX_UNNESTED disable nested locks (non-recursive). 59251875Speter * </PRE> 60251875Speter * @param pool the pool from which to allocate the mutex. 61251875Speter * @warning Be cautious in using APR_THREAD_MUTEX_DEFAULT. While this is the 62269847Speter * most optimal mutex based on a given platform's performance characteristics, 63251875Speter * it will behave as either a nested or an unnested lock. 64251875Speter */ 65251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_create(apr_thread_mutex_t **mutex, 66251875Speter unsigned int flags, 67251875Speter apr_pool_t *pool); 68251875Speter/** 69251875Speter * Acquire the lock for the given mutex. If the mutex is already locked, 70251875Speter * the current thread will be put to sleep until the lock becomes available. 71251875Speter * @param mutex the mutex on which to acquire the lock. 72251875Speter */ 73251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_lock(apr_thread_mutex_t *mutex); 74251875Speter 75251875Speter/** 76251875Speter * Attempt to acquire the lock for the given mutex. If the mutex has already 77251875Speter * been acquired, the call returns immediately with APR_EBUSY. Note: it 78251875Speter * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine 79251875Speter * if the return value was APR_EBUSY, for portability reasons. 80251875Speter * @param mutex the mutex on which to attempt the lock acquiring. 81251875Speter */ 82251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_trylock(apr_thread_mutex_t *mutex); 83251875Speter 84251875Speter/** 85251875Speter * Release the lock for the given mutex. 86251875Speter * @param mutex the mutex from which to release the lock. 87251875Speter */ 88251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_unlock(apr_thread_mutex_t *mutex); 89251875Speter 90251875Speter/** 91251875Speter * Destroy the mutex and free the memory associated with the lock. 92251875Speter * @param mutex the mutex to destroy. 93251875Speter */ 94251875SpeterAPR_DECLARE(apr_status_t) apr_thread_mutex_destroy(apr_thread_mutex_t *mutex); 95251875Speter 96251875Speter/** 97251875Speter * Get the pool used by this thread_mutex. 98251875Speter * @return apr_pool_t the pool 99251875Speter */ 100251875SpeterAPR_POOL_DECLARE_ACCESSOR(thread_mutex); 101251875Speter 102251875Speter#endif /* APR_HAS_THREADS */ 103251875Speter 104251875Speter/** @} */ 105251875Speter 106251875Speter#ifdef __cplusplus 107251875Speter} 108251875Speter#endif 109251875Speter 110251875Speter#endif /* ! APR_THREAD_MUTEX_H */ 111