oasys::Thread Class Reference

#include <Thread.h>

Inheritance diagram for oasys::Thread:

dtn::APIClient dtn::BluetoothDiscovery dtn::BundleDaemon dtn::CLConnection dtn::FileConvergenceLayer::Scanner dtn::IPDiscovery dtn::ProphetEncounter 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 59 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 64 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 85 of file Thread.h.


Constructor & Destructor Documentation

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

Constructor.

Definition at line 89 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 109 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 51 of file Thread.cc.

References log_debug_p, 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 59 of file Thread.cc.

References log_debug_p, 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 125 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 305 of file Thread.h.

Referenced by dtn::ConnectionConvergenceLayer::close_contact(), dtn::UDPConvergenceLayer::interface_down(), dtn::TCPConvergenceLayer::interface_down(), dtn::BluetoothConvergenceLayer::interface_down(), dtn::DTND::main(), 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 320 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 294 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 78 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 120 of file Thread.cc.

References ASSERT, CREATE_JOINABLE, errno, flags_, INTERRUPT_SIG, interrupt_signal(), interrupt_sigset_, log_debug_p, oasys::LOG_ERR, oasys::logf(), pre_thread_run(), signals_inited_, start_barrier_enabled_, thread_id_, and threads_in_barrier_.

Referenced by dtntunnel::TCPTunnel::Listener::accepted(), oasys::SMTPServer::accepted(), dtn::APIServer::accepted(), oasys::TCPServerThread::bind_listen_start(), oasys::BluetoothServerThread::bind_listen_start(), dtn::IPDiscovery::configure(), dtn::BluetoothDiscovery::configure(), dtntunnel::TCPTunnel::handle_bundle(), dtn::IPAnnounce::handle_neighbor_discovered(), dtn::BluetoothAnnounce::handle_neighbor_discovered(), oasys::TimerThread::init(), dtn::UDPConvergenceLayer::interface_up(), dtn::TCPConvergenceLayer::interface_up(), dtn::BluetoothConvergenceLayer::interface_up(), dtntunnel::UDPTunnel::Listener::Listener(), dtn::ProphetController::new_neighbor(), and dtn::ConnectionConvergenceLayer::open_contact().

void oasys::Thread::join (  ) 

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

Definition at line 197 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 222 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 236 of file Thread.cc.

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

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 248 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 213 of file Thread.h.

References flags_, and SHOULD_STOP.

Referenced by dtn::BundleDaemon::handle_shutdown_request(), dtn::UDPConvergenceLayer::interface_down(), dtn::TCPConvergenceLayer::interface_down(), and dtn::BluetoothConvergenceLayer::interface_down().

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

Return whether or not the thread should stop.

Definition at line 218 of file Thread.h.

References flags_, and SHOULD_STOP.

Referenced by dtn::UDPConvergenceLayer::Receiver::run(), oasys::TCPServerThread::run(), dtn::BundleDaemon::run(), and oasys::BluetoothServerThread::run().

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

Return true if the thread has stopped.

Definition at line 223 of file Thread.h.

References flags_, and STOPPED.

Referenced by 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 228 of file Thread.h.

References flags_, and STARTED.

Referenced by dtn::IPDiscovery::configure(), and dtn::BluetoothDiscovery::configure().

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

Set the given thread flag.

Definition at line 233 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 238 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 244 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 270 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 286 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 293 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::CLConnection, dtn::FileConvergenceLayer::Scanner, dtn::UDPConvergenceLayer::Receiver, dtn::BluetoothDiscovery, dtn::IPDiscovery, and dtn::ProphetEncounter.

Referenced by thread_run().


Member Data Documentation

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

Maximum number of live threads.

Definition at line 93 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 99 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 105 of file Thread.h.

Referenced by thread_run().

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

Definition at line 254 of file Thread.h.

Referenced by start().

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

Definition at line 255 of file Thread.h.

Referenced by set_interruptable(), and start().

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

Definition at line 258 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 259 of file Thread.h.

Referenced by release_start_barrier(), and start().

ThreadId_t oasys::Thread::thread_id_ [protected]

Definition at line 261 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 262 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 263 of file Thread.h.

Referenced by pre_thread_run(), and Thread().


The documentation for this class was generated from the following files:
Generated on Thu Jun 7 12:54:36 2007 for DTN Reference Implementation by  doxygen 1.5.1