ns3::SystemThread Class Reference

A class which provides a relatively platform-independent thread primitive. More...

#include "system-thread.h"

Inheritance diagram for ns3::SystemThread:

Public Types
typedef pthread_t	ThreadId
	Type alias for the system-dependent thread object. More...

Public Member Functions
	SystemThread (Callback< void > callback)
	Create a SystemThread object. More...
	~SystemThread ()
	Destroy a SystemThread object. More...
void	Join (void)
	Suspend the caller until the thread of execution, running the provided callback, finishes. More...
void	Start (void)
	Start a thread of execution, running the provided callback. More...
Public Member Functions inherited from ns3::SimpleRefCount< SystemThread >
	SimpleRefCount ()
	Default constructor. More...
	SimpleRefCount (const SimpleRefCount &o)
	Copy constructor. More...
uint32_t	GetReferenceCount (void) const
	Get the reference count of the object. More...
SimpleRefCount &	operator= (const SimpleRefCount &o)
	Assignment operator. More...
void	Ref (void) const
	Increment the reference count. More...
void	Unref (void) const
	Decrement the reference count. More...

Static Public Member Functions
static bool	Equals (ThreadId id)
	Compares an ThreadId with the current ThreadId . More...
static ThreadId	Self (void)
	Returns the current thread Id. More...

Static Private Member Functions
static void *	DoRun (void *arg)
	Invoke the callback in the new thread. More...

Private Attributes
Callback< void >	m_callback
	The main function for this thread when launched. More...
pthread_t	m_thread
	The thread id of the child thread. More...

Detailed Description

A class which provides a relatively platform-independent thread primitive.

This class allows for creation of multiple threads of execution in a process. The exact implementation of the thread functionality is operating system dependent, but typically in ns-3 one is using an environment in which Posix Threads are supported (either natively or in the case of Windows via Cygwin's implementation of pthreads on the Win32 API. In either case we expect that these will be kernel-level threads and therefore a system with multiple CPUs will see truly concurrent execution.

Synchronization between threads is provided via the SystemMutex class.

See main-test-sync.cc for example usage.

Definition at line 56 of file system-thread.h.

Member Typedef Documentation

ThreadId

typedef pthread_t ns3::SystemThread::ThreadId

Type alias for the system-dependent thread object.

Definition at line 62 of file system-thread.h.

Constructor & Destructor Documentation

SystemThread()

ns3::SystemThread::SystemThread

(

Callback< void >

callback

)

Create a SystemThread object.

A system thread object is not created running. A thread of execution must be explicitly started by calling the Start method. When the Start method is called, it will spawn a thread of execution and cause that thread to call out into the callback function provided here as a parameter.

Like all ns-3 callbacks, the provided callback may refer to a function or a method of an object depending on how the MakeCallback function is used.

The most common use is expected to be creating a thread of execution in a method. In this case you would use code similar to,

MyClass myObject;
Ptr<SystemThread> st = Create<SystemThread> (
  MakeCallback (&MyClass::MyMethod, &myObject));
st->Start ();

The SystemThread is passed a callback that calls out to the function MyClass::MyMethod. When this function is called, it is called as an object method on the myObject object. Essentially what you are doing is asking the SystemThread to call object->MyMethod() in a new thread of execution.

If starting a thread in your currently executing object, you can use the "this" pointer:

Ptr<SystemThread> st = Create<SystemThread> (
  MakeCallback (&MyClass::MyMethod, this));
st->Start ();

Object lifetime is always an issue with threads, so it is common to use smart pointers. If you are spinning up a thread in an object that is managed by a smart pointer, you can use that pointer directly:

Ptr<MyClass> myPtr = Create<MyClass> ();
Ptr<SystemThread> st = Create<SystemThread> (
  MakeCallback (&MyClass::MyMethod, myPtr));
st->Start ();

Just like any thread, you can synchronize with its termination. The method provided to do this is Join(). If you call Join() you will block until the SystemThread run method returns.

Parameters

[in]

callback

entry point of the thread

Warning

I've made the system thread class look like a normal ns3 object with smart pointers, and living in the heap. This makes it very easy to manage threads from a single master thread context. You should be very aware though that I have not made Ptr multithread safe! This means that if you pass Ptr<SystemThread> around in a multithreaded environment, it is possible that the reference count will get messed up since it is not an atomic operation. CREATE AND MANAGE YOUR THREADS IN ONE PLACE – LEAVE THE PTR THERE.

Definition at line 38 of file system-thread.cc.

References NS_LOG_FUNCTION.

~SystemThread()

ns3::SystemThread::~SystemThread

(

)

Destroy a SystemThread object.

Definition at line 44 of file system-thread.cc.

References NS_LOG_FUNCTION.

Member Function Documentation

DoRun()

void * ns3::SystemThread::DoRun ( void *  arg )

staticprivate

Invoke the callback in the new thread.

Parameters

[in]

arg

This SystemThread instance to communicate to the newly launched thread.

Definition at line 79 of file system-thread.cc.

References m_callback, and NS_LOG_FUNCTION.

Referenced by Start().

Equals()

bool ns3::SystemThread::Equals ( SystemThread::ThreadId  id )

static

Compares an ThreadId with the current ThreadId .

Parameters

[in]

id

The ThreadId to compare to.

Returns

true if id matches the current ThreadId.

Definition at line 96 of file system-thread.cc.

References NS_LOG_FUNCTION.

Referenced by ns3::DefaultSimulatorImpl::Schedule(), ns3::DefaultSimulatorImpl::ScheduleDestroy(), ns3::DefaultSimulatorImpl::ScheduleNow(), ns3::DefaultSimulatorImpl::ScheduleWithContext(), and ns3::RealtimeSimulatorImpl::ScheduleWithContext().

Join()

void ns3::SystemThread::Join

(

void

)

Suspend the caller until the thread of execution, running the provided callback, finishes.

Definition at line 65 of file system-thread.cc.

References m_thread, NS_FATAL_ERROR, and NS_LOG_FUNCTION.

Self()

SystemThread::ThreadId ns3::SystemThread::Self ( void  )

static

Returns the current thread Id.

Returns

Current thread Id.

Definition at line 89 of file system-thread.cc.

References NS_LOG_FUNCTION_NOARGS.

Referenced by ns3::DefaultSimulatorImpl::DefaultSimulatorImpl(), ns3::RealtimeSimulatorImpl::RealtimeSimulatorImpl(), ns3::DefaultSimulatorImpl::Run(), and ns3::RealtimeSimulatorImpl::Run().

Start()

void ns3::SystemThread::Start

(

void

)

Start a thread of execution, running the provided callback.

Definition at line 50 of file system-thread.cc.

References DoRun(), m_thread, NS_FATAL_ERROR, and NS_LOG_FUNCTION.

Member Data Documentation

m_callback

Callback<void> ns3::SystemThread::m_callback

private

The main function for this thread when launched.

Definition at line 169 of file system-thread.h.

Referenced by DoRun().

m_thread

pthread_t ns3::SystemThread::m_thread

private

The thread id of the child thread.

Definition at line 170 of file system-thread.h.

Referenced by Join(), and Start().

---

The documentation for this class was generated from the following files:

• src/core/model/system-thread.h
• src/core/model/system-thread.cc