856 lines25.8 KB

Newer

Older

Markdown Text Raw Blame

9 months ago	Update readme	26	1	Stackful coroutines in C.
9 months ago	Documentation started	17	2
9 months ago	Split down into component parts	37	3	* `Task` & `Future` coroutines which can pause, waiting for a future.
9 months ago	Split down into component parts	37	4	* `ASleep` an example of pausing `Task`s using `Future`s.
9 months ago	Update readme	26	5	* `Generator` coroutines used as generators for loops.
9 months ago	Split down into component parts	37	6	* `Coroutine` the base coroutine engine.
9 months ago	Documentation started	17	7
9 months ago	Split down into component parts	37	8	Your code doesn't need to do anything special to be a coroutine. Only standard, or commonly available libraries are needed.
9 months ago	Documentation started	17	9
9 months ago	Update readme	26	10	## Prerequisites
9 months ago	Documentation started	17	11
9 months ago	Split down into component parts	37	12	These libraries rely on as much as possible on C's cross-platform comfort zone. C's standard libraries are used as far as possible, but, as `threads.h` is not usually supported, `pthread.h` has been used instead.
9 months ago	Documentation started	17	13
9 months ago	Split down into component parts	37	14	You will need to build & link the code, `coroutine/.c`, as part of your system, and ensure the headers, `include/`, are available on your include path.
9 months ago	Documentation started	17	15
9 months ago	Update readme	26	16	## Quick Start
9 months ago	Documentation started	17	17
9 months ago	Split down into component parts	37	18	### Tasks
9 months ago	Documentation started	17	19
9 months ago	Split down into component parts	37	20	To run `Task`s:
9 months ago	Documentation started	17	21
9 months ago	All code blocks language-tagged	39	22	#!C
9 months ago	Split down into component parts	37	23	#include "coroutine.h"
9 months ago	Split down into component parts	37	24	#include "task.h"
9 months ago	Update readme	26	25	main(){
9 months ago	Split down into component parts	37	26	Coroutine_StartSystem();
9 months ago	Update readme	26	27	void *res = NULL;
9 months ago	Split down into component parts	37	28	bool canceled = Task_Run(maintask, &param, &res);
9 months ago	Split down into component parts	37	29	Coroutine_StopSystem();
9 months ago	Update readme	26	30	}
9 months ago	Update readme	26	31
9 months ago	Split down into component parts	37	32	`Task_Run` runs tasks, switching between them when the current task waits on an `Future`. `maintask()` is run as a task. The start function for any task looks like this:
9 months ago	Update readme	26	33
9 months ago	All code blocks language-tagged	39	34	#!C
9 months ago	Update readme	26	35	bool mytask(void param, void *res){
			36
			37	// do your thing here
			38
			39	return canceled;
			40	}
			41
			42	When `Task` returns from its start function, it returns whether it was canceled. Canceled `Task`s are assumed to have not finished what they were doing.
			43
9 months ago	Split down into component parts	37	44	Within your main task, create `Task`s and `Task_Await()` them when you want to wait for their result:
9 months ago	Update readme	26	45
9 months ago	All code blocks language-tagged	39	46	#!C
9 months ago	Split down into component parts	37	47	Task task1;
9 months ago	Split down into component parts	37	48	Task_ctor(&task1, adifferenttask, &task1param);
9 months ago	Update readme	26	49
9 months ago	Update readme	26	50	void *result;
9 months ago	Split down into component parts	37	51	bool canceled = Task_Await(&task1, &result);
9 months ago	Update readme	26	52
9 months ago	Split down into component parts	37	53	Task_dtor(&task1);
9 months ago	Update readme	26	54
			55	// use the result
			56
			57	When a task needs to wait for something, and wants to allow other tasks to run, it should use a `Future`:
			58
9 months ago	All code blocks language-tagged	39	59	#!C
9 months ago	Split down into component parts	37	60	Future future;
9 months ago	Split down into component parts	37	61	Future_ctor(&future);
9 months ago	Update readme	26	62
			63	// pass the future to the background-thing-which-might-take-a-while
			64
9 months ago	Documentation experiment	27	65	void *res;
9 months ago	Split down into component parts	37	66	bool canceled = Future_Await(&future, &res);
9 months ago	Update readme	26	67
9 months ago	Split down into component parts	37	68	Future_dtor(&future);
9 months ago	Update readme	26	69
			70	When the background-thing-which-might-take-a-while has a result:
			71
9 months ago	All code blocks language-tagged	39	72	#!C
9 months ago	Split down into component parts	37	73	Future_SetResult(future, false, result);
9 months ago	Update readme	26	74
9 months ago	Split down into component parts	37	75	### ASleep
			76
			77	`ASleep()` needs its own system to be started to work:
			78
9 months ago	All code blocks language-tagged	39	79	#!C
9 months ago	Split down into component parts	37	80	ASleep_StartSystem()
			81	Coroutine_StartSystem();
			82	// Run tasks here which may now use ASLeep()
			83	Coroutine_StopSystem();
			84	ASleep_StopSystem();
			85
			86	Note that `ASleep_StartSystem()` / `ASleep_StopSystem()` is only needed once per process, whereas `Coroutine_StartSystem()` / `Coroutine_StopSystem()` is needed on each thread where coroutines are used.
			87
			88	Sleeping in a task:
			89
9 months ago	All code blocks language-tagged	39	90	#!C
9 months ago	Split down into component parts	37	91	bool mytask(void param, void *result){
			92	..
			93	ASleep(time_to_sleep);
			94	..
			95	}
			96
9 months ago	Update readme	26	97	### Generators
9 months ago	Update readme	26	98
9 months ago	Split down into component parts	37	99	The coroutine system needs to be started:
9 months ago	Update readme	26	100
9 months ago	All code blocks language-tagged	39	101	#!C
9 months ago	Split down into component parts	37	102	Coroutine_StartSYstem();
			103	// you can use generators now
			104	Coroutine_StopSystem();
			105
			106	Note that you need to start the coroutine system on each thread you want to use them.
			107
9 months ago	Update readme	26	108	You will need a generator function:
9 months ago	Update readme	26	109
9 months ago	Tag C fragment as C	38	110	#!C
9 months ago	Update readme	26	111	void yield_my_things(void param){
			112	bool domore = true;
			113
			114	// loop/call functions to find more values to yield, and when you have one:
			115	domore = Generator_Yield(thing);
			116	// .. if domore is false, exit your generator - it is being destructed
			117
			118	// not actually used by generators, but this is a useful convention for bubbling
			119	// the flag out to calling functions.
			120	return (void *)domore;
			121	}
			122
			123	And to use it:
			124
9 months ago	All code blocks language-tagged	39	125	#!C
9 months ago	Update readme	26	126	Generator gen;
			127	Generator_ctor(&gen, yield_my_things, "..");
			128	void *thing;
			129	while(Generator_Next(&gen, &thing)){
			130	// use thing - a value yielded by your generator
			131	}
			132	Generator_dtor(&gen);
			133
			134	### Coroutines
			135
			136	While you can use coroutines directly, it's designed as a system to support more useful patterns, like `Async` and `Generators`.
			137
			138	The Coroutines system must be started:
			139
9 months ago	All code blocks language-tagged	39	140	#!C
9 months ago	Update readme	26	141	Coroutine_StartSystem();
			142	// use coroutines here
			143	Coroutine_StopSystem();
			144
			145	Your coroutine will need to have a start function:
			146
9 months ago	All code blocks language-tagged	39	147	#!C
9 months ago	Update readme	26	148	void start(void param){
			149	...
			150	}
			151
			152	When there is no coroutine running, start your 'main' coroutine:
			153
9 months ago	All code blocks language-tagged	39	154	#!C
9 months ago	Update readme	26	155	void *result = Coroutine_Run(comain, param);
			156
			157	Create other coroutines like this:
			158
9 months ago	All code blocks language-tagged	39	159	#!C
9 months ago	Update readme	26	160	Coroutine *cor = Coroutine_New(start);
			161
			162	When you want a Coroutine to run, or to return from a yield:
			163
9 months ago	All code blocks language-tagged	39	164	#!C
9 months ago	Update readme	26	165	Coroutine_Continue(cor, value, run_early);
			166
			167	`value` will be start function's parameter, or the value returned from the yield.
			168
			169	Within the Coroutine, to yield a value:
			170
9 months ago	All code blocks language-tagged	39	171	#!C
9 months ago	Update readme	26	172	void Coroutine_Yield(value, on_yield, void me);
			173
			174	The on_yield function is called after the coroutine has been 'wait'ed, but before the next coroutine is resumed.
			175
			176	## How it Works
			177
9 months ago	Split down into component parts	37	178	The coroutine system uses the stack divided into smaller stacks for the coroutines. This means you may need to consider whether the coroutine stack size, set by `COROUTINE_STARTUP_STACK_SIZE`, is right for your application, and whether your stack size is enough for the number of coroutines you might run.
9 months ago	Update readme	26	179
9 months ago	Documentation moderately done	36	180	Each of your threads has its own stack - the coroutine system can be run (or not) independantly on each thread. For some special cases, you may want to adjust each of your thread's stack sizes depending on how it is used.
9 months ago	Update readme	26	181
			182	## Style
			183
9 months ago	Split down into component parts	37	184	The style is influenced by C++. For example, where possible, a `Something Something_New(a, b, c)` and `Something_Delete(Something )` will have corresponding `Somthing_ctor(Somthing , a, b, c)` and `Something_dtor(Something )` to initialise and finalise a `Something` on the stack, or within another object. Using `.._ctor()` and `.._dtor()` will be faster as they avoid the `malloc()` and `free()`.
9 months ago	Documentation started	17	185
9 months ago	All code blocks language-tagged	39	186	#!C
9 months ago	Documentation started	17	187	Something *oneofthem = Something_New();
			188	// use oneofthem
			189	Something_Delete(oneofthem);
			190
			191	Can be also be done like this, and this will run faster:
			192
9 months ago	All code blocks language-tagged	39	193	#!C
9 months ago	Documentation started	17	194	Something oneofthem;
			195	Something_ctor(&oneofthem);
			196	// use oneofthem
			197	Something_dtor(&oneofthem);
			198
9 months ago	Update readme	26	199	The exception is `Coroutine_New()` and `Coroutine_Delete()`. The returned `Coroutine` is somewhere on your thread's stack - its memory is managed by the coroutine system, and is allocated and freed quickly.
9 months ago	Update readme	26	200
9 months ago	Documentation started	17	201	## Usage
			202
			203	When you are using coroutines or generators:
			204
9 months ago	All code blocks language-tagged	39	205	#!C
9 months ago	Documentation started	17	206	void myfunc(void ){
			207	// your function here
			208	}
			209
			210	Coroutine_StartSystem();
			211	Coroutine_Run(myfunc, (void *)myparam);
			212	Coroutine_StopSystem();
			213
9 months ago	Split down into component parts	37	214	While the system is started, you can make many calls to `Coroutine_Run()` or `Task_Run()`, but only one of them can be running at once. A running system is thread local - each thread you want to use coroutines on will need to be `Coroutine_StartSystem()`ed.
9 months ago	Documentation started	17	215
9 months ago	Documentation experiment	27	216	## Stack Overruns
9 months ago	Documentation started	17	217
9 months ago	Documentation experiment	27	218	The C stack is divided down into smaller stacks. There's one to give some work room between `..StartSystem()` and `..Run()`, and one for each coroutine. These have guard markers which are checked to see if the stack has overrun. If there is a stack overrun, the system cannot continue - a message is output and the programe exited. There's a number of ways to avoid this issue:
9 months ago	Documentation started	17	219
9 months ago	Documentation experiment	27	220	* Use less stack. This is, sometimes, the right advice, especially if the startup stack overrins. The expectation is that very little is done between `.._StartSystem()` and `..Run()`. If your situation needs more doing, you can...
			221
			222	* increase the stack size. Adjust `COROUTINE_STACK_SIZE` (for startup) or `COROUTINE_STARTUP_STACK_SIZE` (for coroutines) as appropriate. If your use case is even more demanding, such as if you want 1000s of coroutines (so you need small stack chunks), /and/ some of them can recurse an unknown amount (so you need a deep stack for that coroutine), then you can...
			223
			224	* monitor stack headroom, and add another stack chunk if you need to:
			225
			226	In this last case you'll need to add some code at key points:
			227
9 months ago	All code blocks language-tagged	39	228	#!C
9 months ago	Documentation experiment	27	229	void myfunction(void param){
			230	if (Coroutine_GetStackHeadroom() < MIN_ALLOWED_STACK){
			231	return Coroutine_Chain(myfunction, param);
			232	}
			233	// do everything normally
			234	}
			235
			236	More realistically:
			237
9 months ago	All code blocks language-tagged	39	238	#!C
9 months ago	Documentation experiment	27	239	struct myfunctionparams {
			240	int a;
			241	char *b;
			242	struct dog *d;
			243	}
			244
			245	void mychain(void param){
			246	struct myfunctionparams myparams = (struct myfunctionparams )params;
			247	return (void )myfunction(myparams->a, myparams->b, myparams->d);
			248	}
			249
			250	int myfunction(int a, char *b, struct dog d){
			251	if (Coroutine_GetStackHeadroom() < MIN_ALLOWED_STACK){
			252	struct myfunctionparams params = {
			253	a,
			254	b,
			255	&d
			256	};
			257	return (int)Coroutine_Chain(mychain, &params);
			258	}
			259	}
			260
9 months ago	Documentation moderately done	36	261	And if you want to panic if the C stack overruns:
9 months ago	Documentation moderately done	36	262
9 months ago	All code blocks language-tagged	39	263	#!C
9 months ago	Documentation moderately done	36	264	if (Coroutine_GetStackHeadroom() < MIN_ALLOWED_COROUTINE_STACK){
			265	if (Coroutine_HasCoroutinesInFreePool() \|\|
			266	(char *)Coroutine_GetCStackTop() - c_stack_end >= MIN_ALLOWED_C_STACK) {
			267	struct myfunctionparams params = {
			268	a,
			269	b,
			270	&d
			271	};
			272	return (int)Coroutine_Chain(mychain, &params);
			273	}
			274	// panic now
			275	}
			276
9 months ago	Update readme	26	277	# API
9 months ago	Documentation started	17	278
9 months ago	Split down into component parts	37	279	## Task & Future
9 months ago	Documentation experiment	27	280
			281	The pattern for using async is:
			282
9 months ago	All code blocks language-tagged	39	283	#!C
9 months ago	Split down into component parts	37	284	bool mymaintask(void param, void *result){
9 months ago	Split down into component parts	37	285	// do your main task things here, like starting more tasks
9 months ago	Documentation experiment	27	286	}
9 months ago	Documentation experiment	27	287
9 months ago	Split down into component parts	37	288	Coroutine_StartSystem();
9 months ago	Documentation experiment	27	289	void *res = NULL;
9 months ago	Split down into component parts	37	290	bool canceled = Task_Run(mymaintask, NULL, &res);
9 months ago	Split down into component parts	37	291	Coroutine_StopSystem();
9 months ago	Documentation experiment	27	292
9 months ago	Split down into component parts	37	293	To create and wait for a task:
9 months ago	Documentation experiment	27	294
9 months ago	All code blocks language-tagged	39	295	#!C
9 months ago	Split down into component parts	37	296	Task task1;
9 months ago	Split down into component parts	37	297	Task_ctor(&task1, asynctask1, &task1param);
9 months ago	Documentation experiment	27	298	void *res = NULL;
9 months ago	Split down into component parts	37	299	bool canceled = Task_Await(&task1, void **res)
9 months ago	Split down into component parts	37	300	Task_dtor(&task1);
9 months ago	Documentation experiment	27	301
			302	or, if you prefer new & delete:
			303
9 months ago	All code blocks language-tagged	39	304	#!C
9 months ago	Split down into component parts	37	305	Task *task1 = Task_New(asynctask1, &task1param);
9 months ago	Documentation experiment	27	306	void *res = NULL;
9 months ago	Split down into component parts	37	307	bool canceled = Task_Await(task1, void **res)
9 months ago	Split down into component parts	37	308	Task_Delete(task1);
9 months ago	Documentation experiment	27	309
			310	Inside your task, when there is something to wait for and you want other tasks to run while your task is waiting, you will need a future:
			311
9 months ago	All code blocks language-tagged	39	312	#!C
9 months ago	Split down into component parts	37	313	Future future;
9 months ago	Split down into component parts	37	314	Future_ctor(&future);
9 months ago	Documentation experiment	27	315
9 months ago	Documentation experiment	27	316	// keep &future to hand for when the background thing completes
9 months ago	Split down into component parts	37	317	bool canceled = Future_Await(&future, NULL);
9 months ago	Documentation experiment	27	318
9 months ago	Split down into component parts	37	319	Future_dtor(&future);
9 months ago	Documentation experiment	27	320
9 months ago	Split down into component parts	37	321	`Future_New()` and `Future_Delete()` are also available if you prefer that style.
9 months ago	Documentation experiment	27	322
			323	Inside the callback when the background thing is complete:
			324
9 months ago	All code blocks language-tagged	39	325	#!C
9 months ago	Documentation experiment	27	326	// result is a void *
9 months ago	Split down into component parts	37	327	Future_SetResult(future, result, false);
9 months ago	Documentation experiment	27	328
			329	or, if something went wrong:
			330
9 months ago	All code blocks language-tagged	39	331	#!C
9 months ago	Documentation experiment	27	332	// exception is a void *
9 months ago	Split down into component parts	37	333	Future_SetResult(future, exception, true);
9 months ago	Documentation experiment	27	334
			335	Back in the task, you can respond to the future:
			336
9 months ago	All code blocks language-tagged	39	337	#!C
9 months ago	Split down into component parts	37	338	... Future_Await has returned
9 months ago	Documentation experiment	27	339	if (canceled){
			340	// exit quickly - you've been canceled
			341	// you could, for example, use the future's result as an exception, or error code here
			342	}
			343	// carry on - the future's result may be an actual result, that's up to you
			344
			345
9 months ago	Split down into component parts	37	346	##### void Future_ctor(Future *fut)
9 months ago	Documentation experiment	27	347
9 months ago	Documentation experiment again	28	348	fut
9 months ago	Split down into component parts	37	349	: The `Future` being constructed
9 months ago	Documentation experiment again	28	350
9 months ago	Split down into component parts	37	351	Initialise a future. When you no longer need it, use `Future_dtor()`.
9 months ago	Documentation experiment	27	352
9 months ago	Split down into component parts	37	353	##### Future *Future_New()
9 months ago	Documentation experiment	27	354
9 months ago	Documentation experiment again	29	355	(returns)
9 months ago	Documentation experiment again	28	356	: The new future
9 months ago	Documentation experiment	27	357
9 months ago	Split down into component parts	37	358	Allocates and initialises a future, When you no longer need it, use `Future_Delete()`.
9 months ago	Documentation experiment	27	359
9 months ago	Split down into component parts	37	360	##### void Future_dtor(Future *fut)
9 months ago	Documentation experiment	27	361
9 months ago	Documentation experiment	27	362	fut
9 months ago	Split down into component parts	37	363	: The `Future` being destructed
9 months ago	Documentation experiment	27	364
9 months ago	Split down into component parts	37	365	Destruct a future previously constructed with `Future_ctor()`.
9 months ago	Documentation experiment	27	366
9 months ago	Split down into component parts	37	367	##### void Future_Delete(Future *fut)
9 months ago	Documentation experiment	27	368
9 months ago	Documentation WIP	31	369	fut
9 months ago	Split down into component parts	37	370	: The `Future` to be destructed and freed
9 months ago	Documentation WIP	31	371
9 months ago	Split down into component parts	37	372	Delete (finalise and free) a future previously new'ed with `Future_New()`
9 months ago	Documentation experiment	27	373
9 months ago	Split down into component parts	37	374	##### void Future_SetResult(Future fut, bool canceled, void value)
9 months ago	Documentation experiment	27	375
9 months ago	Documentation WIP	31	376	fut
9 months ago	Split down into component parts	37	377	: The `Future` whose result is being set
9 months ago	Documentation experiment	27	378
9 months ago	Documentation WIP	31	379	canceled
9 months ago	Documentation WIP	31	380	: The future's `canceled` setting
9 months ago	Documentation experiment	27	381
9 months ago	Documentation WIP	31	382	value
9 months ago	Split down into component parts	37	383	: The future's result `value`
9 months ago	Documentation experiment	27	384
9 months ago	Split down into component parts	37	385	Set the result of a future. This has an effect only the first time its done, ie a completed future can't be canceled and a canceled future can't be completed. When an `Future` has a result, its watchers are called back.
9 months ago	Documentation experiment	27	386
9 months ago	Documentation WIP	31	387	The `value` of a future might be a result if the future completes (when `canceled == false`), or could be some sort of exception value if `canceled == true`. The interpretation of a future's `value` is up to the user - as far as the async system is concerned, it's only a `void *`.
9 months ago	Documentation experiment	27	388
9 months ago	Split down into component parts	37	389	##### bool Future_GetResult(Future fut, void *res)
9 months ago	Documentation experiment	27	390
9 months ago	Documentation WIP	31	391	(returns)
9 months ago	Split down into component parts	37	392	: The `canceled` value of the `Future`.
9 months ago	Documentation experiment	27	393
9 months ago	Documentation WIP	31	394	res
9 months ago	Split down into component parts	37	395	: Where to store the value of the `Future`. This may be `NULL`.
9 months ago	Documentation experiment	27	396
9 months ago	Documentation WIP	31	397	Get the result of a future.
9 months ago	Documentation experiment	27	398
9 months ago	Split down into component parts	37	399	##### typedef void (Future_Watcher)(void me, Future *fut)
9 months ago	Documentation experiment	27	400
9 months ago	Split down into component parts	37	401	A `Future_Watcher` is a callback called when a future has a result. The `me` parameter is the one passed to `Future_AddWatcher()`. `fut` is the future which has just got its result.
9 months ago	Documentation experiment	27	402
9 months ago	Split down into component parts	37	403	##### void Future_AddWatcher(Future fut, Future_Watcher watcher, void me)
9 months ago	Documentation experiment	27	404
9 months ago	Documentation WIP	31	405	fut
9 months ago	Split down into component parts	37	406	: the `Future` to add a watcher to
9 months ago	Documentation WIP	31	407
9 months ago	Documentation WIP	31	408	watcher
9 months ago	Split down into component parts	37	409	: the callback to call when the `Future` has a result.
9 months ago	Documentation WIP	31	410
			411	me
			412	: the `me` value to pass to `watcher` when it is called back.
			413
			414	Add a watcher (callback) to be called when the future has a result. If the future is already complete, `watcher` is immediately called. The `me` value is passed to the watcher as its `me` parameter. It is assumed that a watcher, identified by the `(watcher, me)` pair, will only be added once.
			415
9 months ago	Split down into component parts	37	416	##### void Future_RemoveWatcher(Future fut, Future_Watcher watcher, void me)
9 months ago	Documentation WIP	31	417
9 months ago	Documentation WIP	31	418	fut
9 months ago	Split down into component parts	37	419	: the `Future` to remove a watcher from
9 months ago	Documentation WIP	31	420
			421	watcher
			422	: the callback of the watcher to remove.
			423
			424	me
			425	: the `me` value of the watcher to remove.
			426
			427	Remove a watcher from a future. It is not an error if no watcher matching `(watcher, me)` is found - it has probably already been called back.
			428
9 months ago	Split down into component parts	37	429	##### bool Future_Await(Future fut, void *res)
9 months ago	Documentation WIP	31	430
9 months ago	Documentation WIP	31	431	(returns)
9 months ago	Split down into component parts	37	432	: whether the `Future` was canceled.
9 months ago	Documentation WIP	31	433
9 months ago	Documentation WIP	31	434	fut
9 months ago	Split down into component parts	37	435	: The `Future` to wait for.
9 months ago	Documentation WIP	31	436
			437	res
			438	: Where to store the `value` of the future when it is has a result. May be `NULL`.
			439
9 months ago	Split down into component parts	37	440	The current `Task` is paused until the `Future` has a result. Other `Task`s are run while this one is waiting.
9 months ago	Documentation WIP	31	441
9 months ago	Split down into component parts	37	442	##### typedef bool (Task_Entry)(void param, void **res)
9 months ago	Documentation WIP	31	443
9 months ago	Split down into component parts	37	444	The entry function to an `Task`.
9 months ago	Documentation WIP	33	445
9 months ago	Split down into component parts	37	446	##### void Task_ctor(Task tsk, Task_Entry entry, void param)
9 months ago	Documentation WIP	33	447
			448	tsk
			449	: The task to construct.
			450
			451	entry
			452	: The entry function for the task.
			453
			454	param
			455	: The value for `param` to pass to `entry`.
			456
9 months ago	Split down into component parts	37	457	Initialises an `Task`. When you have finished with an `Task` you must finalise it using `Task_dtor()`
9 months ago	Documentation WIP	33	458
9 months ago	All code blocks language-tagged	39	459	#!C
9 months ago	Split down into component parts	37	460	Task tsk;
9 months ago	Split down into component parts	37	461	Task_ctor(&tsk, mytask, myparam);
9 months ago	Documentation WIP	33	462	// tsk will run if you wait for a task or future
9 months ago	Split down into component parts	37	463	Task_Await(&tsk, NULL);
9 months ago	Split down into component parts	37	464	Task_dtor(&tsk);
9 months ago	Documentation WIP	33	465
9 months ago	Split down into component parts	37	466	##### Task Task_New(Task_Entry entry, void param)
9 months ago	Documentation WIP	33	467
9 months ago	Documentation WIP	33	468	(returns)
9 months ago	Split down into component parts	37	469	: The new `Task`.
9 months ago	Documentation WIP	33	470
			471	entry
			472	: The entry function for the task.
			473
			474	param
			475	: The value for `param` to pass to `entry`.
			476
9 months ago	Split down into component parts	37	477	This allocates and initialises a new `Task`. When you have finished with your task, you must `Task_Delete()` it.
9 months ago	Documentation WIP	33	478
9 months ago	All code blocks language-tagged	39	479	#!C
9 months ago	Split down into component parts	37	480	Task *tsk = Task_New(mytask, myparam);
9 months ago	Documentation WIP	33	481	// tsk will run if you wait for a task or future
9 months ago	Split down into component parts	37	482	Task_Await(tsk, NULL);
9 months ago	Split down into component parts	37	483	Task_Delete(tsk);
9 months ago	Documentation WIP	33	484
9 months ago	Split down into component parts	37	485	##### void Task_dtor(Task *tsk)
9 months ago	Documentation WIP	33	486
9 months ago	Documentation WIP	33	487	tsk
9 months ago	Split down into component parts	37	488	: The `Task` to destruct.
9 months ago	Documentation WIP	33	489
9 months ago	Split down into component parts	37	490	This finalises an `Task` you ealier initalised with `Task_ctor()`. It is an error to attempt to destruct a task which is running.
9 months ago	Documentation WIP	33	491
9 months ago	All code blocks language-tagged	39	492	#!C
9 months ago	Split down into component parts	37	493	Task tsk;
9 months ago	Split down into component parts	37	494	Task_ctor(&tsk, mytask, myparam);
9 months ago	Documentation WIP	33	495	// use tsk
9 months ago	Split down into component parts	37	496	Task_dtor(&tsk);
9 months ago	Documentation WIP	33	497
9 months ago	Split down into component parts	37	498	##### void Task_Delete(Task *tsk)
9 months ago	Documentation WIP	33	499
9 months ago	Documentation WIP	33	500	tsk
9 months ago	Split down into component parts	37	501	: The `Task` to delete.
9 months ago	Documentation WIP	33	502
9 months ago	Split down into component parts	37	503	This finalises and frees an `Task` you ealier new'ed with `Task_New()`. It is an error to attempt to delete a task which is running.
9 months ago	Documentation WIP	33	504
9 months ago	All code blocks language-tagged	39	505	#!C
9 months ago	Split down into component parts	37	506	Task *tsk = Task_New(mytask, myparam);
9 months ago	Documentation WIP	33	507	// use tsk
9 months ago	Split down into component parts	37	508	Task_Delete(tsk);
9 months ago	Documentation WIP	33	509
9 months ago	Split down into component parts	37	510	##### static inline bool Task_Await(Task tsk, void *res)
9 months ago	Documentation WIP	33	511
			512	(returns)
			513	: Whether the task was canceled.
			514
			515	tsk
9 months ago	Split down into component parts	37	516	: The `Task` to wait for.
9 months ago	Documentation WIP	33	517
9 months ago	Documentation WIP	33	518	res
9 months ago	Split down into component parts	37	519	: Where to store the `Task`'s value when it finishes. This may be NULL.
9 months ago	Documentation WIP	33	520
9 months ago	Split down into component parts	37	521	The current `Task` waits for `tsk` to finish, and returns the result.
9 months ago	Documentation WIP	33	522
9 months ago	Split down into component parts	37	523	##### void Task_Cancel(Task tsk, void cancel_value)
9 months ago	Documentation WIP	33	524
			525	tsk
			526	: The task to cancel.
			527
			528	cancel_value
			529	: The value to set on any future this task waits on.
			530
			531	This marks a task as canceled. When that task waits on a future that future will be canceled too, using `cancel_value`.
			532
9 months ago	Split down into component parts	37	533	##### static inline bool Task_IsCanceled(Task *tsk)
9 months ago	Documentation WIP	33	534
			535	(returns)
			536	: Whether the task is canceled.
			537
			538	tsk
			539	: The task to get its canceled setting from.
			540
9 months ago	Split down into component parts	37	541	##### static inline Future Task_GetAwaitedFuture(Task tsk)
9 months ago	Documentation WIP	31	542
9 months ago	Documentation WIP	33	543	(returns)
			544	: The future the task is waiting on. May be NULL.
			545
			546	tsk
			547	: Teh task to read the future it is waiting on.
			548
			549	Return the future a task is waiting on.
			550
9 months ago	Split down into component parts	37	551	##### bool Task_Run(Task_Entry start, void value, void *res)
9 months ago	Documentation WIP	33	552
9 months ago	Documentation WIP	33	553	(returns)
9 months ago	Split down into component parts	37	554	: Whether `start` was canceled.
9 months ago	Documentation WIP	33	555
9 months ago	Split down into component parts	37	556	start
9 months ago	Split down into component parts	37	557	: The function to use as the main task.
9 months ago	Documentation WIP	33	558
9 months ago	Documentation WIP	33	559	value
9 months ago	Split down into component parts	37	560	: The value to pass to `start`.
9 months ago	Documentation WIP	33	561
9 months ago	Split down into component parts	37	562	res
9 months ago	Split down into component parts	37	563	: Where to store the result of `start`.
9 months ago	Documentation WIP	33	564
9 months ago	Split down into component parts	37	565	Runs `start` as an `Task`. When `start` returns all other tasks must have been destructed, using `Task_dtor()` or `Task_Delete()`.
9 months ago	Documentation WIP	33	566
9 months ago	Split down into component parts	37	567	## ASleep
9 months ago	Documentation WIP	33	568
9 months ago	Split down into component parts	37	569	##### void ASleep_StartSystem()
9 months ago	Documentation WIP	33	570
9 months ago	Split down into component parts	37	571	You must start the `ASleep` system to use it. This needs to happen per process (whereas `Coroutine_StartSystem()` needs to happen per-thread). Once you've finished with `ASleep` you must `ASleep_StopSystem()`.
9 months ago	Documentation WIP	33	572
9 months ago	All code blocks language-tagged	39	573	#!C
9 months ago	Split down into component parts	37	574	ASleep_StartSystem();
			575	// Now you can use ASleep() on any thread
			576	ASleep_StopSystem();
9 months ago	Documentation WIP	33	577
9 months ago	Split down into component parts	37	578	##### void ASleep_StopSystem()
9 months ago	Documentation WIP	33	579
9 months ago	Split down into component parts	37	580	Call this to stop the `ASleep` system.
9 months ago	Documentation WIP	33	581
9 months ago	Split down into component parts	37	582	##### bool ASleep(float delay, void **value)
9 months ago	Documentation WIP	33	583
9 months ago	Split down into component parts	37	584	(returns)
9 months ago	Split down into component parts	37	585	: Whether the task was canceled.
9 months ago	Documentation WIP	33	586
9 months ago	Split down into component parts	37	587	delay
9 months ago	Split down into component parts	37	588	: How many seconds to delay for.
9 months ago	Documentation WIP	31	589
9 months ago	Split down into component parts	37	590	value
9 months ago	Split down into component parts	37	591	: Where to store the cancellation value. This may be NULL.
9 months ago	Documentation WIP	31	592
9 months ago	Split down into component parts	37	593	Sleep for `delay` seconds. `*value` will be set to `NULL` if the sleep is successful, and the `cancel_value` if the task is canceled.
9 months ago	Documentation WIP	33	594
9 months ago	Update readme	26	595	## Generator
9 months ago	Documentation started	17	596
9 months ago	Update readme	26	597	The pattern for a `Generator` is:
9 months ago	Update readme	26	598
9 months ago	Documentation WIP	35	599	#### A loop which uses the `Generator
9 months ago	Update readme	26	600
9 months ago	All code blocks language-tagged	39	601	#!C
9 months ago	Documentation started	17	602	Generator gen;
9 months ago	Update readme	26	603	Generator_ctor(&gen, mygen, &param);
9 months ago	Documentation started	17	604
9 months ago	Update readme	26	605	void *value;
			606	while(Generator_Next(&gen, &value)){
			607	// use value here
9 months ago	Documentation started	17	608	}
9 months ago	Update readme	26	609	// value is now the return value from the Generator
9 months ago	Update readme	26	610
9 months ago	Documentation started	17	611	Generator_dtor(&gen);
9 months ago	Documentation started	17	612
9 months ago	Update readme	26	613	Or:
9 months ago	Documentation started	17	614
9 months ago	All code blocks language-tagged	39	615	#!C
9 months ago	Update readme	26	616	Generator *gen = Generator_New(mygen, &param);
9 months ago	Documentation started	17	617
9 months ago	Update readme	26	618	void *value;
			619	while(Generator_Next(gen, &value)){
			620	// use value here
			621	}
9 months ago	Documentation started	17	622
9 months ago	Update readme	26	623	Generator_Delete(gen);
9 months ago	Documentation started	17	624
9 months ago	Update readme	26	625	`Generator`s yield a series of `void `s - what the `void `s mean is up to you. `Generator_Next()` returns a `bool` to indicate whether the `Generator` has finished.
9 months ago	Documentation started	17	626
9 months ago	Update readme	26	627	#### A generator function
9 months ago	Documentation started	17	628
9 months ago	All code blocks language-tagged	39	629	#!C
9 months ago	Update readme	26	630	void mygen(void param){
			631	bool domore = true;
			632	// The parameter is a pointer to a string of chars
			633	for (char str = param; str; ++str) {
			634	// The value yielded is a pointer to a character in the string
			635	domore = Generator_Yield(str);
			636	if (!domore){
			637	break;
			638	}
			639	}
			640
			641	return (void *)domore;
9 months ago	Documentation started	17	642	}
9 months ago	Documentation started	17	643
9 months ago	Update readme	26	644	The `bool` returned from `Generator_Yield()` indicates whether the generator function should yield more values. When it is `false` the `Generator` is being finalised - your generator function should close files, and release any other resources it has claimed, before exiting.
9 months ago	Documentation started	17	645
9 months ago	Documentation WIP	35	646	##### void Generator_ctor(Generator gen, void (start)(void ), void *param)
9 months ago	Documentation started	17	647
9 months ago	Documentation WIP	31	648	gen
9 months ago	Documentation WIP	31	649	: The `Generator` to construct.
9 months ago	Documentation started	17	650
9 months ago	Documentation WIP	31	651	start
			652	: The function which is the start/entry-point of the `Generator`.
			653
			654	param
			655	: The value to pass to `start`.
			656
			657	Initialise a `Generator`. When you no longer need the `Generator`, use `Generator_dtor()` to destruct it.
			658
9 months ago	All code blocks language-tagged	39	659	#!C
9 months ago	Update readme	26	660	Generator gen;
9 months ago	Update readme	26	661	Generator_ctor(&gen, mystart, &params);
9 months ago	Documentation started	17	662
9 months ago	Update readme	26	663	// Generator is used
9 months ago	Documentation started	17	664
9 months ago	Update readme	26	665	// ... later:
			666	Generator_dtor(&gen);
			667
9 months ago	Documentation WIP	35	668	##### Generator Generator_New(void (start)(void ), void *param)
9 months ago	Update readme	26	669
9 months ago	Documentation WIP	31	670	start
9 months ago	Documentation WIP	31	671	: The function which is the start/entry-point of the `Generator`.
9 months ago	Update readme	26	672
9 months ago	Documentation WIP	31	673	param
			674	: The value to pass to `start`.
			675
			676	`new` a `Generator` - malloc, and initialise it. When you no longer need the `Generator` use `Generator_dtor` to finalise it.
			677
9 months ago	All code blocks language-tagged	39	678	#!C
9 months ago	Update readme	26	679	Generator *gen = Generator_New(mystart, &params);
			680
			681	// Generator is used
			682
			683	// ... later:
			684	Generator_Delete(gen);
			685
9 months ago	Documentation WIP	35	686	##### void Generator_dtor(Generator *gen)
9 months ago	Update readme	26	687
9 months ago	Documentation WIP	31	688	gen
			689	: The `Generator` to destruct.
			690
9 months ago	Update readme	26	691	Finalise a `Generator`. Once a `Generator` is no longer needed, it must be finalised:
9 months ago	Update readme	26	692
9 months ago	All code blocks language-tagged	39	693	#!C
9 months ago	Update readme	26	694	// earlier...
			695	Generator gen;
			696	Generator_ctor(&gen, mystart, &params);
			697
			698	// Generator is used
			699
			700	// the Generator is no longer needed
			701	Generator_dtor(&gen);
			702
			703
9 months ago	Documentation WIP	35	704	##### void Generator_Delete(Generator *gen)
9 months ago	Update readme	26	705
9 months ago	Documentation WIP	31	706	gen
			707	: The `Generator` to delete.
			708
9 months ago	Update readme	26	709	Finalise then `free()` a `Generator`. Once a `new`ed `Generator` is no longer needed, it must be deleted:
9 months ago	Update readme	26	710
9 months ago	All code blocks language-tagged	39	711	#!C
9 months ago	Update readme	26	712	// earlier...
			713	Generator *gen = Generator_New(mystart, &params);
			714
			715	// Generator is used
			716
			717	// the Generator is no longer needed
			718	Generator_Delete(gen);
			719
			720
9 months ago	Documentation WIP	35	721	##### bool Generator_Next(Generator gen, void *value)
9 months ago	Update readme	26	722
9 months ago	Documentation WIP	31	723	(returns)
			724	: Whether there is a next value. `true` - there is a next value; `false` - the `Generator` has finished
			725
			726	gen
			727	: The `Generator` to get the next value from.
			728
			729	value
			730	: Where to store the next value.
			731
9 months ago	Update readme	26	732	Get the next value yielded by the `Generator`.
9 months ago	Update readme	26	733
9 months ago	All code blocks language-tagged	39	734	#!C
9 months ago	Update readme	26	735	void *value;
			736	while(Generator_Next(gen, &value)){
			737	// use value here
9 months ago	Documentation started	17	738	}
9 months ago	API documentation started	24	739
9 months ago	Documentation WIP	31	740	The `Generator` feeds values to its client using `Generator_Yield()` - it is these values which `Generator_Next()` sets, in the example, `value` to.
9 months ago	API documentation started	24	741
9 months ago	Documentation WIP	31	742	When a `Generator` is finished it returns from `start`. When you call `Generator_Yield()` on a finished `Generator` it returns `false` and `value` will be the return value from `start`.
9 months ago	Documentation WIP	31	743
9 months ago	Documentation WIP	35	744	##### bool Generator_Yield(void *value)
9 months ago	Update readme	26	745
9 months ago	Documentation WIP	31	746	(returns)
9 months ago	Documentation WIP	31	747	: Whether the `Generator` should do more.
9 months ago	Update readme	26	748
9 months ago	Documentation WIP	31	749	value
			750	: The `Generator`'s next value.
			751
			752	Yield a value from a `Generator`.
			753
9 months ago	All code blocks language-tagged	39	754	#!C
9 months ago	Update readme	26	755	bool domore = Generator_Yield(value);
9 months ago	Update readme	26	756
9 months ago	Documentation WIP	31	757	`value` is then provided by `Generator_Next()` as the next value from the generator.
9 months ago	Update readme	26	758
9 months ago	Documentation WIP	31	759	The `bool` returned by `Generator_Yield()` says whether more values should be provided by your generator function. `true` - provide more values if there are any. `false` - close files, free memory, free up any other resources and `return`. `false` is returned when the `Generator` is being finalised before it has finished, ie the client has exited its `for`-loop early.
9 months ago	Documentation WIP	31	760
9 months ago	API documentation started	24	761	## Coroutine
9 months ago	API documentation started	24	762
9 months ago	Documentation WIP	35	763	##### void Coroutine_StartSystem()
9 months ago	API documentation started	24	764
9 months ago	Documentation moderately done	36	765	Start the coroutine system on this thread. When you've finished with `Coroutine` must call `Coroutine_Stop()`.
9 months ago	API documentation started	24	766
9 months ago	All code blocks language-tagged	39	767	#!C
9 months ago	Documentation WIP	31	768	Coroutine_Start();
			769	// prepare
			770	void *result = Coroutine_Run(...);
			771	// use result
			772	Coroutine_Stop();
9 months ago	API documentation started	24	773
9 months ago	Documentation WIP	31	774	`Coroutine` can be started & stopped many times. While `Coroutine` is started, `Coroutine_Run()` can be called any number of times.
			775
			776	The total stack allowed for all coroutines running on any thread is the size of the call stack on that thread.
			777
9 months ago	Split down into component parts	37	778	##### Coroutine_Report Coroutine_StopSystem()
9 months ago	Documentation WIP	31	779
9 months ago	Split down into component parts	37	780	Stop the coroutine system on this thread. A `Coroutine_Report` is returned, which summarises the coroutine activity on this thread:
9 months ago	API documentation started	24	781
9 months ago	All code blocks language-tagged	39	782	#!C
9 months ago	Split down into component parts	37	783	typedef struct Coroutine_Report {
			784	unsigned coroutines_created;
			785	unsigned coroutines_pool_size;
			786	unsigned lowest_headroom;
			787	} Coroutine_Report;
			788
			789	coroutines_created
			790	: How many coroutines were created
			791
			792	coroutines_pool_size
			793	: The size of the coroutine pool (count of available, free `Coroutine` objects) when the system stopped. This is also the peak number of active coroutines. This will give you an idea of how much stack was needed for your coroutines.
			794
			795	lowest_headroom
			796	: The lowest headroom (unused bytes before the guard word) any of the coroutine had.
			797
9 months ago	Documentation WIP	35	798	##### Coroutine_Start
9 months ago	API documentation started	24	799
9 months ago	All code blocks language-tagged	39	800	#!C
9 months ago	API documentation started	24	801	void ()(void *param)
9 months ago	API documentation started	24	802
9 months ago	Documentation experiment	27	803	The entry function for a coroutine. The `param` is the value passed to `Coroutine_Continue`, and the `void *` return value can be accessed through the `Coroutine` object using `Coroutine_GetValue()`.
9 months ago	API documentation started	24	804
9 months ago	Documentation WIP	35	805	##### Coroutine *Coroutine_New(Coroutine_Start start)
9 months ago	API documentation started	24	806
			807	Create a new `Coroutine`. The `Coroutine` system must be started to create a `Coroutine`. The stack size available to the coroutine will be `COROUTINE_STACK_SIZE` defined in `coroutine.h`. When you have finished with your `Coroutine`, use `Coroutine_Delete()` to delete it.
			808
9 months ago	Documentation WIP	35	809	##### void Coroutine_Run_Coroutine(Coroutine cor, void value)
9 months ago	API documentation started	24	810
			811	Run the `Coroutine` and return when it returns. This is how to start coroutines running in the coroutine system. It is an error for the run coroutine to return before all other coroutines have completed.
			812
9 months ago	Documentation WIP	35	813	##### void Coroutine_Run(Coroutine_Start start, void value)
9 months ago	API documentation started	24	814
			815	Convenience wrapper for `Coroutine_Run_Coroutine` which creates the `Coroutine` and retrieves its result.
			816
9 months ago	Documentation WIP	35	817	##### void Coroutine_Delete(Coroutine *cor)
9 months ago	API documentation started	24	818
9 months ago	Documentation WIP	33	819	Use `Coroutine_Delete()` to delete a coroutine when it is no longer needed. It is an error to attempt to delete a coroutine which is running.
9 months ago	API documentation started	24	820
9 months ago	Documentation WIP	35	821	##### void Coroutine_Continue(Coroutine cor, void value, bool early)
9 months ago	API documentation started	24	822
			823	Continue the given `Coroutine`. `value` is passed to the coroutine, as `param` to the `start` function, or as the return value from `Coroutine_Yield`. `early` determines whether the continued coroutine is added to the head of tail of the list of runable coroutines.
			824
9 months ago	Documentation WIP	35	825	##### void Coroutine_Yield(void value, Coroutine_YieldCallback on_yield, void *this)
9 months ago	API documentation started	24	826
			827	Yield `value` from the current coroutine; this coroutine is moved to the list of coroutines waiting to be continued. The next runable coroutine is run - either by its start routine being called with `value` as its `param`, or by `value`being returned from its `Coroutine_Yield()`.
			828
9 months ago	Documentation WIP	35	829	##### void Coroutine_GetValue(Coroutine cor)
9 months ago	API documentation started	24	830
			831	Return the `Coroutine`'s value - the value last yielded, or returned by its `start` routine.
			832
9 months ago	Documentation WIP	35	833	##### Coroutine *Coroutine_GetActive()
9 months ago	API documentation started	24	834
			835	Return whihc coroutine is currently running, ie the caller's `Coroutine`.
			836
9 months ago	Documentation WIP	35	837	##### bool Coroutine_IsRunning(Coroutine *cor)
9 months ago	API documentation started	24	838
9 months ago	API documentation started	24	839	Return whether the given coroutine is still running - it may be running, ready to run, or waiting to be continued, but won't have returned from its `start` function.
9 months ago	Documentation experiment	27	840
9 months ago	Documentation WIP	35	841	##### int Coroutine_GetStackHeadroom()
9 months ago	Documentation experiment	27	842
9 months ago	Documentation moderately done	36	843	Return the headroom available in the current coroutine's stack. This can be used to detect when your coroutine is nearing its stack limit, and then use `Coroutine_Chain()` to continue in a new chunk of coroutine stack.
9 months ago	Documentation experiment	27	844
9 months ago	Documentation WIP	35	845	##### bool Coroutine_HasCoroutinesInFreePool()
9 months ago	Documentation experiment	27	846
			847	Return whether the coroutine system has any coroutine stacks available in its coroutine stack free pool.
			848
9 months ago	Documentation WIP	35	849	##### void *Coroutine_GetCStackTop()
9 months ago	Documentation experiment	27	850
			851	Return an address which is near to the top of used C stack.
			852
9 months ago	Documentation WIP	35	853	##### void Coroutine_Chain(Coroutine_Start start, void value)
9 months ago	Documentation experiment	27	854
			855	Run `start` with `value` on a new coroutine, and return its return value. It is expected that `Coroutine_Chain()` will be used when your coroutine is running short of stack - it is not an alternative to `Coroutine_Run()`.
			856