tco_go.3


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

.TH tco_go 3 2025-02-06
.SH NAME
tco_go, tco_yield
.SH LIBRARY
Tiny Coroutines
.RI ( libtco ", " \-ltco )
.SH SYNOPSIS
.nf
.B #include <tco.h>
.P
.BI "int tco_go(void (*f)(void));"
.BI "void tco_yield(void);"
.fi
.SH DESCRIPTION
.BR tco_go ()
spawns a coroutine context with its own stack, then saves the current execution
context and switches to the new coroutine.
The coroutine function pointer
.I f
is required to not be inlined
(the
.BR coroutine
macro is provided as a convienient way to use the
.BR gcc (1)
/
.BR clang (1)
.BR noinline
attribute, and to communicate the intented use of a function as a coroutine).
When the scheduler switches back to a context that has called
.BR tco_go (),
it resumes execution from after that call.
.P
.BR tco_yield ()
saves the current execution context and switches to the next scheduled context,
pausing execution of the current coroutine.
Tasks are scheduled in a round-robin fashion.
.P
Functions scheduled as coroutines are automatically deinitialised when they
return.
.SH RETURN VALUE
.BR tco_go ()
returns 0 on success, and a non-zero error code when the coroutine fails to
initialise.
.SH CAVEATS
This library works by preserving the state of the callee-saved registers and
restoring them later when the coroutine is resumed. This approach may be
incompatible with other forms of black magic voodoo, your mileage may vary.
.SH AUTHOR AND LICENSE
Copyright (C) 2025 Aiden Gall
.P
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
.P
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.P
You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.