MKHSequence

Lightweight tasks collection controller.

Swift vs. Objective-C

Note, that this description is valid for version 2.x, which is done in Swift 2.0. If you are looking for an Objective-C implementation and documentation, see tag/release 1.0.3.

Inspiration

This library has been inspired by PromiseKit, Objective-Chain and ReactiveCocoa.

The Goal

A tool for simple and elegant management of sequence of tasks that are being executed serially on a background queue with shared (among all tasks) error handler and completion handler being called on main queue after all tasks have been executed and completed successfully.

How It Works?

Sequence class implements generic queue-based (FIFO) collection of tasks that are supposed to be executed one-by-one. Each task is represented by a block which is being executed on the sequence target queue. You can add as many tasks to a sequence as you need, but at least one task is expected to make use of this class meaningful. Each task should expect to receive result from previous task as input parameter (expect the very first task where input parameter is always nil).

Any sequence might be provided with final (completion) block which will be called when all tasks have completed successfully. Completion block is always being called on main queue. If you do not need completion block - feel free to just call start() instead.

Sequence also might be configured with custom error handling block which will be called (with error as input parameter) if ANY of the tasks in the sequence has failed. To indicate failure, a task must return an instance of NSError class. In this case, the sequence will not call next task (or final/completion block). Instead it will call sequence error handling block and stop execution after that. Error handling block is always being called on main queue.

NOTE: Each task in a sequence may be also called step.

Key Features

Here are some key features that makes this library different from the others.

Lightweight syntax

Easy to use, minimal syntax. Minimum params have to be provided per each call to simplify usage and increase readability.

Code completion

This library does not use block-return class methods or run time "magic", so in Xcode you have full code-completion support.

Independent target queue per each sequence

The target queue (where all tasks of that given sequence will be executed one by one) can be set for each sequence independently from other sequences.

NOTE: The sequence target queue is automatically being set to global default value, so no need to setup target queue for each particular sequence explicitly. In turn, global default target queue is being set automatically to current queue, i.e. to the queue where sequence class has been used first time. It is recommended to setup global default target queue to a custom background serial queue explicitly before you start using Sequence class.

Pass result value between steps

Each task in a sequence returns an Any? value. This object is considered as a result of this step and will be passed to next task as input parameter.

Operates via main queue

Each sequence manages its flow on main queue, i.e. every step is being executed on target queue, but sequence passes results from previous task to next one and controls the flow via main queue.

Completion block

When all tasks from the sequence have been successfully completed, the sequence will call completion block with result of the very last task in the sequence.

Shared error handling block

Each sequence can be configured with shared error handling block which will be called (with error as input parameter) if ANY of the tasks in the sequence has indicated execution failure.

Cancellable

Any sequence might be cancelled at any time. If cancelled, sequence won't force to stop current task execution immediately, but will NOT proceed to next task or completion block.

How to add to your project

Just import module "MKHSequence" like this:

import MKHSequence

How To Use

Please, see unit tests to get an idea of how to use Sequence class.