Cgu::Thread::CancelBlock Class Reference

A class enabling the cancellation state of a thread to be controlled. More...

#include <c++-gtk-utils/thread.h>

Public Member Functions
int	restore (int &old_state)
int	restore ()
	CancelBlock (bool blocking=true)
	~CancelBlock ()

Static Public Member Functions
static int	block (int &old_state)
static int	block ()
static int	unblock (int &old_state)
static int	unblock ()

Detailed Description

A class enabling the cancellation state of a thread to be controlled.

A class enabling the cancellation state of a thread to be controlled, so as to provide exception safe cancellation state changes. When a CancelBlock object goes out of scope, the thread's cancellation state is returned to the state it was in immediately prior to the object's construction.

Cancellation state can be changed before a CancelBlock object goes out of scope by calling its block() and unblock() methods. However, care should be taken if calling unblock() for the purpose of enabling thread cancellation while the CancelBlock object is still in existence: this should normally only be done if the thread's cancellation state at the time the CancelBlock object was constructed (which is the cancellation state to which the thread will be restored when the object goes out of scope) was PTHREAD_CANCEL_DISABLE. This is because when a thread begins cancellation the POSIX standard states that it will automatically switch itself into a PTHREAD_CANCEL_DISABLE state (see System Interfaces, section 2.9.5, Thread Cancellation Cleanup Handlers), and the POSIX standard further states that the behaviour is undefined if a cancellation handler attempts to enable cancellation again while the thread is cleaning up - and any thread implementation such as NPTL which unwinds the stack on cancellation will do so if the CancelBlock's destructor would restore to PTHREAD_CANCEL_ENABLE state. Whilst it is to be expected that any cancellation stack unwinding implementation will behave sensibly in these circumstances, this is not mandated by POSIX, so making code relying on this less portable.

For these reasons, the same care should be exercised if passing 'false' to the CancelBlock constructor's 'blocking' argument.

Constructor & Destructor Documentation

CancelBlock()

Cgu::Thread::CancelBlock::CancelBlock

(

bool

blocking = true

)

The constructor will not throw.

Parameters

blocking

Whether the CancelBlock object should start in blocking mode. The 'Detailed Description' section above has information about the issues to be taken into account if 'false' is passed to this parameter.

~CancelBlock()

Cgu::Thread::CancelBlock::~CancelBlock ( )

inline

The destructor will put the thread in the cancellation state that it was in immediately before the CancelBlock object was constructed (which might be blocking). It will not throw.

This behaviour is from version 0.9.1. In version 0.9.0 cancellation state was always made non-blocking by the destructor.

Member Function Documentation

block() [1/2]

static int Cgu::Thread::CancelBlock::block ( )

inlinestatic

Makes the thread uncancellable, even if the code passes through a cancellation point, while the CancelBlock object exists (when the CancelBlock object ceases to exist, cancellation state is returned to the state prior to it being constructed). It should only be called by the thread which created the CancelBlock object. This method will not throw.

Returns

0 if successful, else a value other than 0.

block() [2/2]

static int Cgu::Thread::CancelBlock::block ( int &  old_state )

inlinestatic

Makes the thread uncancellable, even if the code passes through a cancellation point, while the CancelBlock object exists (when the CancelBlock object ceases to exist, cancellation state is returned to the state prior to it being constructed). It should only be called by the thread which created the CancelBlock object. This method will not throw.

Parameters

old_state

Indicates the cancellation state of the calling thread immediately before this call to block() was made, either PTHREAD_CANCEL_ENABLE (if the thread was previously cancellable) or PTHREAD_CANCEL_DISABLE (if this call did nothing because the thread was already uncancellable).

Returns

0 if successful, else a value other than 0.

restore() [1/2]

int Cgu::Thread::CancelBlock::restore ( )

inline

Restores cancellation state to the state it was in immediately before this CancelBlock object was constructed. It should only be called by the thread which created the CancelBlock object. This method will not throw.

Returns

0 if successful, else a value other than 0.

Since 0.9.1

restore() [2/2]

int Cgu::Thread::CancelBlock::restore ( int &  old_state )

inline

Restores cancellation state to the state it was in immediately before this CancelBlock object was constructed. It should only be called by the thread which created the CancelBlock object. This method will not throw.

Parameters

old_state

Indicates the cancellation state of the calling thread immediately before this call to restore() was made, either PTHREAD_CANCEL_DISABLE (if the thread was previously uncancellable) or PTHREAD_CANCEL_ENABLE (if this thread was previously cancellable).

Returns

0 if successful, else a value other than 0.

Since 0.9.1

unblock() [1/2]

static int Cgu::Thread::CancelBlock::unblock ( )

inlinestatic

Makes the thread cancellable while the CancelBlock object exists (when the CancelBlock object ceases to exist, cancellation state is returned to the state prior to it being constructed). It should only be called by the thread which created the CancelBlock object. This method will not throw. The 'Detailed Description' section above has information about the issues to be taken into account if a call to this method is to be made.

Returns

0 if successful, else a value other than 0.

unblock() [2/2]

static int Cgu::Thread::CancelBlock::unblock ( int &  old_state )

inlinestatic

Makes the thread cancellable while the CancelBlock object exists (when the CancelBlock object ceases to exist, cancellation state is returned to the state prior to it being constructed). It should only be called by the thread which created the CancelBlock object. This method will not throw. The 'Detailed Description' section above has information about the issues to be taken into account if a call to this method is to be made.

Parameters

old_state

Indicates the cancellation state of the calling thread immediately before this call to unblock() was made, either PTHREAD_CANCEL_DISABLE (if the thread was previously uncancellable) or PTHREAD_CANCEL_ENABLE (if this call did nothing because the thread was already cancellable).

Returns

0 if successful, else a value other than 0.

---

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

• thread.h