DCMTK: OFThread Class Reference

DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Static Public Attributes | Static Protected Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
OFThread Class Referenceabstract

provides an operating system independent abstraction for threads. More...

Inheritance diagram for OFThread:

## Public Member Functions
| OFThread ()
| default constructor.
virtual | ~OFThread ()
| destructor.
int | start ()
| adds a new thread of control to the current process.
int | join ()
| blocks the calling thread until the thread referenced by the OFThread object terminates.
unsigned long | threadID ()
| returns the thread identifier of the thread referenced by the OFThread object, if the thread has already been started.
OFBool | equal (unsigned long tID)
| checks if the given thread ID matches the thread ID of the thread referenced by this object.

## Static Public Member Functions
static void | errorstr (OFString &description, int code)
| converts any of the error codes returned by the methods of this class into a textual description, which is written into the string object.

## Static Public Attributes
static const int | busy
| this constant is returned by the join() method if another thread is already waiting for termination of the thread referenced by the OFThread object.

## Static Protected Member Functions
static void | thread_exit ()
| terminates the calling thread, in a similar way that exit() terminates the calling process.
static unsigned long | self ()
| returns the thread ID of the calling thread.

## Private Member Functions
virtual void | run ()=0
| this method implements the thread that is run by calling the start method of the OFThread object.
| OFThread (const OFThread &arg)
| unimplemented private copy constructor
OFThread & | operator= (const OFThread &arg)
| unimplemented private assignment operator

## Private Attributes
unsigned long | theThread
| thread identifier

## Friends
DCMTK_OFSTD_EXPORT void * | thread_stub (void *arg)
| thread stub must be friend to call run()

## Detailed Description

provides an operating system independent abstraction for threads.

Threads are executed asynchronously in parallel to the main thread of the process. On multi-processor machines threads may run on different CPUs if the operating system permits. This class is abstract. Deriving classes must implement the run() method which contains the code executed by the thread.

## Constructor & Destructor Documentation

## ◆ OFThread()

OFThread::OFThread | ( |  | ) |

default constructor.

The new thread is not started immediately upon creation of the OFThread object. Calling the start() method causes the creation of the thread.

Referenced by OFThread(), and operator=().

## ◆ ~OFThread()

virtual OFThread::~OFThread | ( |  | ) |
| virtual

destructor.

Destruction of an OFThread object does not cause the referenced thread to be stopped and may result in undefined behaviour if the derived class maintains thread specific data in this object (which is not recommended). The join() method should be called prior to destruction of the thread object to make sure a thread has terminated.

## Member Function Documentation

## ◆ equal()

OFBool OFThread::equal | ( | unsigned long | tID | ) |

checks if the given thread ID matches the thread ID of the thread referenced by this object.

Parameters

  tID | thread ID to be compared

Returns
  OFTrue if equal, OFFalse otherwise.

## ◆ errorstr()

void OFThread::errorstr | ( | OFString & | description,
|  | int | code )
| static

converts any of the error codes returned by the methods of this class into a textual description, which is written into the string object.

Parameters

  description | string object into which the error description is written.
  code | error code

## ◆ join()

int OFThread::join | ( |  | ) |

blocks the calling thread until the thread referenced by the OFThread object terminates.

Several threads cannot wait for the same thread to complete; one thread will complete the join() method successfully others may or may not return OFThread::busy. The method will not block the calling thread if the target thread has already terminated.

Returns
  0 upon success, OFThread::busy if another thread is already waiting for the termination of the target thread, an error code otherwise.

## ◆ run()

virtual void OFThread::run | ( |  | ) |
| privatepure virtual

this method implements the thread that is run by calling the start method of the OFThread object.

Defined as abstract method in OFThread. It is recommended that derived classes implementing this method do not rely on attributes of the OFThread object because this might result in undefined behaviour if another thread deletes or restarts the OFThread object before the thread has terminated.

Implemented in DcmBaseSCPPool::DcmBaseSCPWorker, FGInterface::ThreadedFGReader, and FGInterface::ThreadedFGWriter.

References theThread.

## ◆ self()

unsigned long OFThread::self | ( |  | ) |
| staticprotected

returns the thread ID of the calling thread.

For a running thread, this->threadID() and this->self() should return the same value, but self() is more robust and should be preferred. On certain platforms like OSF/1, a thread ID contains a pointer to a structure. Therefore, thread IDs should never be compared directly, but always using the equal() method provided in this class.

Returns
  thread ID of the calling thread.

## ◆ start()

int OFThread::start | ( |  | ) |

adds a new thread of control to the current process.

The main() procedure itself is a single thread of control. Each thread executes simultaneously with all the other threads within the calling process. A newly created thread shares all of the calling process' global data with the other threads in this process except the execution stack. The new thread executes the run() method and terminates upon return from this method or a call to thread_exit() from within the thread. This method should not be called if a thread is already running, otherwise a new thread will be started and the identifier of the old thread will be overwritten, making it impossible to call join() for the old thread. It may also result in undefined behaviour if the derived class maintains thread specific data in this object (which is not recommended).

Returns
  0 upon success, an error code otherwise.

## ◆ thread_exit()

void OFThread::thread_exit | ( |  | ) |
| staticprotected

terminates the calling thread, in a similar way that exit() terminates the calling process.

This method does not return.

## ◆ threadID()

unsigned long OFThread::threadID | ( |  | ) |

returns the thread identifier of the thread referenced by the OFThread object, if the thread has already been started.

Otherwise returns 0. On certain platforms like OSF/1, a thread ID contains a pointer to a structure. Therefore, thread IDs should never be compared directly, but always using the equal() method provided in this class.

Returns
  thread ID of target thread if started, 0 otherwise.

## Related Definitions

## ◆ thread_stub

DCMTK_OFSTD_EXPORT void * thread_stub | ( | void * | arg | ) |
| friend

thread stub must be friend to call run()

Parameters

  arg | pointer to the OFThread instance to be started, passed as void pointer.

Referenced by operator=().

## Member Data Documentation

## ◆ busy

const int OFThread::busy
| static

this constant is returned by the join() method if another thread is already waiting for termination of the thread referenced by the OFThread object.

Since this value is operating system dependent, comparisons should always compare the return value of join() with this constant.

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

- ofstd/include/dcmtk/ofstd/ofthread.h

Generated on for DCMTK Version 3.7.0 by Doxygen 1.16.1