Runnable State

Each runnable object maintains two pieces of state information: a current execution state, and a current completion state. The following paragraphs explain the various operations that the Threading package includes for manipulating runnable objects and their state.

Many of these operations rely on or make changes to the execution or completion state of a runnable. To help you better understand these relationships, study the state diagrams in the two diagrams on this page and use them as a reference as you read.

The current execution state is represented by the enumerated type RWExecutionState, which defines the following state values:

  • RW_THR_INITIAL — The initial state is used to indicate when a runnable is inactive. A runnable is created in the initial state and always returns to the initial state after it completes execution.

  • RW_THR_STARTING — A runnable temporarily enters the starting state after start() is called and remains in that state until the runnable is ready to execute its internal run() member.

  • RW_THR_RUNNING — The runnable is active and executing inside its run() member.

  • RW_THR_INTERRUPTED — The runnable is active, but has been interrupted, and is currently waiting to be released from the interrupt.

  • RW_THR_SUSPENDED — The threaded runnable is active, but its thread has been suspended, and is waiting to be resumed.

  • RW_THR_CANCELING — The runnable is active, but is currently attempting cancellation.

  • RW_THR_ABORTING — The runnable is active and has aborted an attempted cancellation.

  • RW_THR_SLEEPING — The runnable is active, but its thread is currently sleeping.

  • RW_THR_YIELDING — The runnable is active, but its thread is currently yielding execution.

  • RW_THR_SERVER_WAIT — The runnable server is active, but is currently waiting for another runnable to be enqueued for execution.

  • RW_THR_EXCEPTION — The runnable is exiting because an exception was produced.

  • RW_THR_TERMINATING — The runnable is being terminated by another thread.

The following figure demonstrates the various execution state transitions.

Execution state transitions

The current completion state is represented by the enumerated type RWCompletionState, which defines the following state values:

  • RW_THR_PENDING: The runnable has not been started since it was created, or the runnable is currently active. The completion state is reset to RW_THR_PENDING each time start() is called.

  • RW_THR_NORMAL: The runnable completed execution normally.

  • RW_THR_FAILED: The runnable exited with an exception.

  • RW_THR_CANCELED: The runnable was canceled.

  • RW_THR_TERMINATED: The thread executing the runnable was terminated.

The following figure demonstrates the various completion state transitions.

Completion state transitions

In addition to the execution and completion states, each runnable also captures any exceptions produced during execution. Any of these exceptions can be recovered by requesting the runnable to rethrow the exception.