Module eco.sync
Coroutine synchronization primitives.
This module provides a small set of synchronization primitives designed for eco's cooperative coroutines (not OS threads):
All timeouts are expressed in seconds.
Functions
| cond () | Create a condition variable. |
| waitgroup () | Create a wait group. |
| mutex () | Create a mutex. |
Class cond
| cond:wait ([timeout]) | Wait until signaled. |
| cond:signal ([data]) | Wake one waiting coroutine. |
| cond:broadcast () | Wake all waiting coroutines. |
Class waitgroup
| waitgroup:add (delta) | Add delta to the wait group counter. |
| waitgroup:done () | Decrement the wait group counter by one. |
| waitgroup:wait ([timeout]) | Wait until the counter becomes zero. |
Class mutex
| mutex:lock ([timeout]) | Lock the mutex. |
| mutex:unlock () | Unlock the mutex. |
Functions
- cond ()
-
Create a condition variable.
Returns:
- waitgroup ()
-
Create a wait group.
One coroutine calls waitgroup:add to set the number of coroutines to wait for. Then each of those coroutines runs and calls waitgroup:done when finished. Meanwhile, waitgroup:wait can be used to block until all of them have finished.
Returns:
- mutex ()
-
Create a mutex.
Returns:
Class cond
A condition variable is a rendezvous point for coroutines waiting for, or announcing, the occurrence of an event.
- cond:wait ([timeout])
-
Wait until signaled.
If signaled with a non-nil truthy
data, returns thatdata. Otherwise returnstrue.Parameters:
- timeout number Timeout in seconds. (optional)
Returns:
-
any
Data passed to cond:signal, or
true.Or
- nil On timeout.
-
string
Error message (
'timeout').
- cond:signal ([data])
-
Wake one waiting coroutine.
If
datais provided and is truthy, the waiter will receivedataas the return value of cond:wait; otherwise it will receivetrue.Parameters:
- data any Data passed to the awakened waiter. (optional)
Returns:
-
boolean
trueif a waiter was awakened. - cond:broadcast ()
-
Wake all waiting coroutines.
All awakened waiters will receive
trueas the return value of cond:wait.Returns:
-
integer
n Number of awakened coroutines.
Class waitgroup
A wait group waits for a collection of coroutines to finish.
- waitgroup:add (delta)
-
Add delta to the wait group counter.
A positive
deltaincrements the number of workers to wait for. A negativedeltadecrements it.Parameters:
- delta integer
Raises:
If the counter would become negative. - waitgroup:done ()
-
Decrement the wait group counter by one.
When the counter reaches zero, all waiters are awakened.
Raises:
If the counter would become negative. - waitgroup:wait ([timeout])
-
Wait until the counter becomes zero.
Parameters:
- timeout number Timeout in seconds. (optional)
Returns:
-
boolean
true When the counter becomes zero.
Or
- nil On timeout.
-
string
Error message (
'timeout').
Class mutex
A mutex provides mutual exclusion between coroutines.
- mutex:lock ([timeout])
-
Lock the mutex.
If the mutex is already locked, the current coroutine waits until it becomes available or
timeoutexpires.Parameters:
- timeout number Timeout in seconds. (optional)
Returns:
-
boolean
true On success.
Or
- nil On timeout.
-
string
Error message (
'timeout').
- mutex:unlock ()
-
Unlock the mutex.
Wakes one coroutine waiting in mutex:lock.
Raises:
If the mutex is not locked.