0 branches 0 tags
27
Documentation experiment
jonroach 19 Sep 2025 08:11
1 contributor
118 lines4.2 KB
Newer
Older
Text Raw Blame
  • Delete
-
+
commited
{line.log.rev}
 on
8 months ago
1
 #ifndef COROUTINE_H
2
 #define COROUTINE_H
3
9 months ago
2
4
 #include <stdbool.h>
5
8 months ago
6
 ///////////////////////////////////////////////////////////////////////////////
7
 // Coroutine
8
 //
9
 // Coroutines for C, based on setjmp/longjmp.
10
 // Thread safe - each thread has its own coroutine system
11
 // Coroutines are cooperatively scheduled
12
 // Coroutines have their own stack (currently 16K each)
13
 // A coroutine can be continued, queried, or deleted on a different thread.
14
 //
15
 // Usage:
16
 // Coroutine_StartSystem(); // call once per thread before using coroutines
17
 // Coroutine *co = Coroutine_New(start_function);
18
 // void *result = Coroutine_Run(co, initial_value);
19
 // Coroutine_Delete(co);
20
 // Coroutine_StopSystem(); // call once per thread when done with coroutines
21
 //
22
 // Inside the coroutine function:
23
 // void *value = Coroutine_Yield(yield_value, on_yield, this);
24
 // ...
25
 // return return_value;
26
 //
27
 // To create a coroutine:
28
 // Coroutine *co = Coroutine_New(start_function);
29
 // To start or continue a coroutine:
30
 // void *result = Coroutine_Continue(co, value, early);
31
 // // early=true puts the coroutine at the head of the run queue
32
 // // early=false puts the coroutine at the tail of the run queue
33
 // To yield from inside a coroutine:
34
 // void *value = Coroutine_Yield(yield_value, on_yield, this);
35
 // // on_yield is called before the next coroutine is run
36
 // // 'this' is passed to on_yield as its parameter
37
 // // value is the value passed to Coroutine_Continue
38
 // To delete a coroutine:
39
 // Coroutine_Delete(co);
40
 // To get the value yielded from, or returned by a corotuine:
41
 // void *value = Coroutine_GetValue(co);
42
 // To get the currently running coroutine (NULL if none):
43
 // Coroutine *co = Coroutine_GetActive();
44
 // To check if a coroutine is currently running:
45
 // bool running = Coroutine_IsRunning(co);
46
 //
47
 // Notes:
48
 // Coroutine is not expected to be used directly, but as a foundation for
49
 // higher level constructs such as Generators, Async, etc.
50
 //
51
 ///////////////////////////////////////////////////////////////////////////////
52
53
54
 // The stack is used as follows:
55
 // +------------------+ <- stack top
56
 // | coroutine header | <- more claimed as needed in Coroutine_New
57
 // +------------------+ <-
58
 // | coroutine stack | <-
59
 // +------------------+ <-
60
 // | coroutine header |
61
 // +------------------+
62
 // | coroutine stack |
63
 // +------------------+
64
 // | coroutine header |
65
 // +------------------+
66
 // | coroutine stack |
67
 // +------------------+
68
 // | coroutine header |
69
 // +------------------+
70
 // | coroutine stack |
71
 // +------------------+
72
 // | coroutine header |
73
 // +------------------+
74
 // | startup space | <- set aside by Coroutine_StartSystem
75
 // +------------------+
76
 // | caller | <- This calls Coroutine_StartSystem etc
77
 // +------------------+
78
 // | used stack |
79
 // +------------------+ <- stack bottom
80
81
 // Each coroutine has this much stack:
8 months ago
82
 #define COROUTINE_STACK_SIZE 65536
8 months ago
83
84
 // When Coroutines is started, an amount of stack is set aside to give
85
 // the caller of Coroutine_StartSystem a bit of room to work before calling
86
 // Coroutine_Run(), that is this amount:
8 months ago
87
 #define COROUTINE_STARTUP_STACK_SIZE 4096
8 months ago
88
8 months ago
89
 // Returned by Coroutine_StopSystem(), this summarises the coroutine session
90
 typedef struct Coroutine_Report {
91
 unsigned coroutines_created;
92
 unsigned coroutines_pool_size;
93
 unsigned lowest_headroom;
94
 } Coroutine_Report;
95
9 months ago
2
96
 typedef struct Coroutine Coroutine;
97
98
 typedef void (*Coroutine_YieldCallback)(void *this);
99
 typedef void *(*Coroutine_Start)(void *);
100
101
 void Coroutine_StartSystem();
8 months ago
102
 Coroutine_Report Coroutine_StopSystem();
8 months ago
103
 Coroutine *Coroutine_New(Coroutine_Start start);
8 months ago
104
 void Coroutine_Run_Coroutine(Coroutine *cor, void *value);
8 months ago
105
 void *Coroutine_Run(Coroutine_Start start, void *value);
9 months ago
2
106
 void Coroutine_Delete(Coroutine *cor);
107
 void Coroutine_Continue(Coroutine *cor, void *value, bool early);
8 months ago
108
 void *Coroutine_Yield(void *value, Coroutine_YieldCallback on_yield, void *me);
9 months ago
2
109
 void *Coroutine_GetValue(Coroutine *cor);
110
 Coroutine *Coroutine_GetActive();
8 months ago
111
 int Coroutine_GetStackHeadroom();
112
 bool Coroutine_HasCoroutinesInFreePool();
113
 void *Coroutine_GetCStackTop();
114
 void *Coroutine_Chain(Coroutine_Start start, void *value);
9 months ago
2
115
 bool Coroutine_IsRunning(Coroutine *cor);
8 months ago
116
117
 #endif
118