src/core/system-condition.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Sat, 04 Jul 2009 08:15:48 +0200
changeset 4654 2eaebe77d66b
permissions -rw-r--r--
Added tag ns-3.5 for changeset c975274c9707
     1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
     2 /*
     3  * Copyright (c) 2008 University of Washington
     4  *
     5  * This program is free software; you can redistribute it and/or modify
     6  * it under the terms of the GNU General Public License version 2 as
     7  * published by the Free Software Foundation;
     8  *
     9  * This program is distributed in the hope that it will be useful,
    10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    12  * GNU General Public License for more details.
    13  *
    14  * You should have received a copy of the GNU General Public License
    15  * along with this program; if not, write to the Free Software
    16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    17  */
    18 
    19 #ifndef SYSTEM_CONDITION_H
    20 #define SYSTEM_CONDITION_H
    21 
    22 #include "ptr.h"
    23 
    24 namespace ns3 { 
    25 	
    26 class SystemConditionPrivate;
    27 
    28 /**
    29  * @brief A class which provides a relatively platform-independent 
    30  * conditional-wait thread synchronization primitive.
    31  *
    32  * It is often desirable to have a mechanism by which a thread can suspend its
    33  * execution and relinquish the process until some condition to becomes true.
    34  * We provide platform-independent access to this OS-dependent capability with
    35  * the SystemCondition class.
    36  *
    37  * There are two ways to tell the underlying primitive that the condition has
    38  * become true:  Signal and Broadcast.  Signal will only wake up one thread
    39  * waiting on the condition (according to the OS scheduling policy); 
    40  * Broadcast will wake up all of the threads waiting on the condition 
    41  * (cf. "The Thundering Herd").
    42  * 
    43  * In order to wait for the underlying condition, you also have two
    44  * alternatives:  Wait and TimedWait.  The Wait call will wait forever for the
    45  * condition to become true; but the TimedWait has a timeout.
    46  *
    47  * The condition underlying this class is a simple boolean variable.  It is
    48  * set to false in each call to Wait and TimedWait.  It is set to true in each
    49  * call to Signal and Broadcast.  This is a fairly simple-minded condition
    50  * designed for 
    51  *
    52  * A typical use case will be to call Wait() or TimedWait() in one thread
    53  * context and put the processor to sleep until an event happens somewhere 
    54  * else that 
    55  */
    56 class SystemCondition
    57 {
    58 public:
    59   SystemCondition ();
    60   ~SystemCondition ();
    61 
    62   /**
    63    * Set the value of the underlying condition.
    64    */
    65   void SetCondition (bool condition);
    66 
    67   /**
    68    * Get the value of the underlying condition.
    69    */
    70   bool GetCondition (void);
    71 
    72   /**
    73    * Release one thread if waiting for the condition to be true.  If you want 
    74    * a waiting thread to return, you should have done a SetCondition (true)
    75    * prior to calling.
    76    */
    77   void Signal (void);
    78 
    79   /**
    80    * Release all threads waiting for the condition to be true.  If you want 
    81    * all waiting threads to return, you should have done a SetCondition (true)
    82    * prior to calling.
    83    */
    84   void Broadcast (void);
    85 
    86   /**
    87    * Wait, possibly forever, for the condition to be true.  
    88    */
    89   void Wait (void);
    90 	
    91   /**
    92    * Wait a maximum of ns nanoseconds for the condition to be true.  If the
    93    * wait times out, return true else return false.
    94    */
    95   bool TimedWait (uint64_t ns);
    96 	
    97 
    98 private:
    99   SystemConditionPrivate * m_priv;    
   100 };
   101 
   102 } //namespace ns3
   103 
   104 #endif /* SYSTEM_CONDITION_H */
   105 
   106