oasys::Thread Class Reference

#include <Thread.h>

Inheritance diagram for oasys::Thread:

dtn::APIClient dtn::BluetoothConvergenceLayer::Connection dtn::BluetoothConvergenceLayer::NeighborDiscovery dtn::BundleDaemon dtn::CLConnection dtn::FileConvergenceLayer::Scanner dtn::UDPConvergenceLayer::Receiver dtntunnel::TCPTunnel::Connection dtntunnel::UDPTunnel::Listener oasys::BluetoothServerThread oasys::SMTPHandlerThread oasys::TCPServerThread oasys::TimerThread List of all members.

Detailed Description

Class to wrap a thread of execution using native system threads (i.e.

pthreads on UNIX or Windows threads). Similar to the Java API.

Definition at line 80 of file Thread.h.

Public Types

enum  thread_flags_t {
  CREATE_JOINABLE = 1 << 0, DELETE_ON_EXIT = 1 << 1, INTERRUPTABLE = 1 << 2, STARTED = 1 << 3,
  SHOULD_STOP = 1 << 4, STOPPED = 1 << 5
}
 Bit values for thread flags. More...
enum  thread_signal_t { INTERRUPT_SIG = SIGURG }
 Enum to define signals used internally in the thread system (currently just the interrupt signal). More...

Public Member Functions

 Thread (const char *name, int flags=0)
 Constructor.
virtual ~Thread ()
 Destructor.
void start ()
 Starts a new thread and calls the virtual run() method with the new thread.
void join ()
 Join with this thread, blocking the caller until we quit.
void kill (int sig)
 Send a signal to the thread.
void interrupt ()
 Send an interrupt signal to the thread to unblock it if it's stuck in a system call.
void set_interruptable (bool interruptable)
 Set the interruptable state of the thread (default off).
void set_should_stop ()
 Set a bit to stop the thread.
bool should_stop ()
 Return whether or not the thread should stop.
bool is_stopped ()
 Return true if the thread has stopped.
bool started ()
 Return true if the thread has been started.
void set_flag (thread_flags_t flag)
 Set the given thread flag.
void clear_flag (thread_flags_t flag)
 Clear the given thread flag.
ThreadId_t thread_id ()
 Return a pointer to the Thread object's id.

Static Public Member Functions

static void activate_start_barrier ()
 Activate the thread creation barrier.
static void release_start_barrier ()
 Release the thread creation barrier and actually start up any pending threads.
static bool start_barrier_enabled ()
 
Returns:
Status of start barrier

static void yield ()
 Yield the current process.
static void spin_yield ()
 Potentially yield the current thread to implement a busy waiting function.
static ThreadId_t current ()
 Return a pointer to the currently running thread.
static bool id_equal (ThreadId_t a, ThreadId_t b)
 
Returns:
True if ThreadId_t's are equal


Static Public Attributes

static const int max_live_threads_ = 256
 Maximum number of live threads.
static Threadall_threads_ [Thread::max_live_threads_]
 Array of all live threads.
static SpinLockall_threads_lock_
 Spin lock to protect the all threads array on thread startup / shutdown.

Protected Member Functions

void thread_run (const char *thread_name, ThreadId_t thread_id)
 Wrapper function to handle initialization and cleanup of the thread.
virtual void run ()=0
 Derived classes should implement this function which will get called in the new Thread context.

Static Protected Member Functions

static void * pre_thread_run (void *t)
 Static function which is given to the native threading library.
static void interrupt_signal (int sig)
 Noop thread signal handler.

Protected Attributes

ThreadId_t thread_id_
int flags_
char name_ [64]

Static Protected Attributes

static bool signals_inited_
static sigset_t interrupt_sigset_
static bool start_barrier_enabled_
static std::vector< Thread * > threads_in_barrier_


Member Enumeration Documentation

enum oasys::Thread::thread_flags_t

Bit values for thread flags.

Enumerator:
CREATE_JOINABLE  inverse of PTHREAD_CREATE_DETACHED.

Implies not DELETE_ON_EXIT.

DELETE_ON_EXIT  delete thread when run() completes.
INTERRUPTABLE  thread can be interrupted
STARTED  thread has been started
SHOULD_STOP  bit to signal the thread to stop
STOPPED  bit indicating the thread has stopped

Definition at line 85 of file Thread.h.

enum oasys::Thread::thread_signal_t

Enum to define signals used internally in the thread system (currently just the interrupt signal).

Enumerator:
INTERRUPT_SIG 

Definition at line 106 of file Thread.h.


Constructor & Destructor Documentation

oasys::Thread::Thread ( const char *  name,
int  flags = 0 
)

Constructor.

Definition at line 110 of file Thread.cc.

References ASSERT, CREATE_JOINABLE, oasys::cstring_copy(), DELETE_ON_EXIT, FALSE, name_, thread_id_, and TRUE.

oasys::Thread::~Thread (  )  [virtual]

Destructor.

Definition at line 130 of file Thread.cc.


Member Function Documentation

void oasys::Thread::activate_start_barrier (  )  [static]

Activate the thread creation barrier.

No new threads will be created until release_start_barrier() is called.

Note this should only be called in a single-threaded context, i.e. during initialization.

Definition at line 72 of file Thread.cc.

References log_debug, and start_barrier_enabled_.

Referenced by dtn::DTND::main().

void oasys::Thread::release_start_barrier (  )  [static]

Release the thread creation barrier and actually start up any pending threads.

Definition at line 80 of file Thread.cc.

References log_debug, start_barrier_enabled_, and threads_in_barrier_.

Referenced by dtn::DTND::main().

static bool oasys::Thread::start_barrier_enabled (  )  [inline, static]

Returns:
Status of start barrier

Definition at line 146 of file Thread.h.

References start_barrier_enabled_.

Referenced by dtn::DTNServer::init(), and dtn::BundleDaemon::post_and_wait().

void oasys::Thread::yield (  )  [inline, static]

Yield the current process.

Needed for capriccio to yield the processor during long portions of code with no I/O. (Probably used for testing only).

Definition at line 326 of file Thread.h.

Referenced by dtn::ConnectionConvergenceLayer::close_contact(), dtn::BluetoothConvergenceLayer::close_contact(), dtn::BluetoothConvergenceLayer::Connection::connect(), dtn::UDPConvergenceLayer::interface_down(), dtn::TCPConvergenceLayer::interface_down(), dtn::BluetoothConvergenceLayer::interface_down(), and spin_yield().

void oasys::Thread::spin_yield (  )  [inline, static]

Potentially yield the current thread to implement a busy waiting function.

The implementation is dependant on the configuration. On an SMP, don't do anything. Otherwise, with capriccio threads, this should never happen, so issue an assertion. Under pthreads, however, actually call thread_yield() to give up the processor.

Definition at line 341 of file Thread.h.

References yield().

Referenced by oasys::SXLock::exclusive_lock(), oasys::SpinLock::lock(), oasys::SXLock::shared_lock(), and oasys::SpinLock::unlock().

ThreadId_t oasys::Thread::current (  )  [inline, static]

Return a pointer to the currently running thread.

XXX/demmer this could keep a map to return a Thread* if it's actually useful

Definition at line 315 of file Thread.h.

Referenced by oasys::FatalSignals::handler(), oasys::Lock::is_locked_by_me(), oasys::SpinLock::lock(), oasys::Mutex::lock(), pre_thread_run(), set_interruptable(), oasys::SpinLock::try_lock(), and oasys::Mutex::try_lock().

bool oasys::Thread::id_equal ( ThreadId_t  a,
ThreadId_t  b 
) [static]

Returns:
True if ThreadId_t's are equal

Definition at line 99 of file Thread.cc.

void oasys::Thread::start (  ) 

Starts a new thread and calls the virtual run() method with the new thread.

Definition at line 141 of file Thread.cc.

References ASSERT, CREATE_JOINABLE, errno, flags_, INTERRUPT_SIG, interrupt_signal(), interrupt_sigset_, log_debug, log_err, pre_thread_run(), signals_inited_, start_barrier_enabled_, thread_id_, and threads_in_barrier_.

Referenced by dtntunnel::TCPTunnel::Listener::accepted(), oasys::SMTPServer::accepted(), dtn::BluetoothConvergenceLayer::Listener::accepted(), dtn::APIServer::accepted(), oasys::TCPServerThread::bind_listen_start(), oasys::BluetoothServerThread::bind_listen_start(), dtn::BluetoothConvergenceLayer::Connection::connect(), dtntunnel::TCPTunnel::handle_bundle(), oasys::TimerThread::init(), dtn::UDPConvergenceLayer::interface_up(), dtn::TCPConvergenceLayer::interface_up(), dtn::BluetoothConvergenceLayer::interface_up(), dtntunnel::UDPTunnel::Listener::Listener(), dtn::ConnectionConvergenceLayer::open_contact(), dtn::BluetoothConvergenceLayer::open_contact(), and dtn::StreamConvergenceLayer::Connection::send_pending_acks().

void oasys::Thread::join (  ) 

Join with this thread, blocking the caller until we quit.

Definition at line 215 of file Thread.cc.

References ASSERT, CREATE_JOINABLE, flags_, and thread_id_.

void oasys::Thread::kill ( int  sig  ) 

Send a signal to the thread.

Definition at line 240 of file Thread.cc.

References errno, NOTIMPLEMENTED, and thread_id_.

Referenced by interrupt().

void oasys::Thread::interrupt (  ) 

Send an interrupt signal to the thread to unblock it if it's stuck in a system call.

Implemented with SIGUSR1.

XXX/bowei - There's no good way to implement this on many platforms. We should get rid of this.

Definition at line 254 of file Thread.cc.

References INTERRUPT_SIG, kill(), log_debug, and NOTIMPLEMENTED.

Referenced by dtn::BluetoothConvergenceLayer::interface_down().

void oasys::Thread::set_interruptable ( bool  interruptable  ) 

Set the interruptable state of the thread (default off).

If interruptable, a thread can receive SIGUSR1 signals to interrupt any system calls.

Note: This must be called by the thread itself. To set the interruptable state before a thread is created, use the INTERRUPTABLE flag.

Definition at line 266 of file Thread.cc.

References ASSERT, current(), interrupt_sigset_, NOTIMPLEMENTED, and thread_id_.

Referenced by thread_run().

void oasys::Thread::set_should_stop (  )  [inline]

Set a bit to stop the thread.

This simply sets a bit in the thread's flags that can be examined by the run method to indicate that the thread should be stopped.

Definition at line 234 of file Thread.h.

References flags_, and SHOULD_STOP.

Referenced by dtn::BluetoothConvergenceLayer::Connection::break_contact(), dtn::BluetoothConvergenceLayer::close_contact(), dtn::BluetoothConvergenceLayer::Connection::connect(), dtn::BundleDaemon::handle_shutdown_request(), dtn::UDPConvergenceLayer::interface_down(), dtn::TCPConvergenceLayer::interface_down(), dtn::BluetoothConvergenceLayer::interface_down(), dtn::BluetoothConvergenceLayer::Connection::recv_bundle(), and dtn::BluetoothConvergenceLayer::Connection::send_loop().

bool oasys::Thread::should_stop (  )  [inline]

Return whether or not the thread should stop.

Definition at line 239 of file Thread.h.

References flags_, and SHOULD_STOP.

Referenced by dtn::BluetoothConvergenceLayer::Connection::break_contact(), dtn::BluetoothConvergenceLayer::close_contact(), dtn::UDPConvergenceLayer::Receiver::run(), oasys::TCPServerThread::run(), dtn::BundleDaemon::run(), oasys::BluetoothServerThread::run(), dtn::BluetoothConvergenceLayer::NeighborDiscovery::run(), dtn::BluetoothConvergenceLayer::Connection::run(), and dtn::BluetoothConvergenceLayer::Connection::send_loop().

bool oasys::Thread::is_stopped (  )  [inline]

Return true if the thread has stopped.

Definition at line 244 of file Thread.h.

References flags_, and STOPPED.

Referenced by dtn::BluetoothConvergenceLayer::close_contact(), dtn::BluetoothConvergenceLayer::Connection::connect(), dtn::UDPConvergenceLayer::interface_down(), dtn::TCPConvergenceLayer::interface_down(), and dtn::BluetoothConvergenceLayer::interface_down().

bool oasys::Thread::started (  )  [inline]

Return true if the thread has been started.

Definition at line 249 of file Thread.h.

References flags_, and STARTED.

void oasys::Thread::set_flag ( thread_flags_t  flag  )  [inline]

Set the given thread flag.

Definition at line 254 of file Thread.h.

References flags_.

Referenced by dtn::FileConvergenceLayer::Scanner::Scanner().

void oasys::Thread::clear_flag ( thread_flags_t  flag  )  [inline]

Clear the given thread flag.

Definition at line 259 of file Thread.h.

References flags_.

ThreadId_t oasys::Thread::thread_id (  )  [inline]

Return a pointer to the Thread object's id.

The static function current() is the currently executing thread id.

Definition at line 265 of file Thread.h.

References thread_id_.

Referenced by pre_thread_run().

void * oasys::Thread::pre_thread_run ( void *  t  )  [static, protected]

Static function which is given to the native threading library.

Definition at line 288 of file Thread.cc.

References current(), name_, thread_id(), and thread_run().

Referenced by start().

void oasys::Thread::interrupt_signal ( int  sig  )  [static, protected]

Noop thread signal handler.

Definition at line 304 of file Thread.cc.

Referenced by start().

void oasys::Thread::thread_run ( const char *  thread_name,
ThreadId_t  thread_id 
) [protected]

Wrapper function to handle initialization and cleanup of the thread.

Runs in the context of the newly created thread.

Definition at line 311 of file Thread.cc.

References all_threads_, all_threads_lock_, DELETE_ON_EXIT, flags_, INTERRUPTABLE, oasys::SpinLock::lock(), max_live_threads_, NOTREACHED, run(), set_interruptable(), SHOULD_STOP, STARTED, STOPPED, thread_id_, and oasys::SpinLock::unlock().

Referenced by pre_thread_run().

virtual void oasys::Thread::run (  )  [protected, pure virtual]

Derived classes should implement this function which will get called in the new Thread context.

Implemented in dtn::APIClient, dtntunnel::TCPTunnel::Connection, dtntunnel::UDPTunnel::Listener, oasys::BluetoothServerThread, oasys::TCPServerThread, oasys::SMTPHandlerThread, oasys::TimerThread, dtn::BundleDaemon, dtn::BluetoothConvergenceLayer::Connection, dtn::BluetoothConvergenceLayer::NeighborDiscovery, dtn::CLConnection, dtn::FileConvergenceLayer::Scanner, and dtn::UDPConvergenceLayer::Receiver.

Referenced by thread_run().


Member Data Documentation

const int oasys::Thread::max_live_threads_ = 256 [static]

Maximum number of live threads.

Definition at line 114 of file Thread.h.

Referenced by oasys::FatalSignals::handler(), and thread_run().

Thread * oasys::Thread::all_threads_ [static]

Array of all live threads.

Used for debugging, see FatalSignals.cc.

Definition at line 120 of file Thread.h.

Referenced by oasys::FatalSignals::handler(), and thread_run().

SpinLock * oasys::Thread::all_threads_lock_ [static]

Spin lock to protect the all threads array on thread startup / shutdown.

Definition at line 126 of file Thread.h.

Referenced by thread_run().

bool oasys::Thread::signals_inited_ [static, protected]

Definition at line 275 of file Thread.h.

Referenced by start().

sigset_t oasys::Thread::interrupt_sigset_ [static, protected]

Definition at line 276 of file Thread.h.

Referenced by set_interruptable(), and start().

bool oasys::Thread::start_barrier_enabled_ [static, protected]

Definition at line 279 of file Thread.h.

Referenced by activate_start_barrier(), release_start_barrier(), start(), and start_barrier_enabled().

std::vector< Thread * > oasys::Thread::threads_in_barrier_ [static, protected]

Definition at line 280 of file Thread.h.

Referenced by release_start_barrier(), and start().

ThreadId_t oasys::Thread::thread_id_ [protected]

Definition at line 282 of file Thread.h.

Referenced by join(), kill(), set_interruptable(), start(), Thread(), thread_id(), and thread_run().

int oasys::Thread::flags_ [protected]

Definition at line 283 of file Thread.h.

Referenced by clear_flag(), is_stopped(), join(), set_flag(), set_should_stop(), should_stop(), start(), started(), and thread_run().

char oasys::Thread::name_[64] [protected]

Reimplemented in dtnsim::Node.

Definition at line 284 of file Thread.h.

Referenced by pre_thread_run(), and Thread().


The documentation for this class was generated from the following files:
Generated on Fri Dec 22 14:48:07 2006 for DTN Reference Implementation by  doxygen 1.5.1