ns3::SystemThread Class Reference

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

#include <system-thread.h>

List of all members.

Public Member Functions
	SystemThread (Callback< void > callback)
	Create a SystemThread object.
	~SystemThread ()
	Destroy a SystemThread object.
void	Ref (void) const
void	Unref (void) const
void	Start (void)
	Start a thread of execution, running the provided callback.
void	Join (void)
	Suspend the caller until the thread of execution, running the provided callback, finishes.
void	Shutdown (void)
	Indicates to a managed thread doing cooperative multithreading that its managing thread wants it to exit.
bool	Break (void)
	Indicates to a thread doing cooperative multithreading that its managing thread wants it to exit.

---

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 navively 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.

---

Constructor & Destructor Documentation

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.

Remember that if you are invoking a callback on an object that is managed by a smart pointer, you need to call PeekPointer.

Ptr<MyClass> myPtr = Create<MyClass> (); Ptr<SystemThread> st = Create<SystemThread> ( MakeCallback (&MyClass::MyMethod, PeekPointer (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.

Warning:

The SystemThread uses SIGALRM to wake threads that are possibly blocked on IO.

See also:

Shutdown

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.

---

Member Function Documentation

bool ns3::SystemThread::Break

(

void

)

Indicates to a thread doing cooperative multithreading that its managing thread wants it to exit.

It is often the case that we want a thread to be off doing work until such time as its job is done. We then want the thread to exit itself. This method allows a thread to query whether or not it should be running. Typically, the worker thread is running in a forever-loop, and will need to "break" out of that loop to exit -- thus the name.

See also:

Shutdown

Returns:

true if thread is expected to exit (break out of the forever-loop)

void ns3::SystemThread::Ref

(

void

)

const [inline]

Increment the reference count. This method should not be called by user code. Object instances are expected to be used in conjunction of the Ptr template which would make calling Ref unecessary and dangerous.

void ns3::SystemThread::Shutdown

(

void

)

Indicates to a managed thread doing cooperative multithreading that its managing thread wants it to exit.

It is often the case that we want a thread to be off doing work until such time as its job is done (typically when the simulation is done). We then want the thread to exit itself. This method provides a consistent way for the managing thread to communicate with the managed thread. After the manager thread calls this method, the Break() method will begin returning true, telling the managed thread to exit.

This alone isn't really enough to merit these events, but in Unix, if a worker thread is doing blocking IO, it will need to be woken up from that read somehow. This method also provides that functionality, by sending a SIGALRM signal to the possibly blocked thread.

Warning:

Uses SIGALRM to notifiy threads possibly blocked on IO. Beware if you are using signals.

See also:

Break

void ns3::SystemThread::Unref

(

void

)

const [inline]

Decrement the reference count. This method should not be called by user code. Object instances are expected to be used in conjunction of the Ptr template which would make calling Ref unecessary and dangerous.

---

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

• src/core/system-thread.h