Main Page | Namespace List | Class List | File List | Namespace Members | Class Members | File Members

Dv::Thread::Thread Class Reference

Posix thread class. More...

#include <thread.h>

List of all members.

Public Types

enum  errors { BAD_EXCEPTION = -1, DEFAULT_MAIN = -2 }

Public Member Functions

 Thread (bool delete_after_main=false) throw (std::runtime_error)
 Constructor.
virtual ~Thread ()
 Destructor.
int start () throw (std::runtime_error)
 Start up thread.
virtual int main ()
 Main function of thread.
virtual void killed () throw ()
 This function is called by the thread as a response to a SIGFPE signal being delivered from another thread, using Thread::kill.
int join () const throw ()
 Wait for this thread to finish.
int kill () const throw (std::runtime_error)
 Kill a thread.
int status () const
 Return exit status of this thread.
void set_status (int status)
pthread_t id () const
 Return posix thread id of this thread.
std::string sid () const
 String representation of thread id of this thread.
Threaddetach ()
 Detach this thread.
Threaddelete_after_main (bool yes)
 Delete this thread object after Thread::main() has completed.
bool delete_after_main ()
 Will this thread object be deleted after Thread::main() has completed?
bool is_self () const
 Is this thread the currently running thread?
bool running () const
 Is this thread running?
void set_signal_handler_installed ()
 Set signal_handler_installed.

Static Public Member Functions

static Threadself () throw (std::runtime_error)
 Return pointer to currently running thread.
static pthread_t self_id () throw ()
 Return id (pthread_t) of currently running thread.
static void exit (int status)
 Finish this thread, with status.

Static Public Attributes

static std::ostream * log
 Stream to log info on, if not 0.

Private Member Functions

 Thread (const Thread &)
 Forbid cctor.
Threadoperator= (const Thread &)
 Forbid assignment.

Private Attributes

pthread_t id_
 Posix thread id.
pthread_attr_t attributes_
 Posix thread attributes.
int exit_status_
 Exit status of this thread.
bool delete_after_main_
 Should this object be deleted after Thread::main has completed?
bool signal_handler_installed
 Is a signal handler for SIGFPE installed? This should really be private but it is not since it is set from a C function.


Detailed Description

Posix thread class.

Example Thread class definitions:

See also:
Dv::Thread::Monitor


Member Enumeration Documentation

enum Dv::Thread::Thread::errors
 

Enumerator:
BAD_EXCEPTION 
DEFAULT_MAIN 


Constructor & Destructor Documentation

Dv::Thread::Thread::Thread bool  delete_after_main = false  )  throw (std::runtime_error)
 

Constructor.

Parameters:
delete_after_main if true, delete(t) will be executed after t->main() has completed.
See also:
Dv::Thread::Thread::delete_after_main

virtual Dv::Thread::Thread::~Thread  )  [virtual]
 

Destructor.

Dv::Thread::Thread::Thread const Thread  )  [private]
 

Forbid cctor.


Member Function Documentation

int Dv::Thread::Thread::start  )  throw (std::runtime_error)
 

Start up thread.

This function will execute main().

Returns:
0 iff ok, system errno else.
Exceptions:
runtime_error if thread is already running.

virtual int Dv::Thread::Thread::main  )  [virtual]
 

Main function of thread.

Returns:
the value to keep in set_status Note that this function should not throw any exceptions except integers. The library will catch any exception e that is thrown erroneously, print e.what() on cerr and return an exit status of BAD_EXCEPTION.
See also:
Dv::Thread::Thread::start

Dv::Thread::Thread::BAD_EXCEPTION

Dv::Thread::Thread::exit

Dv::Thread::Thread::set_status

virtual void Dv::Thread::Thread::killed  )  throw () [inline, virtual]
 

This function is called by the thread as a response to a SIGFPE signal being delivered from another thread, using Thread::kill.

This function is then called the internal handler for this signal.

Warning:
This function should not throw any exceptions or chaos will result. Typical usage might be:
 class MyThread {
 public:
  ...
  void main() throw() {
    while (!killed_ && socket_>>line) {
      ...
      }
    }
  void killed() throw () {
    killed_ = true;
    socket_.close();
    }
 }

int Dv::Thread::Thread::join  )  const throw ()
 

Wait for this thread to finish.

Returns:
0 iff ok, see manpage for pthread_self for other possibities.
Warning:
only works for non-detached threads.
See also:
Dv::Thread::Thread::detach
 MyThread t;
 cout << "starting t" << endl;
 t.start();
 cout << "waiting for t to finish" << endl;
 t.join();

int Dv::Thread::Thread::kill  )  const throw (std::runtime_error)
 

Kill a thread.

This function delivers a SIGFPE signal to the thread using pthread_kill(id_,SIGFPE1). The signal is caught and handled internally by calling Dv::Thread::Thread::killed().

Exceptions:
runtime_error for a thread that tries to kill itself.
See also:
Dv::Thread::Thread::killed

int Dv::Thread::Thread::status  )  const [inline]
 

Return exit status of this thread.

Returns:
exit status of thread.

void Dv::Thread::Thread::set_status int  status  )  [inline]
 

pthread_t Dv::Thread::Thread::id  )  const [inline]
 

Return posix thread id of this thread.

Returns:
Posix thread id.

std::string Dv::Thread::Thread::sid  )  const
 

String representation of thread id of this thread.

Returns:
string representation of the id of this thread

Thread& Dv::Thread::Thread::detach  ) 
 

Detach this thread.

Threads are created as ``joinable'', this function makes this impossible. It also ensures that all resources are freed when the thread exits.

Warning:
To avoid a memory leak, a thread must be joined or detached.
Returns:
*this
See also:
Dv::Thread::Thread::join

Thread& Dv::Thread::Thread::delete_after_main bool  yes  )  [inline]
 

Delete this thread object after Thread::main() has completed.

This feature is handy when there are an unknown number of threads that are created using new and the only thing to do after a thread has finished is to delete the Thread object.

The code below shows a typical example.

 class MyThread: public Dv::Thread::Thread {
 public:
   MyThread* make(); // factory method to prohibit non-heap allocation.
   void main();
 private:
   MyThread(...): Dv::Thread::Thread(true), .. { detach(); .. }  
 };

 while (accept) {
   MyThread::make()->start(); // will delete itself automatically
   }
Parameters:
yes if true, the object will be deleted after Thread::main has finished.
Returns:
*this

bool Dv::Thread::Thread::delete_after_main  )  [inline]
 

Will this thread object be deleted after Thread::main() has completed?

Returns:
true iff this object will be deleted after Thread::main() finished.

bool Dv::Thread::Thread::is_self  )  const
 

Is this thread the currently running thread?

Returns:
true iff this thread is the currently running thread

false otherwise

bool Dv::Thread::Thread::running  )  const [inline]
 

Is this thread running?

Returns:
true iff this thread has been created using pthread_create

false otherwise

static Thread* Dv::Thread::Thread::self  )  throw (std::runtime_error) [static]
 

Return pointer to currently running thread.

Returns:
pointer to currently running thread, may be 0 if the thread was not made by this library.

static pthread_t Dv::Thread::Thread::self_id  )  throw () [inline, static]
 

Return id (pthread_t) of currently running thread.

This works for any thread; it is actually just call to pthread_self.

Returns:
id of currently running thread.

static void Dv::Thread::Thread::exit int  status  )  [static]
 

Finish this thread, with status.

Warning:
This is implemented by throwing the status integer as an exception. Hence is your code catches integers, as in
 try {
    exit(3);
 }
 catch (integer e) {
 }
the thread will not exit.
The implementation of this function was changed between versions 0.4 and 0.5 because the previous implementation, which used pthread_exit, gave problems on systems with the nptl thread implementation.
Parameters:
status to return.

Thread& Dv::Thread::Thread::operator= const Thread  )  [private]
 

Forbid assignment.

void Dv::Thread::Thread::set_signal_handler_installed  ) 
 

Set signal_handler_installed.

This function does nothing if not called by the thread itself.

See also:
Dv::Thread::Thread::is_self


Member Data Documentation

std::ostream* Dv::Thread::Thread::log [static]
 

Stream to log info on, if not 0.

pthread_t Dv::Thread::Thread::id_ [private]
 

Posix thread id.

pthread_attr_t Dv::Thread::Thread::attributes_ [private]
 

Posix thread attributes.

int Dv::Thread::Thread::exit_status_ [private]
 

Exit status of this thread.

bool Dv::Thread::Thread::delete_after_main_ [private]
 

Should this object be deleted after Thread::main has completed?

bool Dv::Thread::Thread::signal_handler_installed [private]
 

Is a signal handler for SIGFPE installed? This should really be private but it is not since it is set from a C function.


The documentation for this class was generated from the following file:
dvthread-0.5.0 [22 June, 2006]