00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_THREAD_MUTEX_H 00018 #define APR_THREAD_MUTEX_H 00019 00020 /** 00021 * @file apr_thread_mutex.h 00022 * @brief APR Thread Mutex Routines 00023 */ 00024 00025 #include "apr.h" 00026 #include "apr_errno.h" 00027 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif /* __cplusplus */ 00031 00032 #if APR_HAS_THREADS || defined(DOXYGEN) 00033 00034 /** 00035 * @defgroup apr_thread_mutex Thread Mutex Routines 00036 * @ingroup APR 00037 * @{ 00038 */ 00039 00040 /** Opaque thread-local mutex structure */ 00041 typedef struct apr_thread_mutex_t apr_thread_mutex_t; 00042 00043 #define APR_THREAD_MUTEX_DEFAULT 0x0 /**< platform-optimal lock behavior */ 00044 #define APR_THREAD_MUTEX_NESTED 0x1 /**< enable nested (recursive) locks */ 00045 #define APR_THREAD_MUTEX_UNNESTED 0x2 /**< disable nested locks */ 00046 00047 /* Delayed the include to avoid a circular reference */ 00048 #include "apr_pools.h" 00049 00050 /** 00051 * Create and initialize a mutex that can be used to synchronize threads. 00052 * @param mutex the memory address where the newly created mutex will be 00053 * stored. 00054 * @param flags Or'ed value of: 00055 * <PRE> 00056 * APR_THREAD_MUTEX_DEFAULT platform-optimal lock behavior. 00057 * APR_THREAD_MUTEX_NESTED enable nested (recursive) locks. 00058 * APR_THREAD_MUTEX_UNNESTED disable nested locks (non-recursive). 00059 * </PRE> 00060 * @param pool the pool from which to allocate the mutex. 00061 * @warning Be cautious in using APR_THREAD_MUTEX_DEFAULT. While this is the 00062 * most optimial mutex based on a given platform's performance charateristics, 00063 * it will behave as either a nested or an unnested lock. 00064 */ 00065 APR_DECLARE(apr_status_t) apr_thread_mutex_create(apr_thread_mutex_t **mutex, 00066 unsigned int flags, 00067 apr_pool_t *pool); 00068 /** 00069 * Acquire the lock for the given mutex. If the mutex is already locked, 00070 * the current thread will be put to sleep until the lock becomes available. 00071 * @param mutex the mutex on which to acquire the lock. 00072 */ 00073 APR_DECLARE(apr_status_t) apr_thread_mutex_lock(apr_thread_mutex_t *mutex); 00074 00075 /** 00076 * Attempt to acquire the lock for the given mutex. If the mutex has already 00077 * been acquired, the call returns immediately with APR_EBUSY. Note: it 00078 * is important that the APR_STATUS_IS_EBUSY(s) macro be used to determine 00079 * if the return value was APR_EBUSY, for portability reasons. 00080 * @param mutex the mutex on which to attempt the lock acquiring. 00081 */ 00082 APR_DECLARE(apr_status_t) apr_thread_mutex_trylock(apr_thread_mutex_t *mutex); 00083 00084 /** 00085 * Release the lock for the given mutex. 00086 * @param mutex the mutex from which to release the lock. 00087 */ 00088 APR_DECLARE(apr_status_t) apr_thread_mutex_unlock(apr_thread_mutex_t *mutex); 00089 00090 /** 00091 * Destroy the mutex and free the memory associated with the lock. 00092 * @param mutex the mutex to destroy. 00093 */ 00094 APR_DECLARE(apr_status_t) apr_thread_mutex_destroy(apr_thread_mutex_t *mutex); 00095 00096 /** 00097 * Get the pool used by this thread_mutex. 00098 * @return apr_pool_t the pool 00099 */ 00100 APR_POOL_DECLARE_ACCESSOR(thread_mutex); 00101 00102 #endif /* APR_HAS_THREADS */ 00103 00104 /** @} */ 00105 00106 #ifdef __cplusplus 00107 } 00108 #endif 00109 00110 #endif /* ! APR_THREAD_MUTEX_H */