src/core/system-mutex.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 INRIA
     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  * Author: Mathieu Lacage <mathieu.lacage.inria.fr>
    19  */
    20 
    21 #ifndef SYSTEM_MUTEX_H
    22 #define SYSTEM_MUTEX_H
    23 
    24 #include "ptr.h"
    25 
    26 namespace ns3 { 
    27 	
    28 class SystemMutexPrivate;
    29 
    30 /**
    31  * @brief A class which provides a relatively platform-independent Mutual
    32  * Exclusion thread synchronization primitive.
    33  *
    34  * When more than one thread needs to access a shared resource (data structure
    35  * or device), the system needs to provide a way to serialize access to the
    36  * resource.  An operating system will typically provide a Mutual Exclusion
    37  * primitive to provide that capability.  We provide plattorm-independent
    38  * access to the OS-dependent capability with the SystemMutex class.
    39  *
    40  * There are two operations:  Lock and Unlock.  Lock allows an executing 
    41  * SystemThread to attempt to acquire ownership of the Mutual Exclusion 
    42  * object.  If the SystemMutex object is not owned by another thread, then
    43  * ownership is granted to the calling SystemThread and Lock returns 
    44  * immediately,  However, if the SystemMutex is already owned by another
    45  * SystemThread, the calling SystemThread is blocked until the current owner
    46  * releases the SystemMutex by calling Unlock.
    47  *
    48  * @see CriticalSection
    49  */
    50 class SystemMutex 
    51 {
    52 public:
    53   SystemMutex ();
    54   ~SystemMutex ();
    55 
    56   /**
    57    * Acquire ownership of the Mutual Exclusion object.
    58    */
    59   void Lock ();
    60 
    61   /**
    62    * Release ownership of the Mutual Exclusion object.
    63    */
    64   void Unlock ();
    65 	
    66 private:
    67   SystemMutexPrivate * m_priv;    
    68 };
    69 
    70 /**
    71  * @brief A class which provides a simple way to implement a Critical Section.
    72  *
    73  * When more than one SystemThread needs to access a shared resource, we
    74  * conrol access by acquiring a SystemMutex.  The CriticalSection class uses
    75  * the C++ scoping rules to automatically perform the required Lock and Unlock
    76  * operations to implement a Critical Section.
    77  *
    78  * If one wants to treat an entire method call as a critical section, one would
    79  * do something like,
    80  *
    81  * Class::Method ()
    82  * {
    83  *   CriticalSection cs (mutex);
    84  *   ...
    85  * }
    86  *
    87  * In this case, the critical section is entered when the CriticalSection 
    88  * object is created, and the critical section is exited when the 
    89  * CriticalSection object goes out of scope at the end of the method.
    90  *
    91  * Finer granularity is achieved by using local scope blocks.
    92  *
    93  * Class::Method ()
    94  * {
    95  *   ...
    96  *   {
    97  *     CriticalSection cs (mutex);
    98  *   }
    99  *   ...
   100  * }
   101  *
   102  * Here, the critical section is entered partway through the method when the
   103  * CriticalSection object is created in the local scope block (the braces).
   104  * The critical section is exited when the CriticalSection object goes out of
   105  * scope at the end of block.
   106  *
   107  * @see SystemMutex
   108  */
   109 class CriticalSection
   110 {
   111 public:
   112   CriticalSection (SystemMutex &mutex);
   113   ~CriticalSection ();
   114 private:
   115   SystemMutex &m_mutex;
   116 };
   117 
   118 } //namespace ns3
   119 
   120 #endif /* SYSTEM_MUTEX_H */