/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * Copyright (c) 2008 INRIA

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation;

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 *

 * Author: Mathieu Lacage <mathieu.lacage.inria.fr>

 */

#ifndef SYSTEM_MUTEX_H

#define SYSTEM_MUTEX_H

#include "ptr.h"

namespace ns3 { 

class SystemMutexPrivate;

/**

 * @brief A class which provides a relatively platform-independent Mutual

 * Exclusion thread synchronization primitive.

 *

 * When more than one thread needs to access a shared resource (data structure

 * or device), the system needs to provide a way to serialize access to the

 * resource.  An operating system will typically provide a Mutual Exclusion

 * primitive to provide that capability.  We provide plattorm-independent

 * access to the OS-dependent capability with the SystemMutex class.

 *

 * There are two operations:  Lock and Unlock.  Lock allows an executing 

 * SystemThread to attempt to acquire ownership of the Mutual Exclusion 

 * object.  If the SystemMutex object is not owned by another thread, then

 * ownership is granted to the calling SystemThread and Lock returns 

 * immediately,  However, if the SystemMutex is already owned by another

 * SystemThread, the calling SystemThread is blocked until the current owner

 * releases the SystemMutex by calling Unlock.

 *

 * @see CriticalSection

 */

class SystemMutex 

{

public:

  SystemMutex ();

  ~SystemMutex ();

  /**

   * Acquire ownership of the Mutual Exclusion object.

   */

  void Lock ();

  /**

   * Release ownership of the Mutual Exclusion object.

   */

  void Unlock ();

private:

  SystemMutexPrivate * m_priv;    

};

/**

 * @brief A class which provides a simple way to implement a Critical Section.

 *

 * When more than one SystemThread needs to access a shared resource, we

 * conrol access by acquiring a SystemMutex.  The CriticalSection class uses

 * the C++ scoping rules to automatically perform the required Lock and Unlock

 * operations to implement a Critical Section.

 *

 * If one wants to treat an entire method call as a critical section, one would

 * do something like,

 *

 * Class::Method ()

 * {

 *   CriticalSection cs (mutex);

 *   ...

 * }

 *

 * In this case, the critical section is entered when the CriticalSection 

 * object is created, and the critical section is exited when the 

 * CriticalSection object goes out of scope at the end of the method.

 *

 * Finer granularity is achieved by using local scope blocks.

 *

 * Class::Method ()

 * {

 *   ...

 *   {

 *     CriticalSection cs (mutex);

 *   }

 *   ...

 * }

 *

 * Here, the critical section is entered partway through the method when the

 * CriticalSection object is created in the local scope block (the braces).

 * The critical section is exited when the CriticalSection object goes out of

 * scope at the end of block.

 *

 * @see SystemMutex

 */

class CriticalSection

{

public:

  CriticalSection (SystemMutex &mutex);

  ~CriticalSection ();

private:

  SystemMutex &m_mutex;

};

} //namespace ns3

#endif /* SYSTEM_MUTEX_H */