Venice
Venice provides structured concurrency and CSP for Swift.
Features
- Coroutines
- Coroutine cancelation
- Coroutine groups
- Channels
- Receive-only channels
- Send-only channels
- File descriptor polling
Venice wraps a fork of the C library libdill.
Installation
Before using Venice you need to install our libdill fork. Follow the instruction for your operating system.
macOS
On macOS install libdill using brew.
brew install zewo/tap/libdill
Linux
On Linux we have to add our apt source first. You only need to run this command once in a lifetime. You don't need to run it again if you already have.
echo "deb [trusted=yes] http://apt.zewo.io ./" | sudo tee -a /etc/apt/sources.list
sudo apt-get update
Now just install the libdill apt package.
sudo apt-get install libdill
Add Venice to Package.swift
After installing libdill just add Venice
as a dependency in your Package.swift
file.
import PackageDescription
let package = Package(
dependencies: [
.Package(url: "https://github.com/Zewo/Venice.git", majorVersion: 0, minor: 19)
]
)
Test Coverage
The inner-most circle is the entire project, moving away from the center are folders then, finally, a single file. The size and color of each slice is represented by the number of statements and the coverage, respectively.
Documentation
You can check the Venice API reference for more in-depth documentation.
Structured Concurrency
Structured concurrency means that lifetimes of concurrent functions are cleanly nested. If coroutine foo
launches coroutine bar
, then bar
must finish before foo
finishes.
This is not structured concurrency:
This is structured concurrency:
The goal of structured concurrency is to guarantee encapsulation. If the main
function calls foo
, which in turn launches bar
in a concurrent fashion, main
will be guaranteed that once foo
has finished, there will be no leftover functions still running in the background.
What you end up with is a tree of coroutines rooted in the main
function. This tree spreads out towards the smallest worker functions, and you may think of this as a generalization of the call stack — a call tree, if you will. In it, you can walk from any particular function towards the root until you reach the main function:
Venice implements structured concurrency by allowing you to cancel a running coroutine.
let coroutine = try Coroutine {
let resource = malloc(1000)
defer {
free(resource)
}
while true {
try Coroutine.wakeUp(100.milliseconds.fromNow())
print(".")
}
}
try Coroutine.wakeUp(1.second.fromNow())
coroutine.cancel()
When a coroutine is being canceled all coroutine-blocking calls will start to throw VeniceError.canceledCoroutine
. On one hand, this forces the function to finish quickly (there's not much you can do without coroutine-blocking functions); on the other hand, it provides an opportunity for cleanup.
In the example above, when coroutine.cancel
is called the call to Coroutine.wakeUp
inside the coroutine will throw VeniceError.canceledCoroutine
and then the defer
statement will run, thus releasing the memory allocated for resource
.
Threads
You can use Venice in multi-threaded programs. However, individual threads are strictly separated. You may think of each thread as a separate process.
In particular, a coroutine created in a thread will be executed in that same thread, and it will never migrate to a different one.
In a similar manner, a handle, such as a channel or a coroutine handle, created in one thread cannot be used in a different thread.
License
This project is released under the MIT license. See LICENSE for details.