lco/README

Copyright (C) 2018 Ariadne Devos

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.

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.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

# What is lco?

lco, short for lightweight coroutine. It's not *just another* coroutine
library for C, it is intended to make them as lightweight as possible.
Typically, a C thread has a single call stack. When using coroutines, however,
one can create a new stacks to switch to, and switch back later - or not at
all.

What makes lco different, or, what will make lco different (as we aren't there
yet), is that it performs a statical analysis of the code to determine an upper
bound on how much stack the program will need. So you know aforehand how much
memory your coroutine will consume (not counting dynamic memory allocation
made by the code).

In principle, lco is architecture-independent. It is not OS-independent; I do
not expect it to be fully ported to Microsoft Windows (syscalls might be
difficult).

Dynamical linking is not expected to become a problem.

# How to use?

Edit the Makefile to change ARCH into your architecture, then do 'make test'.
There are now three files of interest: the object files lco-x86-64.o and lco.o
and a header lco.h. As of now, lco.h is the documentation.

# Why all this effort to minimise stack sizes?

If less memory is reserved for the program, the computer needs less RAM and can
therefore be less costly. But we can't just choose a stack size and stick to it,
as some programs need much more than others. We have to perform some analysis,
preferably in an automated fashion.

# Supported platforms

x86-64 Linux (doesn't require redzone)

The BSDs shouldn't require much change.

Non-linux systems might not like the way the stack pointer is manipulated.

# Support

If there is some reason for contacting lco's maintainer, see process/contact.md.

For a list of known bugs, see process/bugs.md.

lco will have a website at
<https://ipfs.io/ipns/QmXikbcdm5uhLEiUzhqvgRP8QQvJ5WX9GwFqti849wKrLw/>.

lco has a public git repository at
<https://notabug.org/ariadne/lco>.