Module (`cthread`)¶

The documentation of the cthread package is outlined below.

Exceptions
Classes

Exceptions ¶

The custom exceptions that cthread can raise are documented below.

exception cthread.CThreadException(message=None, *args, **kwargs)[source]¶

Bases: Exception

Base class of any ControllableThread exception.

All exceptions that are thrown by the cthread module inherit from this exception. This specific exception instance is however never raised.

Parameters: message (str, optional) – Information about the exception that was raised.

exception cthread.CallbackNotImplemented(message=None, *args, **kwargs)[source]¶

Bases: cthread.cthread.CThreadException

A state callback function has not been implemented by the child class.

This exception is raised if a cthread.ControllableThread is created without overwriting a particular state callback function.

Parameters: message (str, optional) – Information about the exception that was raised.

exception cthread.InvalidArgument(message=None, *args, **kwargs)[source]¶

Bases: cthread.cthread.CThreadException

Base class of any invalid argument exception.

This exception is raised if an invalid argument is input to any publicly accessible cthread method. This specific exception instance is however never raised.

Parameters: message (str, optional) – Information about the exception that was raised.

exception cthread.InvalidState(message=None, *args, **kwargs)[source]¶

Bases: cthread.cthread.InvalidArgument

Base class of an unrecognised thread state.

This exception is raised if a thread state is not recognised. While this exception is a base class of an unrecognised thread state, this specific instance could also be raised.

Parameters: message (str, optional) – Information about the exception that was raised.

exception cthread.InvalidMaxState(message=None, *args, **kwargs)[source]¶

Bases: cthread.cthread.InvalidState

Maximum thread state is not recognised.

This exception is raised if the maximum thread state is not recognised.

Parameters: message (str, optional) – Information about the exception that was raised.

exception cthread.InvalidAlternativeState(message=None, *args, **kwargs)[source]¶

Bases: cthread.cthread.InvalidState

Alternative thread state is not recognised.

This exception is raised if the required updated state of the thread is not a registered alternative state.

Parameters: message (str, optional) – Information about the exception that was raised.

exception cthread.InvalidCallback(message=None, *args, **kwargs)[source]¶

Bases: cthread.cthread.InvalidArgument

No alternative state callback functions supplied.

This exception is raised if the thread is initialised with alternative states but not alternative state callback functions.

Parameters: message (str, optional) – Information about the exception that was raised.

exception cthread.InvalidName(message=None, *args, **kwargs)[source]¶

Bases: cthread.cthread.InvalidArgument

Desired name of the thread is not a string.

This exception is raised if the name of the thread is not a string.

Parameters: message (str, optional) – Information about the exception that was raised.

exception cthread.InvalidQueue(message=None, *args, **kwargs)[source]¶

Bases: cthread.cthread.InvalidArgument

No communication method to the initialising thread.

This exception is raised if an instance of a cthread.ControllableThread is initialised without a means of communicating with the thread that initialises it.

Parameters: message (str, optional) – Information about the exception that was raised.

Classes ¶

The classes contained within the cthread package are documented below.

class cthread.ControllableThread(name, queue, **kwargs)[source]¶

Bases: threading.Thread

Parent class for any cthread.ControllableThread.

Allows threads to be killed, paused and resumed, and allows for direct communication to the main initialising thread.

Parameters

name (str) – Name of the thread.
queue (queue.Queue) – Priority queue for communication to the main thread.

Raises

cthread.InvalidName – If name is not a string.
cthread.InvalidQueue – If queue is not a Queue.
cthread.InvalidCallback – If kwargs are not a dictionary of functions.

alt(name)[source]¶

Updates the state of the thread to a registered alternative state.

Note that the state must be a registered alternative state in order for the thread to be updated to the desired state.

Parameters: name (str) – Name of the state to which the thread will be updated.
Raises: cthread.InvalidAlternativeState – If the required updated state of the thread is not a registered alternative state.

kill()[source]¶: Updates the state of the thread to ThreadState.KILLED.

pause()[source]¶: Updates the state of the thread to ThreadState.PAUSED.

reset()[source]¶: Updates the state of the thread to ThreadState.STARTED.

resume()[source]¶: Updates the state of the thread to ThreadState.RESUMED.

run()[source]¶

Entry point for the thread.

Contains the cyclic executive of the thread. There are at least six possible states for the thread:

STARTED
ACTIVE
IDLE
PAUSED
RESUMED
KILLED
Any alternative individual thread-specific states.

Each of these states has a callback function that must be implemented in any of the child threads. Of course, the alterative state callback should not be implemented if there are no alternative states.

This cyclic executive will execute as long as the thread is not killed.

Raises: cthread.CallbackNotImplemented – If any of the following callback functions were not overwritten: cthread.ControllableThread._started_callback(), cthread.ControllableThread._active_callback(), cthread.ControllableThread._paused_callback(), cthread.ControllableThread._resumed_callback(), or cthread.ControllableThread._killed_callback().

class cthread.ThreadState[source]¶

Bases: object

Represents the state of the thread.

STARTED¶

Numerical encoding of the ‘started’ thread state.

Type: int

ACTIVE¶

Numerical encoding of the ‘active’ thread state.

Type: int

IDLE¶

Numerical encoding of the ‘idle’ thread state.

Type: int

PAUSED¶

Numerical encoding of the ‘paused’ thread state.

Type: int

RESUMED¶

Numerical encoding of the ‘resumed’ thread state.

Type: int

KILLED¶

Numerical encoding of the ‘killed’ thread state.

Type: int

get_state()[source]¶

Gets the state of the thread.

Returns

State of the thread. There are at least six possible return values:

ThreadState.STARTED: if the thread is being initialised,

ThreadState.ACTIVE: if the thread is currently running,

ThreadState.IDLE: if the thread is currently not running,

ThreadState.PAUSED: if the thread is transitioning from running to not running.

ThreadState.RESUMED: if the thread is transitioning from not running to running.

ThreadState.KILLED: if the thread is in the process of terminating, and

Any other user-defined thread states.

Return type

int

update_max_state(maxState)[source]¶

Updates the maximum state of the thread.

The maxState value is used to determine the validity of a state to supplied to the cthread.ThreadState.update_state() function. The state of the thread must be within a predefined range, or else it is an invalid state. The maxState is also not a fixed constant because the user can define their own states, and hence the validity check of a state must accomodate these user-defined states.

Parameters: maxState (int) – Maximum state that the thread can take.
Raises: cthread.InvalidState – If the maximum state is <= ThreadState.KILLED.

update_state(state)[source]¶

Updates the state of the thread.

Parameters: state (int) – New state of the thread.
Raises: cthread.InvalidState – If state < ThreadState.STARTED or state > ThreadState._maxState

Module (cthread)¶

Exceptions¶

Classes¶

Module (`cthread`)¶

Exceptions ¶

Classes ¶