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