1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
{
"format": 1,
"id": "saw-buffer",
"kind": "class",
"name": "buffer",
"namespace": "saw",
"module": "core",
"header": "modules/core/c++/buffer.hpp",
"brief_description": "Access class to reduce templated buffer segment bloat.",
"detailed_description": [
[
"A buffer has two independent cursors, one for reading and one for writing, and may be split into segments which are contiguous only up to a point. Everything is phrased around that: composite length is what remains in total, segment length is what remains without a jump."
],
[
"Code which copies in bulk loops on the segment length; code which works byte by byte uses read and write with an offset. Both cursors move only through the advance calls, so a reader can look ahead without consuming."
]
],
"functions": {
"saw-buffer-read_position": {
"id": "saw-buffer-read_position",
"name": "read_position",
"type": ["size_t"],
"const": true,
"virtual": true,
"brief_description": "Where the read cursor currently is."
},
"saw-buffer-read_composite_length": {
"id": "saw-buffer-read_composite_length",
"name": "read_composite_length",
"type": ["size_t"],
"const": true,
"virtual": true,
"brief_description": "How many bytes can be read in total, across segments."
},
"saw-buffer-read_segment_length": {
"id": "saw-buffer-read_segment_length",
"name": "read_segment_length",
"type": ["size_t"],
"const": true,
"virtual": true,
"brief_description": "How many bytes can be read contiguously from an offset.",
"parameters": [
{"name": "offset", "type": ["size_t"], "default": "0"}
]
},
"saw-buffer-read_advance": {
"id": "saw-buffer-read_advance",
"name": "read_advance",
"type": ["void"],
"virtual": true,
"brief_description": "Consumes bytes from the read side.",
"parameters": [
{"name": "bytes", "type": ["size_t"]}
]
},
"saw-buffer-read": {
"id": "saw-buffer-read",
"name": "read",
"type": ["uint8_t &"],
"virtual": true,
"brief_description": "The byte at an offset from the read cursor, without consuming it.",
"parameters": [
{"name": "i", "type": ["size_t"], "default": "0"}
]
},
"saw-buffer-write_position": {
"id": "saw-buffer-write_position",
"name": "write_position",
"type": ["size_t"],
"const": true,
"virtual": true,
"brief_description": "Where the write cursor currently is."
},
"saw-buffer-write_composite_length": {
"id": "saw-buffer-write_composite_length",
"name": "write_composite_length",
"type": ["size_t"],
"const": true,
"virtual": true,
"brief_description": "How many bytes can be written in total, across segments."
},
"saw-buffer-write_segment_length": {
"id": "saw-buffer-write_segment_length",
"name": "write_segment_length",
"type": ["size_t"],
"const": true,
"virtual": true,
"brief_description": "How many bytes can be written contiguously from an offset.",
"parameters": [
{"name": "offset", "type": ["size_t"], "default": "0"}
]
},
"saw-buffer-write_advance": {
"id": "saw-buffer-write_advance",
"name": "write_advance",
"type": ["void"],
"virtual": true,
"brief_description": "Marks bytes as written.",
"parameters": [
{"name": "bytes", "type": ["size_t"]}
]
},
"saw-buffer-write": {
"id": "saw-buffer-write",
"name": "write",
"type": ["uint8_t &"],
"virtual": true,
"brief_description": "The byte at an offset from the write cursor.",
"parameters": [
{"name": "i", "type": ["size_t"], "default": "0"}
]
},
"saw-buffer-write_require_length": {
"id": "saw-buffer-write_require_length",
"name": "write_require_length",
"type": [{"name": "error", "id": "saw-error"}],
"virtual": true,
"brief_description": "Asks for room before writing in bulk.",
"detailed_description": [
[
"Nothing can be done if the read side has not been filled, but the write side can grow on demand. Call this before pushing a run of bytes, so a failure happens once up front instead of halfway through."
]
],
"parameters": [
{"name": "bytes", "type": ["size_t"]}
]
},
"saw-buffer-push-1": {
"id": "saw-buffer-push-1",
"name": "push",
"type": [{"name": "error", "id": "saw-error"}],
"brief_description": "Writes one byte.",
"detailed_description": [
["Fails with", {"name": "buffer_exhausted", "id": "saw-err-buffer_exhausted"}, "if there is no room."]
],
"parameters": [
{"name": "value", "type": ["const uint8_t &"]}
]
},
"saw-buffer-push-2": {
"id": "saw-buffer-push-2",
"name": "push",
"type": [{"name": "error", "id": "saw-error"}],
"brief_description": "Writes a run of bytes, segment by segment.",
"parameters": [
{"name": "buffer", "type": ["const uint8_t &"], "brief_description": "First byte of the run."},
{"name": "size", "type": ["size_t"]}
]
},
"saw-buffer-pop-1": {
"id": "saw-buffer-pop-1",
"name": "pop",
"type": [{"name": "error", "id": "saw-error"}],
"brief_description": "Reads one byte and consumes it.",
"parameters": [
{"name": "value", "type": ["uint8_t &"]}
]
},
"saw-buffer-pop-2": {
"id": "saw-buffer-pop-2",
"name": "pop",
"type": [{"name": "error", "id": "saw-error"}],
"brief_description": "Reads a run of bytes and consumes them.",
"parameters": [
{"name": "buffer", "type": ["uint8_t &"]},
{"name": "size", "type": ["size_t"]}
]
},
"saw-buffer-write_from": {
"id": "saw-buffer-write_from",
"name": "write_from",
"type": ["error_or< uint64_t >"],
"brief_description": "Reads from another buffer and writes into this one.",
"parameters": [
{"name": "buff", "type": ["const buffer &"]}
]
}
},
"notes": [
"The concrete buffers differ in what happens when space runs out, which is the thing to pick on."
]
}
|
