apr_thread_cond.h revision 251875
1219820Sjeff/* Licensed to the Apache Software Foundation (ASF) under one or more 2219820Sjeff * contributor license agreements. See the NOTICE file distributed with 3219820Sjeff * this work for additional information regarding copyright ownership. 4219820Sjeff * The ASF licenses this file to You under the Apache License, Version 2.0 5311803Shselasky * (the "License"); you may not use this file except in compliance with 6219820Sjeff * the License. You may obtain a copy of the License at 7219820Sjeff * 8219820Sjeff * http://www.apache.org/licenses/LICENSE-2.0 9219820Sjeff * 10219820Sjeff * Unless required by applicable law or agreed to in writing, software 11219820Sjeff * distributed under the License is distributed on an "AS IS" BASIS, 12219820Sjeff * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13219820Sjeff * See the License for the specific language governing permissions and 14219820Sjeff * limitations under the License. 15219820Sjeff */ 16219820Sjeff 17219820Sjeff#ifndef APR_THREAD_COND_H 18219820Sjeff#define APR_THREAD_COND_H 19219820Sjeff 20219820Sjeff/** 21219820Sjeff * @file apr_thread_cond.h 22219820Sjeff * @brief APR Condition Variable Routines 23219820Sjeff */ 24219820Sjeff 25219820Sjeff#include "apr.h" 26219820Sjeff#include "apr_pools.h" 27219820Sjeff#include "apr_errno.h" 28289644Shselasky#include "apr_time.h" 29289644Shselasky#include "apr_thread_mutex.h" 30219820Sjeff 31219820Sjeff#ifdef __cplusplus 32219820Sjeffextern "C" { 33219820Sjeff#endif /* __cplusplus */ 34280764Shselasky 35280764Shselasky#if APR_HAS_THREADS || defined(DOXYGEN) 36219820Sjeff 37219820Sjeff/** 38219820Sjeff * @defgroup apr_thread_cond Condition Variable Routines 39219820Sjeff * @ingroup APR 40219820Sjeff * @{ 41219820Sjeff */ 42219820Sjeff 43219820Sjeff/** Opaque structure for thread condition variables */ 44219820Sjefftypedef struct apr_thread_cond_t apr_thread_cond_t; 45219820Sjeff 46219820Sjeff/** 47219820Sjeff * Note: destroying a condition variable (or likewise, destroying or 48219820Sjeff * clearing the pool from which a condition variable was allocated) if 49219820Sjeff * any threads are blocked waiting on it gives undefined results. 50219820Sjeff */ 51219820Sjeff 52219820Sjeff/** 53219820Sjeff * Create and initialize a condition variable that can be used to signal 54219820Sjeff * and schedule threads in a single process. 55219820Sjeff * @param cond the memory address where the newly created condition variable 56219820Sjeff * will be stored. 57219820Sjeff * @param pool the pool from which to allocate the condition. 58219820Sjeff */ 59219820SjeffAPR_DECLARE(apr_status_t) apr_thread_cond_create(apr_thread_cond_t **cond, 60219820Sjeff apr_pool_t *pool); 61219820Sjeff 62219820Sjeff/** 63219820Sjeff * Put the active calling thread to sleep until signaled to wake up. Each 64219820Sjeff * condition variable must be associated with a mutex, and that mutex must 65219820Sjeff * be locked before calling this function, or the behavior will be 66219820Sjeff * undefined. As the calling thread is put to sleep, the given mutex 67219820Sjeff * will be simultaneously released; and as this thread wakes up the lock 68219820Sjeff * is again simultaneously acquired. 69219820Sjeff * @param cond the condition variable on which to block. 70219820Sjeff * @param mutex the mutex that must be locked upon entering this function, 71219820Sjeff * is released while the thread is asleep, and is again acquired before 72219820Sjeff * returning from this function. 73219820Sjeff * @remark Spurious wakeups may occur. Before and after every call to wait on 74219820Sjeff * a condition variable, the caller should test whether the condition is already 75219820Sjeff * met. 76219820Sjeff */ 77219820SjeffAPR_DECLARE(apr_status_t) apr_thread_cond_wait(apr_thread_cond_t *cond, 78219820Sjeff apr_thread_mutex_t *mutex); 79219820Sjeff 80219820Sjeff/** 81251617Sjhb * Put the active calling thread to sleep until signaled to wake up or 82219820Sjeff * the timeout is reached. Each condition variable must be associated 83219820Sjeff * with a mutex, and that mutex must be locked before calling this 84219820Sjeff * function, or the behavior will be undefined. As the calling thread 85219820Sjeff * is put to sleep, the given mutex will be simultaneously released; 86219820Sjeff * and as this thread wakes up the lock is again simultaneously acquired. 87219820Sjeff * @param cond the condition variable on which to block. 88219820Sjeff * @param mutex the mutex that must be locked upon entering this function, 89219820Sjeff * is released while the thread is asleep, and is again acquired before 90219820Sjeff * returning from this function. 91219820Sjeff * @param timeout The amount of time in microseconds to wait. This is 92219820Sjeff * a maximum, not a minimum. If the condition is signaled, we 93219820Sjeff * will wake up before this time, otherwise the error APR_TIMEUP 94219820Sjeff * is returned. 95219820Sjeff */ 96219820SjeffAPR_DECLARE(apr_status_t) apr_thread_cond_timedwait(apr_thread_cond_t *cond, 97219820Sjeff apr_thread_mutex_t *mutex, 98219820Sjeff apr_interval_time_t timeout); 99219820Sjeff 100219820Sjeff/** 101219820Sjeff * Signals a single thread, if one exists, that is blocking on the given 102219820Sjeff * condition variable. That thread is then scheduled to wake up and acquire 103219820Sjeff * the associated mutex. Although it is not required, if predictable scheduling 104219820Sjeff * is desired, that mutex must be locked while calling this function. 105219820Sjeff * @param cond the condition variable on which to produce the signal. 106219820Sjeff * @remark If no threads are waiting on the condition variable, nothing happens. 107219820Sjeff */ 108219820SjeffAPR_DECLARE(apr_status_t) apr_thread_cond_signal(apr_thread_cond_t *cond); 109219820Sjeff 110219820Sjeff/** 111219820Sjeff * Signals all threads blocking on the given condition variable. 112219820Sjeff * Each thread that was signaled is then scheduled to wake up and acquire 113219820Sjeff * the associated mutex. This will happen in a serialized manner. 114270710Shselasky * @param cond the condition variable on which to produce the broadcast. 115270710Shselasky * @remark If no threads are waiting on the condition variable, nothing happens. 116270710Shselasky */ 117270710ShselaskyAPR_DECLARE(apr_status_t) apr_thread_cond_broadcast(apr_thread_cond_t *cond); 118270710Shselasky 119270710Shselasky/** 120219820Sjeff * Destroy the condition variable and free the associated memory. 121219820Sjeff * @param cond the condition variable to destroy. 122219820Sjeff */ 123219820SjeffAPR_DECLARE(apr_status_t) apr_thread_cond_destroy(apr_thread_cond_t *cond); 124219820Sjeff 125219820Sjeff/** 126219820Sjeff * Get the pool used by this thread_cond. 127219820Sjeff * @return apr_pool_t the pool 128219820Sjeff */ 129219820SjeffAPR_POOL_DECLARE_ACCESSOR(thread_cond); 130219820Sjeff 131219820Sjeff#endif /* APR_HAS_THREADS */ 132219820Sjeff 133219820Sjeff/** @} */ 134219820Sjeff 135219820Sjeff#ifdef __cplusplus 136219820Sjeff} 137219820Sjeff#endif 138219820Sjeff 139219820Sjeff#endif /* ! APR_THREAD_COND_H */ 140219820Sjeff