00001 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 00002 /* 00003 * Copyright (c) 2008 INRIA 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 * Author: Mathieu Lacage <mathieu.lacage.inria.fr> 00019 */ 00020 00021 #ifndef SYSTEM_MUTEX_H 00022 #define SYSTEM_MUTEX_H 00023 00024 #include "ptr.h" 00025 00026 namespace ns3 { 00027 00028 class SystemMutexPrivate; 00029 00030 /** 00031 * @brief A class which provides a relatively platform-independent Mutual 00032 * Exclusion thread synchronization primitive. 00033 * 00034 * When more than one thread needs to access a shared resource (data structure 00035 * or device), the system needs to provide a way to serialize access to the 00036 * resource. An operating system will typically provide a Mutual Exclusion 00037 * primitive to provide that capability. We provide plattorm-independent 00038 * access to the OS-dependent capability with the SystemMutex class. 00039 * 00040 * There are two operations: Lock and Unlock. Lock allows an executing 00041 * SystemThread to attempt to acquire ownership of the Mutual Exclusion 00042 * object. If the SystemMutex object is not owned by another thread, then 00043 * ownership is granted to the calling SystemThread and Lock returns 00044 * immediately, However, if the SystemMutex is already owned by another 00045 * SystemThread, the calling SystemThread is blocked until the current owner 00046 * releases the SystemMutex by calling Unlock. 00047 * 00048 * @see CriticalSection 00049 */ 00050 class SystemMutex 00051 { 00052 public: 00053 SystemMutex (); 00054 ~SystemMutex (); 00055 00056 /** 00057 * Acquire ownership of the Mutual Exclusion object. 00058 */ 00059 void Lock (); 00060 00061 /** 00062 * Release ownership of the Mutual Exclusion object. 00063 */ 00064 void Unlock (); 00065 00066 private: 00067 SystemMutexPrivate * m_priv; 00068 }; 00069 00070 /** 00071 * @brief A class which provides a simple way to implement a Critical Section. 00072 * 00073 * When more than one SystemThread needs to access a shared resource, we 00074 * conrol access by acquiring a SystemMutex. The CriticalSection class uses 00075 * the C++ scoping rules to automatically perform the required Lock and Unlock 00076 * operations to implement a Critical Section. 00077 * 00078 * If one wants to treat an entire method call as a critical section, one would 00079 * do something like, 00080 * 00081 * Class::Method () 00082 * { 00083 * CriticalSection cs (mutex); 00084 * ... 00085 * } 00086 * 00087 * In this case, the critical section is entered when the CriticalSection 00088 * object is created, and the critical section is exited when the 00089 * CriticalSection object goes out of scope at the end of the method. 00090 * 00091 * Finer granularity is achieved by using local scope blocks. 00092 * 00093 * Class::Method () 00094 * { 00095 * ... 00096 * { 00097 * CriticalSection cs (mutex); 00098 * } 00099 * ... 00100 * } 00101 * 00102 * Here, the critical section is entered partway through the method when the 00103 * CriticalSection object is created in the local scope block (the braces). 00104 * The critical section is exited when the CriticalSection object goes out of 00105 * scope at the end of block. 00106 * 00107 * @see SystemMutex 00108 */ 00109 class CriticalSection 00110 { 00111 public: 00112 CriticalSection (SystemMutex &mutex); 00113 ~CriticalSection (); 00114 private: 00115 SystemMutex &m_mutex; 00116 }; 00117 00118 } //namespace ns3 00119 00120 #endif /* SYSTEM_MUTEX_H */