00001 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 00002 /* 00003 * Copyright (c) 2008 University of Washington 00004 * 00005 * This program is free software; you can redistribute it and/or modify 00006 * it under the terms of the GNU General Public License version 2 as 00007 * published by the Free Software Foundation; 00008 * 00009 * This program is distributed in the hope that it will be useful, 00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 * GNU General Public License for more details. 00013 * 00014 * You should have received a copy of the GNU General Public License 00015 * along with this program; if not, write to the Free Software 00016 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00017 */ 00018 00019 #ifndef SYSTEM_CONDITION_H 00020 #define SYSTEM_CONDITION_H 00021 00022 #include "ptr.h" 00023 00024 namespace ns3 { 00025 00026 class SystemConditionPrivate; 00027 00028 /** 00029 * @brief A class which provides a relatively platform-independent 00030 * conditional-wait thread synchronization primitive. 00031 * 00032 * It is often desirable to have a mechanism by which a thread can suspend its 00033 * execution and relinquish the process until some condition to becomes true. 00034 * We provide platform-independent access to this OS-dependent capability with 00035 * the SystemCondition class. 00036 * 00037 * There are two ways to tell the underlying primitive that the condition has 00038 * become true: Signal and Broadcast. Signal will only wake up one thread 00039 * waiting on the condition (according to the OS scheduling policy); 00040 * Broadcast will wake up all of the threads waiting on the condition 00041 * (cf. "The Thundering Herd"). 00042 * 00043 * In order to wait for the underlying condition, you also have two 00044 * alternatives: Wait and TimedWait. The Wait call will wait forever for the 00045 * condition to become true; but the TimedWait has a timeout. 00046 * 00047 * The condition underlying this class is a simple boolean variable. It is 00048 * set to false in each call to Wait and TimedWait. It is set to true in each 00049 * call to Signal and Broadcast. This is a fairly simple-minded condition 00050 * designed for 00051 * 00052 * A typical use case will be to call Wait() or TimedWait() in one thread 00053 * context and put the processor to sleep until an event happens somewhere 00054 * else that 00055 */ 00056 class SystemCondition 00057 { 00058 public: 00059 SystemCondition (); 00060 ~SystemCondition (); 00061 00062 /** 00063 * Set the value of the underlying condition. 00064 */ 00065 void SetCondition (bool condition); 00066 00067 /** 00068 * Get the value of the underlying condition. 00069 */ 00070 bool GetCondition (void); 00071 00072 /** 00073 * Release one thread if waiting for the condition to be true. If you want 00074 * a waiting thread to return, you should have done a SetCondition (true) 00075 * prior to calling. 00076 */ 00077 void Signal (void); 00078 00079 /** 00080 * Release all threads waiting for the condition to be true. If you want 00081 * all waiting threads to return, you should have done a SetCondition (true) 00082 * prior to calling. 00083 */ 00084 void Broadcast (void); 00085 00086 /** 00087 * Wait, possibly forever, for the condition to be true. 00088 */ 00089 void Wait (void); 00090 00091 /** 00092 * Wait a maximum of ns nanoseconds for the condition to be true. If the 00093 * wait times out, return true else return false. 00094 */ 00095 bool TimedWait (uint64_t ns); 00096 00097 00098 private: 00099 SystemConditionPrivate * m_priv; 00100 }; 00101 00102 } //namespace ns3 00103 00104 #endif /* SYSTEM_CONDITION_H */ 00105 00106