Apache Portable Runtime
apr_thread_mutex.h
Go to the documentation of this file.
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 */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines