.TH tco_go 3 2025-02-06
.SH NAME
tco_go, tco_args, tco_yield
.SH LIBRARY
Tiny Coroutines
.RI ( libtco ", " \-ltco )
.SH SYNOPSIS
.nf
.B #include <tco.h>
.P
.BI "int tco_go(void (*" f ")(...));"
.B "int tco_args(...);"
.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
.B coroutine
macro is provided as a convenient way to use the
.BR gcc (1)/ clang (1)
.B noinline
attribute, and to communicate the intended 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_args ()
sets the function arguments given to the coroutine spawned by
.BR tco_go ().
.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.
.P
The implementation is incompatible with control flow protection mechanisms such
as shadow stacks as it relies on manipulating return addresses.
.P
.BR tco_args ()
currently only supports arguments passed by registers
.RI ( %rdi ", " %rsi ", " %rdx ", " %r10 ", " %r8 ", " %r9 " and " %xmm0-8 ).
Spawning coroutines that take arguments on the stack will result in stack
corruption.
Refer to the System V ABI for more details.
.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/>.