blob: bec60a047e074c15992a80ac30c9ef0c7a2ee535 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
# coil
A tiny cooperative threading module for Lua. Coil is based around coroutines,
allowing many cooperative threads to run simultaneously.
## Usage
The [coil.lua](coil.lua) file should be dropped into an existing project and
required by it.
```lua
coil = require "coil"
```
At the start of each frame `coil.update()` should be called and given the delta
time since the last call as its argument.
```lua
coil.update(deltatime)
```
Coil refers to each cooperative thread as a *task*; new tasks can be created by
using the `coil.add()` function.
```lua
-- prints the word "hello" each second for 5 seconds
coil.add(function()
for i = 1, 5 do
print("hello")
coil.wait(1)
end
end)
```
### coil.wait()
As tasks are cooperative, they must be manually yielded to allow other parts of
the program to continue. This is done by calling the `coil.wait()` function.
The function can be used to wait for different events before continuing.
* If wait is called with a number as its argument then it waits for that number
of seconds before resuming.
* If wait is called with a callback created by coil.callback() it will wait
until that callback function is called before resuming; it will return the
arguments passed to the callback when it was called.
* If wait is called with no arguments it waits until the next frame
(`coil.update()` call) before resuming; it returns the time that has passed
since the last frame.
### coil.callback()
The `coil.callback()` function can be used to create a special callback which,
if passed to the `coil.wait()` function, will cause the task to wait until the
callback is called.
```lua
-- Prints "Hello world" when `cb()` is called.
coil.add(function()
cb = coil.callback()
coil.wait(cb)
print("Hello world")
end)
```
### coil.update(dt)
This should be called at the start of each frame. Updates all the tasks,
running those which aren't waiting or paused. `dt` should be the amount of time
in seconds which has passed since the function was last called.
### coil.add(fn)
Adds a new task, the task will begin running on the next call to
`coil.update()`.
```lua
-- prints "hello world" every 2 seconds
coil.add(function()
while 1 do
print("hello world")
coil.wait(2)
end
end)
```
## Stopping a task
A task can be stopped and removed at any point by calling its `:stop()` method.
To do this the task must be assigned to a variable when it is created.
```lua
-- Adds a new task
local t = coil.add(function()
coil.wait(1)
print("hello")
end)
-- Removes the task before it has a chance to run
t:stop()
```
## Groups
Coil provides the ability to create task groups; these are objects which can
have tasks added to them, and which are in charge of updating and handling
their contained tasks. A group is created by calling the `coil.group()`
function.
```lua
local group = coil.group()
```
Once a group is created it acts independently of the `coil` object, and must
be updated each frame using its own update method.
```lua
group:update(deltatime)
```
To add a task to a group, the group's `add()` method should be used.
```lua
group:add(function()
coil.wait(10)
print("10 seconds have passed")
end)
```
A good example of where groups are useful is for games where you may have a set
of tasks which effect objects in the game world and which you want to pause
when the game is paused. A group's tasks can be paused by simply neglecting
to call its `update()` method; when a group is destroyed its tasks are also
destroyed.
## License
This library is free software; you can redistribute it and/or modify it under
the terms of the MIT license. See [LICENSE](LICENSE) for details.
|
