TaskQueue
Table of Contents
- Intro
- Installation
- Simple Examples
- Serial and Concurrent Tasks
- GCD Queue Control
- Extensive Example
- Credit
- License
Intro
TaskQueue is a Swift library which allows you to schedule tasks once and then let the queue execute them in a synchronous manner. The great thing about TaskQueue is that you get to decide on which GCD queue each of your tasks should execute beforehand and leave TaskQueue to do switching of the queues as it goes.
Even if your tasks are asynchronious like fetching location, downloading files, etc. TaskQueue will wait until they are finished before going on with the next task.
Last but not least your tasks have full flow control over the queue, depending on the outcome of the work you are doing in your tasks you can skip the next task, abort the queue, or jump ahead to the queue completion. You can further pause, resume, and stop the queue.
Installation
CocoaPods
CocoaPods is a dependency manager for Cocoa projects.
If you don't already have the Cocoapods gem installed, run the following command:
$ gem install cocoapods
To integrate TaskQueue into your Xcode project using CocoaPods, specify it in your Podfile
:
pod 'TaskQueue'
Then, run the following command:
$ pod install
If you find that you're not having the most recent version installed when you run pod install
then try running:
$ pod cache clean
$ pod repo update TaskQueue
$ pod install
Also you'll need to make sure that you've not got the version of TaskQueue locked to an old version in your Podfile.lock
file.
Carthage
Carthage is a decentralized dependency manager that automates the process of adding frameworks to your Cocoa application.
You can install Carthage with Homebrew using the following command:
$ brew update
$ brew install carthage
To integrate TaskQueue into your Xcode project using Carthage, specify it in your Cartfile
:
github "icanzilb/TaskQueue"
Simple Example
Synchronous tasks
Here's the simplest way to use TaskQueue in Swift:
let queue = TaskQueue()
queue.tasks +=~ {
... time consuming task on a background queue...
}
queue.tasks +=! {
... update UI on main queue ...
}
queue.run()
TaskQueue will execute the tasks one after the other waiting for each task to finish and the will execute the next one. By using the operators +=~
and +=!
you can easily set whether the task should execute in background or on the main queue.
Asynchronous tasks
More interesting of course is when you have to do some asynchronous work in the background of your tasks. Then you can fetch the next
parameter in your task and call it whenever your async work is done:
let queue = TaskQueue()
queue.tasks +=~ { result, next in
var url = URL(string: "http://jsonmodel.com")
URLSession.shared.dataTask(with: url,
completionHandler: { _, _, _ in
// process the response
next(nil)
})
}
queue.tasks +=! {
print("execute next task after network call is finished")
}
queue.run {
print("finished")
}
There are a few things to highlight in the example above:
-
The first task closure gets two parameters:
result
is the result from the previous task (nil
in the case of the first task) andnext
.next
is a closure you need to call whenver your async task has finished executing. -
Task nr.2 doesn't get started until you call
next()
in your previous task. -
The
run
function can also take a closure as a parameter - if you pass one it will always get executed after all other tasks has finished.
Serial and Concurrent Tasks
By default TaskQueue executes its tasks one after another or, in other words, the queue has up to one active task at a time.
You can, however, allow a given number of tasks to execute at the same time (e.g. if you need to download a number of image files from web). To do this just increase the number of active tasks and the queue will automatically start executing tasks concurrently. For example:
queue.maximumNumberOfActiveTasks = 10
This will make the queue execute up to 10 tasks at the same time.
Note: As soon as you allow for more than one task at a time certain restrictions apply: you cannot invoke retry(), and you cannot pass a result from one task to another.
GCD Queue Control
Do you want to run couple of heavy duty tasks in the background and then switch to the main queue to update your app UI? Easy. Study the example below, which showcases GCD queue control with TaskQueue:
let queue = TaskQueue()
//
// "+=" adds a task to be executed on the current queue
//
queue.tasks += {
// update the UI
}
//
// "+=~" adds a task to be executed in the background, e.g. low prio queue
// "~" stands for so~so priority
//
queue.tasks +=~ {
// do heavy work
}
//
// "+=!" adds a task to be executed on the main queue
// "!" stands for High! priority
//
queue.tasks +=! {
// update the UI again
}
// to start the queue on the current GCD queue
queue.run()
Extensive example
let queue = TaskQueue()
//
// Simple sync task, just prints to console
//
queue.tasks += {
print("====== tasks ======")
print("task #1: run")
}
//
// A task, which can be asynchronious because it gets
// result and next params and can call next() when ready
// with async work to tell the queue to continue running
//
queue.tasks += { result, next in
print("task #2: begin")
delay(seconds: 2) {
print("task #2: end")
next(nil)
}
}
//
// A task which retries the same task over and over again
// until it succeeds (i.e. util when you make network calls)
// NB! Important to capture **queue** as weak to prevent
// memory leaks!
//
var cnt = 1
queue.tasks += { [weak queue] result, next in
print("task #3: try #\(cnt)")
cnt += 1
if cnt > 3 {
next(nil)
} else {
queue!.retry(delay: 1)
}
}
//
// This task skips the next task in queue
// (no capture cycle here)
//
queue.tasks += {
print("task #4: run")
print("task #4: will skip next task")
queue.skip()
}
queue.tasks += {
print("task #5: run")
}
//
// This task removes all remaining tasks in the queue
// i.e. util when an operation fails and the rest of the queueud
// tasks don't make sense anymore
// NB: This does not remove the completions added
//
queue.tasks += {
print("task #6: run")
print("task #6: will append one more completion")
queue.run { _ in
print("completion: appended completion run")
}
print("task #6: will skip all remaining tasks")
queue.removeAll()
}
queue.tasks += {
print("task #7: run")
}
//
// This either runs or resumes the queue
// If queue is running doesn't do anything
//
queue.run()
//
// This either runs or resumes the queue
// and adds the given closure to the lists of completions.
// You can add as many completions as you want (also half way)
// trough executing the queue.
//
queue.run { result in
print("====== completions ======")
print("initial completion: run")
}
Run the included demo app to see some of these examples above in action.
Credit
Author: Marin Todorov
License
TaskQueue is available under the MIT license. See the LICENSE file for more info.