RKOperationStateMachine Class Reference
| 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
Initializing a State Machine
-
– initWithOperation:dispatchQueue:Initializes a new state machine object with a given operation and dispatch queue.
Inspecting State
-
– isReadyReturns a Boolean value that indicates if the receiver is ready to be started.
-
– isExecutingReturns a Boolean value that indicates if the receiver is executing.
-
– isCancelledReturns a Boolean value that indicates if the receiver has been cancelled.
-
– isFinishedReturns a Boolean value that indicates if the receiver has finished executing.
Firing Events
-
– startStarts the operation by transitioning into the executing state and asychronously invoking the execution block on the operation dispatch queue.
-
– finishFinishes 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.
-
– cancelMarks the operation is being cancelled. Cancellation results in state transition because cancellation semantics can vary widely. Once the cancellation flag has been set (
isCancelledreturnYES), the cancellation block is invoked asynchronously on the operation dispatch queue. The operation must be finished as soon as possible.
Configuring Event Handlers
-
– setExecutionBlock:Sets a block to be executed on the operation dispatch queue once the operation transitions to the executing state.
-
– setCancellationBlock: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.
-
– setFinalizationBlock: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.
Accessing Configuration
-
operationThe operation that the receiver is modeling the lifecycle of.
property -
dispatchQueueThe dispatch queue within which the state machine executes.
property
Properties
Instance Methods
cancel
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.
- (void)cancelDeclared In
RKOperationStateMachine.hfinish
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.
- (void)finishDeclared In
RKOperationStateMachine.hinitWithOperation:dispatchQueue:
Initializes a new state machine object with a given operation and dispatch queue.
- (id)initWithOperation:(NSOperation *)operation dispatchQueue:(dispatch_queue_t)dispatchQueueParameters
- 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.hisCancelled
Returns a Boolean value that indicates if the receiver has been cancelled.
- (BOOL)isCancelledReturn Value
YES if the receiver has been cancelled, else NO.
Declared In
RKOperationStateMachine.hisExecuting
Returns a Boolean value that indicates if the receiver is executing.
- (BOOL)isExecutingReturn Value
YES if the receiver is executing, else NO.
Declared In
RKOperationStateMachine.hisFinished
Returns a Boolean value that indicates if the receiver has finished executing.
- (BOOL)isFinishedReturn Value
YES if the receiver is finished, else NO.
Declared In
RKOperationStateMachine.hisReady
Returns a Boolean value that indicates if the receiver is ready to be started.
- (BOOL)isReadyReturn Value
YES if the receiver is ready to be started, else NO.
Declared In
RKOperationStateMachine.hsetCancellationBlock:
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.
- (void)setCancellationBlock:(void ( ^ ) ( void ))blockParameters
- block
The block to be executed.
Declared In
RKOperationStateMachine.hsetExecutionBlock:
Sets a block to be executed on the operation dispatch queue once the operation transitions to the executing state.
- (void)setExecutionBlock:(void ( ^ ) ( void ))blockParameters
- block
The block to be executed.
Declared In
RKOperationStateMachine.hsetFinalizationBlock:
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.
- (void)setFinalizationBlock:(void ( ^ ) ( void ))blockParameters
- block
The block to be executed.
Declared In
RKOperationStateMachine.h