Skip to content
← Back

src/syntax/process/generate-il/generate_il_generators.ghul

1
namespace Syntax.Process is
2
use IO.Std
3
4
use System.Text.StringBuilder
5
6
use Logging
7
use Trees
8
use Source
9
10
use IR
11
use IR.Values
12
13
use Ghul.Pipes
14
15
16
// Generator state machines: the outer-method stub, the MoveNext body walk and the deferred
17
// state-machine class emission.
18
partial GENERATE_IL is
19
// Generator IL emission:
20
//
21
// 1. The outer user-facing method gets a stub body
22
// (`newobj $StateMachine.ctor(); ret`) emitted inline,
23
// so the AST visit order is unchanged for the caller.
24
// 2. The function body is walked here (recursively, via
25
// self) into a fresh IR.Values.BLOCK that represents
26
// MoveNext's body. Yield statements emit their state-
27
// machine IL into this block as they are walked.
28
// 3. The state-machine class itself is deferred — captured
29
// in `_pending_state_machines` and emitted at the SAME
30
// level as the user's class (after `visit(`class)`
31
// closes the user class), since CIL doesn't allow
32
// classes nested inside method bodies.
33
_pre_generator_function(function: Definitions.FUNCTION, symbol: Semantic.Symbols.Function, state_machine: Semantic.Symbols.STATE_MACHINE) -> bool is
34
let frame = state_machine.frame
35
36
if !frame? then
37
_logger.error(function.location, "generator must return Iterable[T], Iterator[T] or Pipe[T]")
38
39
return true
40
fi
41
42
// Realise the frame's symbol-level declarations (fields
43
// + ctor) once. Required for both the outer method's
44
// newobj reference and the state-machine class itself.
45
frame.declare()
46
47
// --- Outer user-facing method ---
48
//
49
// Forward this method's own arguments, construct the
50
// frame, return it.
51
_without_position(() is _emit_generator_outer_method(symbol, frame, state_machine) si)
52
53
// --- Walk the body into MoveNext's block ---
54
//
55
// The block lands captured on PENDING_STATE_MACHINE
56
// alongside the state machine; `_emit_pending_state_
57
// machines` writes it out inside the class definition
58
// once the enclosing user class has closed.
59
//
60
// For a generic generator, move each function-T symbol to
61
// a class-level position on the frame, so any IR.Values
62
// inside MoveNext that baked in function-T (callvirt owner
63
// types on the for-each dispatch, locals init for the
64
// iterator current, etc.) reach `!N` — MoveNext has no
65
// type parameters of its own — rather than `!!N`.
66
// The destructured formal arguments are unpacked into their
67
// leaf frame fields before the body reads them: the plain
68
// path's AST walk does this from visit(Variables.VARIABLE),
69
// and this path drives its own walk and never reaches those
70
// nodes.
71
_gen_generator_move_next(
72
function,
73
state_machine,
74
frame,
75
() => _gen_generator_function_body(function)
76
)
77
78
// Skip the framework's default body walk + the framework's
79
// visit(function) close-out path. Our visit(function)
80
// sees the state-machine and returns early.
81
return true
82
si
83
84
85
// A generator's MoveNext: the body of a generator function or a
86
// generator literal, walked into a block of its own and queued
87
// with its state machine for emission once the enclosing class
88
// has closed. `emit_body` emits the body into MoveNext's block.
89
_gen_generator_move_next(
90
scope: Trees.ScopeCarrier,
91
state_machine: Semantic.Symbols.STATE_MACHINE,
92
frame: Semantic.Symbols.STATE_MACHINE_FRAME,
93
emit_body: () -> void
94
) is
95
state_machine.install_body_emission_overrides()
96
97
enter_scope(scope)
98
99
let move_next_block = Values.BLOCK()
100
101
enter_block(move_next_block)
102
103
// `.maxstack` must precede any IL opcodes in the
104
// method body. Add it before the dispatch placeholder
105
// so the populated dispatch IL lands after the
106
// directive at the start of MoveNext.
107
add(Values.MAX_STACK(64))
108
109
// Cache the state field to a CLR local at MoveNext
110
// entry. Every yield keeps it in sync via `dup; stloc;
111
// stfld` so per-region dispatches and state-guarded
112
// finally bodies read a stable value. Same pattern as
113
// the async path — needed to allow yield inside `.try`
114
// without branching into a protected region from
115
// outside (ECMA-335 forbids that, and the previous
116
// centralized-dispatch shape had exactly that bug).
117
let resumable = Values.RESUMABLE(LABEL(), _innate_symbol_lookup.get_void_type())
118
119
_open_structured(resumable)
120
121
let outer_dispatch_holder =
122
_open_state_machine_entry(frame, frame.state_field, ".gen_state")
123
124
// Stash the enclosing generator's resumable body so nested
125
// generator functions (rare) don't trip over each other.
126
let prev_resumable = _current_generator_resumable
127
_current_generator_resumable = resumable
128
129
// A frame whose stream has ended stays ended: a read that wants
130
// to start over takes a fresh frame from GetEnumerator.
131
let int_type = _innate_symbol_lookup.get_int_type()
132
let not_done = _open_region(LABEL())
133
134
add(Values.BREAK(not_done, BRANCH.NE, Values.Load.TEMP(_current_state_local()!), Literal.NUMBER(-1, int_type)))
135
add(Literal.NUMBER(0, _innate_symbol_lookup.get_bool_type()))
136
add(Values.RET())
137
_close_structured(not_done)
138
139
// The body, emitted into current_block, which is MoveNext's
140
// block: each yield appends its suspend here.
141
emit_body()
142
143
// Fell-off-end trailer: mark done, return false. Plain `ret`
144
// since we're at the MoveNext outer scope (no open `.try`).
145
add(_build_frame_field_store(
146
frame, frame.state_field, Literal.NUMBER(-1, _innate_symbol_lookup.get_int_type())))
147
add(Literal.NUMBER(0, _innate_symbol_lookup.get_bool_type()))
148
add(Values.RET())
149
150
_current_generator_resumable = prev_resumable
151
152
_pop_async_dispatch_holder(outer_dispatch_holder)
153
154
_close_structured(resumable)
155
156
// If any yield inside an inner `.try` left the resumable
157
// body, return true after it (outside any try).
158
if resumable.is_targeted then
159
add(Literal.NUMBER(1, _innate_symbol_lookup.get_bool_type()))
160
add(Values.RET())
161
fi
162
163
leave_block()
164
leave_scope(scope)
165
166
// Uninstall — re-installed by _emit_state_machine_class
167
// around move_next_block.gen() so deferred IR.Value.gen()
168
// calls inside MoveNext still see the override. Between
169
// here and there, other class members emit normally.
170
state_machine.uninstall_body_emission_overrides()
171
172
_pending_state_machines.add(PENDING_STATE_MACHINE(state_machine, move_next_block))
173
si
174
175
// A generator literal: its body is walked into MoveNext exactly as
176
// a generator function's is, and the literal's own method is the
177
// outer method, constructing the frame from the literal's receiver
178
// and arguments and returning it. A literal that never settled on
179
// an element type has been reported in compile-expressions and
180
// emits nothing here.
181
_emit_generator_closure(
182
function: Trees.Expressions.FUNCTION,
183
closure: Semantic.Symbols.Closure,
184
state_machine: Semantic.Symbols.STATE_MACHINE
185
) is
186
let frame = state_machine.frame
187
188
if !frame? then
189
return
190
fi
191
192
frame.declare()
193
194
_gen_generator_move_next(
195
function,
196
state_machine,
197
frame,
198
() => _gen_generator_literal_body(function, closure)
199
)
200
201
_without_position(() is _emit_generator_outer_method(closure, frame, state_machine) si)
202
si
203
204
_gen_generator_function_body(function: Definitions.FUNCTION) is
205
_gen_destructured_formal_prologue(function)
206
207
if function.body? then
208
function.body.walk(self)
209
fi
210
si
211
212
_gen_generator_literal_body(function: Trees.Expressions.FUNCTION, closure: Semantic.Symbols.Closure) is
213
_gen_closure_destructure_prologue(function, closure)
214
215
function.body.walk(self)
216
si
217
218
_visit_generator_function(function: Definitions.FUNCTION, symbol: Semantic.Symbols.Function, state_machine: Semantic.Symbols.STATE_MACHINE) is
219
// _pre_generator_function emitted the outer method and
220
// captured the move_next block onto _pending_state_machines.
221
// Nothing more to do at AST visit time.
222
si
223
224
// `newobj` operand for the SM frame's constructor. For a
225
// generic frame, constructs a specialized type so the
226
// class-T's appear in the signature; for a non-generic frame,
227
// just the default ctor's IL reference. Exceptions in lookup
228
// are logged and a sentinel returned.
229
// A generator's outer method, built rather than walked. Its
230
// whole body is: forward this method's own arguments, construct
231
// the frame, return it.
232
_emit_generator_outer_method(
233
symbol: Semantic.Symbols.Function,
234
frame: Semantic.Symbols.STATE_MACHINE_FRAME,
235
state_machine: Semantic.Symbols.STATE_MACHINE
236
) is
237
// An instance generator hands `this` to the frame's
238
// constructor, which stores it into _outer_self so the
239
// body's `self` access can read back through the frame.
240
let arguments = Collections.LIST[Value]()
241
242
if frame.outer_self_field? then
243
arguments.add(Values.Load.RECEIVER(symbol))
244
fi
245
246
for index in 0..symbol.argument_names.count do
247
arguments.add(Values.Load.ARGUMENT(symbol, index))
248
od
249
250
let constructor = _specialized_frame_constructor(frame, state_machine, symbol.location)
251
252
_backend.begin_body()
253
_backend.write(_returning(Values.NEW(frame.type!, constructor, arguments)))
254
_backend.finish_body(symbol)
255
_backend.end_body()
256
si
257
258
// The frame constructor as it must be named from outside: on the
259
// frame's own instantiation when the frame is generic, and on
260
// the frame itself otherwise.
261
_specialized_frame_constructor(
262
frame: Semantic.Symbols.STATE_MACHINE_FRAME,
263
state_machine: Semantic.Symbols.STATE_MACHINE,
264
location: Source.LOCATION
265
) -> Semantic.Symbols.Function =>
266
_specialized_constructor(
267
frame,
268
frame.constructor,
269
state_machine.get_construction_type_arguments(),
270
location)
271
272
// The same, for any frame: a constructed generic's constructor
273
// is a different symbol from the open type's, and only the
274
// constructed one names a type that exists at run time.
275
_specialized_constructor(
276
frame: Semantic.Symbols.Classy,
277
default_constructor: Semantic.Symbols.Function,
278
construction_type_args: Collections.List[Semantic.Types.Type]?,
279
location: Source.LOCATION
280
) -> Semantic.Symbols.Function is
281
// With no type arguments there is nothing to specialize
282
// over, and the constructed form would be a second symbol
283
// for the same constructor — one the numbering pass never
284
// saw, so it has no row and gets named as if it were
285
// imported.
286
if !construction_type_args? \/ construction_type_args.count == 0 then
287
return default_constructor
288
fi
289
290
if let specialized =
291
_specialized_frame_type(frame, construction_type_args, location)
292
then
293
if let function: Semantic.Symbols.Function = specialized.find_member("init") then
294
return function
295
fi
296
fi
297
298
return default_constructor
299
si
300
301
_emit_state_machine_class(state_machine: Semantic.Symbols.STATE_MACHINE, move_next_block: Values.BLOCK) is
302
let frame = state_machine.frame
303
304
assert frame? else "state machine has no frame at IL emission"
305
306
// Local field types snapshot at the compile-expressions
307
// walk moment; narrowing can retype the source local
308
// later, so re-read the settled types before emitting.
309
frame.refresh_local_field_types()
310
311
// Re-install the body-emission override so deferred
312
// IR.Value.gen() inside MoveNext renders function-T as
313
// class-level `!N`. Uninstalled at the bottom of this
314
// method.
315
state_machine.install_body_emission_overrides()
316
317
// .ctor — parameterless, chains to Object::.ctor.
318
_without_position(() is _gen_state_machine_ctor(frame) si)
319
320
// MoveNext — populated during the body walk.
321
_emit_frame_member_body(
322
frame, IR.FrameMember.MOVE_NEXT, move_next_block)
323
324
// Other Iterator[T] / IDisposable members.
325
_without_position(() is _gen_state_machine_accessors(frame) si)
326
327
state_machine.uninstall_body_emission_overrides()
328
si
329
330
// A frame member the lowering synthesises, finished against the
331
// frame and which member it is. There is no symbol to finish it
332
// against: the member exists only in the emitted assembly.
333
_emit_frame_member_body(
334
frame: Semantic.Symbols.STATE_MACHINE_FRAME,
335
member: IR.FrameMember,
336
block: Values.BLOCK
337
) is
338
_backend.begin_body()
339
_backend.write(block)
340
_backend.finish_frame_member_body(frame, member)
341
_backend.end_body()
342
si
343
344
// The frame's constructor: chain to Object, then copy each
345
// constructor argument into the field the lowering declared for
346
// it. It is a declared symbol with a row of its own, so its body
347
// is deposited the same way any other method's is.
348
_gen_state_machine_ctor(frame: Semantic.Symbols.STATE_MACHINE_FRAME) is
349
let body = Values.BLOCK(_innate_symbol_lookup.get_void_type())
350
351
body.add(Values.RUNTIME(IR.RuntimeOperation.INIT_OBJECT, _frame_self(frame), null))
352
353
// Argument layout mirrors what STATE_MACHINE_FRAME.declare
354
// set up: [$outer_self,] arg0, arg1, ...
355
let argument mut = 0
356
357
if let outer_self_field = frame.outer_self_field then
358
body.add(_store_frame_field(frame, outer_self_field, Values.Load.ARGUMENT(frame.constructor, argument)))
359
360
argument = argument + 1
361
fi
362
363
// The pristine twins, index-aligned with `argument_fields`.
364
let initial_fields = frame.argument_initial_fields
365
366
for arg_field in frame.argument_fields do
367
body.add(_store_frame_field(frame, arg_field, Values.Load.ARGUMENT(frame.constructor, argument)))
368
369
argument = argument + 1
370
od
371
372
// Copy each freshly stored argument into its pristine twin,
373
// so a fresh frame can be constructed from what this one was
374
// constructed with after the body has written the working
375
// fields.
376
let index mut = 0
377
378
for arg_field in frame.argument_fields do
379
body.add(_store_frame_field(frame, initial_fields[index], _load_frame_field(frame, arg_field)))
380
381
index = index + 1
382
od
383
384
body.add(
385
_store_frame_field(
386
frame,
387
frame.thread_field,
388
Values.RUNTIME(IR.RuntimeOperation.CURRENT_THREAD_ID, _innate_symbol_lookup.get_int_type())))
389
390
body.add(Values.RET())
391
392
_backend.begin_body()
393
_backend.write(body)
394
_backend.finish_body(frame.constructor)
395
_backend.end_body()
396
si
397
398
// A synthesised body is written by no source, so whatever position
399
// the walk is at, the values built for it mark none.
400
_without_position(generate: () -> void) is
401
let locations = IoC.CONTAINER.instance.location_stack
402
403
locations.push(Source.LOCATION.internal)
404
405
try
406
generate()
407
finally
408
locations.pop()
409
yrt
410
si
411
412
_frame_self(frame: Semantic.Symbols.Classy) -> Value =>
413
Values.Load.REFERENCE_SELF(frame)
414
415
_load_frame_field(frame: Semantic.Symbols.Classy, target: Semantic.Symbols.Field) -> Value =>
416
Values.Load.INSTANCE_FIELD(_frame_self(frame), target)
417
418
_store_frame_field(frame: Semantic.Symbols.Classy, target: Semantic.Symbols.Field, value: Value) -> Value =>
419
Values.Store.INSTANCE_FIELD(_frame_self(frame), target, value)
420
421
// A body made of a single value followed by a return.
422
_returning(value: Value?) -> Values.BLOCK is
423
let body = Values.BLOCK(_innate_symbol_lookup.get_void_type())
424
425
if value? then
426
body.add(value)
427
fi
428
429
body.add(Values.RET())
430
431
return body
432
si
433
434
// The iterator surface every consumer reaches a frame through.
435
// Each body is fixed and small, so they are built here rather
436
// than walked: get_Current reads the current field,
437
// GetEnumerator returns the frame itself or a fresh one, Dispose
438
// and Reset do nothing, and ToString joins the pipe.
439
_gen_state_machine_accessors(frame: Semantic.Symbols.STATE_MACHINE_FRAME) is
440
// get_Current - read the current field.
441
_emit_frame_member_body(
442
frame,
443
IR.FrameMember.GET_CURRENT,
444
_returning(_load_frame_field(frame, frame.current_field)))
445
446
_emit_frame_member_body(
447
frame,
448
IR.FrameMember.GET_ENUMERATOR,
449
_get_enumerator_body(frame))
450
451
// Dispose - a no-op. A generator abandoned mid-flight does
452
// not run the user's finally bodies.
453
_emit_frame_member_body(frame, IR.FrameMember.DISPOSE, _returning(null))
454
455
// Reset - a no-op: a read that wants to start over takes a
456
// fresh frame from GetEnumerator.
457
_emit_frame_member_body(frame, IR.FrameMember.RESET, _returning(null))
458
459
// ToString - a generator is a Pipe[T], so stringify it the
460
// way every other Pipe does. The trait's default is a
461
// default interface method and does not override
462
// Object.ToString, so each implementing class needs its own.
463
_emit_frame_member_body(
464
frame,
465
IR.FrameMember.TO_STRING,
466
_returning(
467
Values.RUNTIME(
468
IR.RuntimeOperation.JOIN_PIPE,
469
[_frame_self(frame)]:Value,
470
_innate_symbol_lookup.get_string_type(),
471
frame.class_element_type)))
472
si
473
474
// GetEnumerator - the frame implements Iterator[T] itself, so
475
// the first read from the thread that made it is the frame.
476
// Every other read is a fresh frame, constructed from the
477
// arguments this one was, so each read starts from the
478
// beginning and reads in progress at once are independent.
479
_get_enumerator_body(frame: Semantic.Symbols.STATE_MACHINE_FRAME) -> Values.BLOCK is
480
let void_type = _innate_symbol_lookup.get_void_type()
481
let body = Values.BLOCK(void_type)
482
483
let claim = Values.REGION(IR.LABEL(), void_type)
484
claim.clear_position()
485
486
let already_claimed = Values.BREAK(claim, IR.BRANCH.NZ, _load_frame_field(frame, frame.claimed_field))
487
already_claimed.clear_position()
488
claim.body.add(already_claimed)
489
490
let other_thread =
491
Values.BREAK(
492
claim,
493
IR.BRANCH.NE,
494
Values.RUNTIME(IR.RuntimeOperation.CURRENT_THREAD_ID, _innate_symbol_lookup.get_int_type()),
495
_load_frame_field(frame, frame.thread_field))
496
other_thread.clear_position()
497
claim.body.add(other_thread)
498
499
claim.body.add(
500
_store_frame_field(
501
frame,
502
frame.claimed_field,
503
Values.Literal.NUMBER(1, _innate_symbol_lookup.get_bool_type())))
504
claim.body.add(_frame_self(frame))
505
claim.body.add(Values.RET())
506
claim.close()
507
508
body.add(claim)
509
510
let arguments = Collections.LIST[Value]()
511
512
if let outer_self_field = frame.outer_self_field then
513
arguments.add(_load_frame_field(frame, outer_self_field))
514
fi
515
516
for initial_field in frame.argument_initial_fields do
517
arguments.add(_load_frame_field(frame, initial_field))
518
od
519
520
body.add(Values.NEW(frame.type!, frame.constructor, arguments))
521
body.add(Values.RET())
522
523
return body
524
si
525
si
526
si