Inherits from NSObject
Declared in RKOperationStateMachine.h

Overview

The RKOperationStateMachine class provides an implementation of a state machine that is suitable for implementing a concurrent NSOperation subclass via composition. The concurrency mechanism is a dispatch queue. The state machine takes care of correctly implementing all aspects of a concurrent NSOperation including: 1. Asynchronous execution 1. Locking 1. Appropriate state transitions 1. Cancellation 1. State Instrospection

The state machine begins its life in the ready state. Upon start, the state transitions to executing and a user-supplied execution block is invoked on the operation’s dispatch queue. The operation remains in the executing state until it is finished. Just before the operation is finished, a finalization block is invoked. In the event that the operation is cancelled, then an optional cancellation block is invoked. Note that because cancellation semantics can vary widely, a cancelled operation is merely flagged as being cancelled. It is the responsibility of the operation to ensure that a cancelled operation is finished as soon as possible.

The underlying implementation of the state machine is backed by TransitionKit

Tasks

Other Methods

Initializing a State Machine

Inspecting State

  •   ready

    Returns a Boolean value that indicates if the receiver is ready to be started.

    property
  •   executing

    Returns a Boolean value that indicates if the receiver is executing.

    property
  •   cancelled

    Returns a Boolean value that indicates if the receiver has been cancelled.

    property
  •   finished

    Returns a Boolean value that indicates if the receiver has finished executing.

    property

Firing Events

Configuring Event Handlers

Accessing Configuration

  •   operation

    The operation that the receiver is modeling the lifecycle of.

    property
  •   dispatchQueue

    The dispatch queue within which the state machine executes.

    property

Performing Blocks that Mutate State

  • – performBlockWithLock:

    Executes a block after acquiring an exclusive lock on the receiver. This enables the block to safely mutate the state of the operation. The execution context of the block is not changed – it is always executed within the caller’s thread context. If you wish to guarantee execution on the dispatch queue backing the state machine then you must dispatch onto the queue before submitting your block for execution.

Properties

cancelled

@property (nonatomic, getter=isCancelled, readonly) BOOL cancelled
Discussion

Returns a Boolean value that indicates if the receiver has been cancelled.

Return Value

YES if the receiver has been cancelled, else NO.

Declared In

RKOperationStateMachine.h

dispatchQueue

@property (nonatomic, assign, readonly) dispatch_queue_t dispatchQueue
Discussion

The dispatch queue within which the state machine executes.

Declared In

RKOperationStateMachine.h

executing

@property (nonatomic, getter=isExecuting, readonly) BOOL executing
Discussion

Returns a Boolean value that indicates if the receiver is executing.

Return Value

YES if the receiver is executing, else NO.

Declared In

RKOperationStateMachine.h

finished

@property (nonatomic, getter=isFinished, readonly) BOOL finished
Discussion

Returns a Boolean value that indicates if the receiver has finished executing.

Return Value

YES if the receiver is finished, else NO.

Declared In

RKOperationStateMachine.h

operation

@property (nonatomic, weak, readonly) NSOperation *operation
Discussion

The operation that the receiver is modeling the lifecycle of.

Declared In

RKOperationStateMachine.h

ready

@property (nonatomic, getter=isReady, readonly) BOOL ready
Discussion

Returns a Boolean value that indicates if the receiver is ready to be started.

Return Value

YES if the receiver is ready to be started, else NO.

Declared In

RKOperationStateMachine.h

Instance Methods

cancel

- (void)cancel
Discussion

Marks the operation is being cancelled. Cancellation results in state transition because cancellation semantics can vary widely. Once the cancellation flag has been set (isCancelled return YES), the cancellation block is invoked asynchronously on the operation dispatch queue. The operation must be finished as soon as possible.

Declared In

RKOperationStateMachine.h

finish

- (void)finish
Discussion

Finishes the operation by transitioning from the executing state to the finished state. The state transition is executed asynchronously on the operation dispatch queue. Invokes the finalization block just before the state changes from executing to finished.

Declared In

RKOperationStateMachine.h

init

- (instancetype)init

initWithOperation:dispatchQueue:

- (instancetype)initWithOperation:(NSOperation *)operation dispatchQueue:(dispatch_queue_t)dispatchQueue
Discussion

Initializes a new state machine object with a given operation and dispatch queue.

Parameters

operation

The operation that the receiver is modeling the concurrent lifecycle of.

dispatchQueue

The dispatch queue on which the operation executes concurrently.

Return Value

The receiver, initialized with the given operation and queue.

Declared In

RKOperationStateMachine.h

performBlockWithLock:

- (void)performBlockWithLock:(void ( ^ ) ( ))block
Discussion

Executes a block after acquiring an exclusive lock on the receiver. This enables the block to safely mutate the state of the operation. The execution context of the block is not changed – it is always executed within the caller’s thread context. If you wish to guarantee execution on the dispatch queue backing the state machine then you must dispatch onto the queue before submitting your block for execution.

Parameters

block

The block to execute after acquiring an exclusive lock on the receiver.

Declared In

RKOperationStateMachine.h

setCancellationBlock:

- (void)setCancellationBlock:(void ( ^ ) ( void ))block
Discussion

Sets a block to be executed when the operation is cancelled. The block will be invoked on the operation dispatch queue. Cancellation does not trigger any state transition – the operation must still be explicitly finished as soon as possible. If appropriate, the operation may be finished within the body of the cancellation block.

Parameters

block

The block to be executed.

Declared In

RKOperationStateMachine.h

setExecutionBlock:

- (void)setExecutionBlock:(void ( ^ ) ( void ))block
Discussion

Sets a block to be executed on the operation dispatch queue once the operation transitions to the executing state.

Parameters

block

The block to be executed.

Declared In

RKOperationStateMachine.h

setFinalizationBlock:

- (void)setFinalizationBlock:(void ( ^ ) ( void ))block
Discussion

Sets a block to be executed when the operation is about to transition from executing to finished. This block is invoked regardless of the cancellation state. This block should be used to perform any last minute cleanup or preparation before the operation finishes.

Parameters

block

The block to be executed.

Declared In

RKOperationStateMachine.h

start

- (void)start
Discussion

Starts the operation by transitioning into the executing state and asychronously invoking the execution block on the operation dispatch queue.

Declared In

RKOperationStateMachine.h