Skip to content
← Back

src/semantic/symbols/state_machine.ghul

1
namespace Semantic.Symbols is
2
use IO.Std
3
4
use System.Text.StringBuilder
5
6
use IoC
7
use Logging
8
use Source
9
10
use IR.Values.Value
11
12
use Types.Type
13
14
// Per-yield bookkeeping recorded by yield IL emission.
15
// The resumption label is placed immediately after the
16
// `ret` that suspends the generator; entry-dispatch jumps
17
// here when MoveNext re-enters in this state.
18
class STATE_LABEL is
19
state: int
20
label: IR.LABEL
21
22
init(state: int, label: IR.LABEL) is
23
self.state = state
24
self.label = label
25
si
26
si
27
28
// State held on a generator function symbol: the synthesised
29
// frame class, the running state-number counter, the recorded
30
// (state, resumption-label) pairs for entry-dispatch emission.
31
// Lives as a non-null field on each *_GENERATOR_* function;
32
// checked-for via `state_machine_for(...)`.
33
class STATE_MACHINE is
34
function: Function public
35
36
_frame: STATE_MACHINE_FRAME?
37
_next_state: int
38
_yield_labels: Collections.LIST[STATE_LABEL]
39
40
init(function: Function) is
41
self.function = function
42
43
_next_state = 1
44
_yield_labels = Collections.LIST[STATE_LABEL]()
45
si
46
47
// Drops the frame so the next access builds it afresh from the
48
// function's current return type, returning the frame dropped. A
49
// generator literal is walked more than once while its slot is
50
// being resolved, and a frame built on one walk carries that
51
// walk's element type and local fields.
52
reset() -> STATE_MACHINE_FRAME? is
53
let dropped = _frame
54
55
_frame = null
56
_next_state = 1
57
_yield_labels.clear()
58
59
return dropped
60
si
61
62
// Lazy: the frame class is materialised on first access,
63
// pulling its element type from the (now-resolved) function
64
// return type. Returns null only if the return type is not
65
// an `Iterable[T]` / `Iterator[T]` - which is an upstream
66
// diagnostic, not something the frame can recover from.
67
//
68
// A generator literal whose return is still to be inferred has
69
// no element type yet, but its body registers local fields on the
70
// frame as it is walked, so the frame is made now and learns its
71
// element type when the first yield settles the return.
72
frame: STATE_MACHINE_FRAME? is
73
if let existing = _frame then
74
existing.ensure_element_type()
75
76
return existing
77
fi
78
79
if let return_type = function.return_type /\ return_type.is_inferred /\ isa Closure(function) then
80
_frame = STATE_MACHINE_FRAME(function.owner!, function, null)
81
82
return _frame
83
fi
84
85
let element_type = generator_element_type(function)
86
87
if !element_type? then
88
return null
89
fi
90
91
_frame = STATE_MACHINE_FRAME(function.owner!, function, element_type)
92
93
return _frame
94
si
95
96
allocate_state() -> int is
97
let n = _next_state
98
99
_next_state = _next_state + 1
100
101
return n
102
si
103
104
record_label(state: int, label: IR.LABEL) is
105
_yield_labels.add(STATE_LABEL(state, label))
106
si
107
108
yield_labels: Collections.Iterable[STATE_LABEL] => _yield_labels
109
110
// Move every type parameter visible inside the body to a
111
// class-level position on the frame, and back again, so
112
// IR.Values built by compile-expressions reach `!N` — what
113
// MoveNext sees — rather than `!!N` on the original function.
114
// See `STATE_MACHINE_TYPE_PARAMS` for details.
115
install_body_emission_overrides() is
116
STATE_MACHINE_TYPE_PARAMS.walk_install(function, true)
117
si
118
119
uninstall_body_emission_overrides() is
120
STATE_MACHINE_TYPE_PARAMS.walk_install(function, false)
121
si
122
123
// Type arguments to pass at `newobj` construction time, in
124
// the same canonical order the frame captures them. See
125
// `STATE_MACHINE_TYPE_PARAMS` for details.
126
get_construction_type_arguments() -> Collections.List[Type]? =>
127
STATE_MACHINE_TYPE_PARAMS.construction_type_arguments(function)
128
si
129
130
// Synthesised class holding a generator's state machine.
131
// Implements `Iterator[T]` (so the ienumerable/ienumerator
132
// boilerplate emitters fire automatically). Members: `$state`
133
// (0=initial, -1=done, N=resumption point), `$current` (last
134
// yielded value), `$outer_self` (instance-only). The Iterator
135
// methods (MoveNext/get_Current/Dispose/Reset) are hand-emitted
136
// in generate_il rather than declared ghūl-side.
137
class STATE_MACHINE_FRAME: STATE_MACHINE_FRAME_BASE is
138
_next_id: int static
139
140
// Null for a generator literal until its first yield settles
141
// the literal's return type.
142
_element_type: Type?
143
144
// Null until declare() runs; outer-self stays null past
145
// declare() for static and global generators.
146
_state_field: Field?
147
_current_field: Field?
148
_claimed_field: Field?
149
_thread_field: Field?
150
151
element_type: Type => _element_type!
152
153
// The element type rewritten into the frame class's scope —
154
// for use when hand-emitting IL strings that reference the
155
// element type inside the class body (e.g. accessor method
156
// signatures). Renders as `!N` (class-level) for a generic
157
// generator, same as `_element_type` for a non-generic one.
158
class_element_type: Type => _class_relative(_element_type!)
159
// Non-null once declare() has run.
160
state_field: Field => _state_field!
161
current_field: Field => _current_field!
162
163
// Whether the frame has already been handed out as its own
164
// enumerator, and the thread that made it: the first read from that
165
// thread is the frame itself, and every other read a fresh frame.
166
claimed_field: Field => _claimed_field!
167
thread_field: Field => _thread_field!
168
169
next_id: int static is
170
let result = _next_id
171
_next_id = _next_id + 1
172
return result
173
si
174
175
init(owner: Scope, owning_function: Function, element_type: Type?) is
176
let owner_owner: Scope mut
177
178
if isa Symbol(owner) then
179
let owner_symbol = owner
180
owner_owner = owner_symbol.owner!
181
else
182
owner_owner = owner
183
fi
184
185
super.init(
186
LOCATION.internal,
187
LOCATION.internal,
188
owner_owner,
189
"$StateMachine_{owning_function.name}_{next_id}",
190
owner,
191
owning_function
192
)
193
194
_element_type = element_type
195
196
set_type(Types.NAMED(self))
197
si
198
199
// Declare the frame's members lazily — called by IL emission.
200
// Fields and constructor get real Symbol entities so reference
201
// emission (ldfld, stfld, newobj) routes through the existing
202
// SYMBOL_LOADER paths. The Iterator[T] / Iterable[T] methods
203
// are not declared as ghūl symbols: generate-il builds their
204
// bodies, and the backend gives them their .NET names.
205
declare() is
206
// A literal's outer-self target and captured type parameters
207
// arrive while its body is walked, so they are re-polled on
208
// every call, as the async frame does.
209
if isa Closure(owning_function) then
210
ensure_outer_self_field()
211
fi
212
213
if _state_field? then
214
// Recompute argument field types that may have been
215
// captured as not-yet-settled inference placeholders on
216
// the first declare().
217
refresh_argument_field_types()
218
return
219
fi
220
221
// A literal still waiting on its first yield has nothing to
222
// put in $current; everything else is declared once it does.
223
if !ensure_element_type() then
224
return
225
fi
226
227
let listener = IoC.CONTAINER.instance.symbol_definition_locations
228
229
declare_captured_type_params(listener)
230
231
let int_type = IoC.CONTAINER.instance.innate_symbol_lookup.get_int_type()
232
233
let state_field = Symbols.INSTANCE_FIELD(LOCATION.internal, self, "$state")
234
state_field.set_type(int_type)
235
declare(LOCATION.internal, state_field, listener)
236
_state_field = state_field
237
238
let current_field = Symbols.INSTANCE_FIELD(LOCATION.internal, self, "$current")
239
current_field.set_type(_class_relative(_element_type!))
240
declare(LOCATION.internal, current_field, listener)
241
_current_field = current_field
242
243
let claimed_field = Symbols.INSTANCE_FIELD(LOCATION.internal, self, "$claimed")
244
claimed_field.set_type(IoC.CONTAINER.instance.innate_symbol_lookup.get_bool_type())
245
declare(LOCATION.internal, claimed_field, listener)
246
_claimed_field = claimed_field
247
248
let thread_field = Symbols.INSTANCE_FIELD(LOCATION.internal, self, "$thread")
249
thread_field.set_type(int_type)
250
declare(LOCATION.internal, thread_field, listener)
251
_thread_field = thread_field
252
253
let ctor_argument_names = Collections.LIST[string]()
254
let ctor_argument_types = Collections.LIST[Type]()
255
256
// A literal's reference is to whatever holds its captures,
257
// found by ensure_outer_self_field above.
258
if let closure_outer_self = _outer_self_field /\ isa Closure(owning_function) then
259
ctor_argument_names.add("$outer_self")
260
ctor_argument_types.add(closure_outer_self.type!)
261
fi
262
263
// Instance generators carry a reference to the user's
264
// enclosing instance so the body's `self` / instance
265
// field access can be redirected via `ldarg.0; ldfld
266
// _outer_self`. The outer method passes `this` to the
267
// .ctor as the first argument.
268
if !isa Closure(owning_function) /\ owning_function.is_instance /\ owning_function.owner? /\ isa Classy(owning_function.owner) then
269
let outer_classy = cast Classy?(owning_function.owner)!
270
let self_type = outer_self_type(outer_classy)
271
272
let outer_self_field = Symbols.INSTANCE_FIELD(LOCATION.internal, self, "$outer_self")
273
outer_self_field.set_type(self_type)
274
declare(LOCATION.internal, outer_self_field, listener)
275
_outer_self_field = outer_self_field
276
277
ctor_argument_names.add("$outer_self")
278
ctor_argument_types.add(self_type)
279
fi
280
281
if owning_function.argument_names.count > 0 then
282
for arg_name in owning_function.argument_names do
283
let local = cast Symbols.LOCAL_ARGUMENT?(owning_function.find_direct(arg_name))
284
285
if !local? then
286
continue
287
fi
288
289
// As in the async frame: collapse a settled
290
// INFERRED_VARIABLE_TYPE placeholder before it can
291
// reach a field signature.
292
let arg_field_type = _class_relative(
293
SETTLED_PLACEHOLDER_RESOLVER.instance.resolve(local.type ?? Types.ERROR()))
294
295
let arg_field = Symbols.INSTANCE_FIELD(LOCATION.internal, self, "$arg_{arg_name}")
296
arg_field.set_type(arg_field_type)
297
declare(LOCATION.internal, arg_field, listener)
298
299
_argument_fields.add(arg_field)
300
301
// A pristine copy of the constructor argument, so the
302
// emitted Reset can restore what the body started
303
// from after the body has written the working field.
304
// Prefixed rather than suffixed: a suffix on one
305
// synthesised name can collide with another - a
306
// generator taking `n` and `n_initial` would derive
307
// `$arg_n_initial` twice - while no `$arg_`-prefixed
308
// name can equal an `$initial_arg_`-prefixed one.
309
let arg_initial_field = Symbols.INSTANCE_FIELD(LOCATION.internal, self, "$initial_arg_{arg_name}")
310
arg_initial_field.set_type(arg_field_type)
311
declare(LOCATION.internal, arg_initial_field, listener)
312
313
_argument_initial_fields.add(arg_initial_field)
314
315
local.state_machine_field = arg_field
316
317
ctor_argument_names.add(arg_name)
318
ctor_argument_types.add(arg_field_type)
319
od
320
fi
321
322
let ctor = Symbols.INSTANCE_METHOD(LOCATION.internal, LOCATION.internal, self, "init", self)
323
ctor.set_arguments(ctor_argument_names, ctor_argument_types)
324
ctor.set_void_return_type()
325
declare(LOCATION.internal, ctor, listener)
326
_constructor = ctor
327
328
_ctor_argument_names = ctor_argument_names
329
330
// Ancestors — Object + Iterable[T]/Iterator[T] so the
331
// standard boilerplate emitters (gen_extends /
332
// gen_implements, ienumerable/ienumerator bridges) fire.
333
// Interface args use the frame's own T so the implements
334
// clause emits `IEnumerable<!N>`.
335
let lookup = IoC.CONTAINER.instance.innate_symbol_lookup
336
let class_relative_element = _class_relative(_element_type!)
337
338
add_ancestor(lookup.get_object_type())
339
add_ancestor(_construct_specialised(lookup.get_unspecialized_iterable_type(), class_relative_element))
340
add_ancestor(_construct_specialised(lookup.get_unspecialized_iterator_type(), class_relative_element))
341
342
// If the declared return type is a *proper* subtype of
343
// Iterable[T] / Iterator[T] — a richer iterable trait such
344
// as Ghul.Pipes.Pipe[T] — implement it too, so the outer
345
// method can return the state machine directly as that
346
// type and the caller gets the trait's members (the pipe
347
// combinators) for free. A return type that is exactly
348
// Iterable[T] or Iterator[T] is already covered above;
349
// find_ancestor does not self-match, so it is not re-added.
350
let return_type = owning_function.return_type
351
352
if
353
return_type? /\
354
return_type.is_settled /\
355
(
356
return_type.find_ancestor(lookup.get_unspecialized_iterable_type())? \/
357
return_type.find_ancestor(lookup.get_unspecialized_iterator_type())?
358
)
359
then
360
add_ancestor(_class_relative(return_type))
361
fi
362
si
363
364
// Whether the element type is known, settling it from the owning
365
// function's return type once that return is no longer inferred.
366
ensure_element_type() -> bool is
367
if !_element_type? then
368
if let return_type = owning_function.return_type /\ !return_type.is_inferred then
369
_element_type = generator_element_type(owning_function)
370
fi
371
fi
372
373
return _element_type?
374
si
375
376
_construct_specialised(unspecialized: Type, type_arg: Type) -> Type is
377
let classy = cast Symbols.Classy?(unspecialized.symbol.unspecialized_symbol)!
378
379
let args = Collections.LIST[Type]()
380
args.add(type_arg)
381
382
return Types.GENERIC(LOCATION.internal, classy, args)
383
si
384
si
385
386
// The element type a generator produces: T from its Pipe[T],
387
// Iterable[T] or Iterator[T] return type, or null when the return
388
// type is none of those.
389
generator_element_type(function: Function) -> Type? is
390
let return_type = function.return_type
391
392
if !return_type? then
393
return null
394
fi
395
396
let lookup = IoC.CONTAINER.instance.innate_symbol_lookup
397
398
// A Pipe[T] return, or a trait extending one, is matched against
399
// Pipe first: its Iterable[T] base carries Pipe's own type
400
// parameter rather than the element type the return is
401
// constructed over.
402
if let pipe = lookup.get_unspecialized_pipe_type() then
403
if let element = TYPE_ARGUMENT_EXTRACTOR.extract(return_type, pipe) then
404
return element
405
fi
406
fi
407
408
let candidates = Collections.LIST[Type]()
409
candidates.add(lookup.get_unspecialized_iterator_type())
410
candidates.add(lookup.get_unspecialized_iterable_type())
411
412
return TYPE_ARGUMENT_EXTRACTOR.extract_from_any(return_type, candidates)
413
si
414
415
// The element type a slot expecting a sequence asks for: T from a
416
// Pipe[T], Iterable[T] or Iterator[T], or null for any other type.
417
// What a generator literal written into that slot yields.
418
sequence_element_type(slot: Type?) -> Type? is
419
if !slot? \/ !slot.is_settled then
420
return null
421
fi
422
423
let lookup = IoC.CONTAINER.instance.innate_symbol_lookup
424
425
let candidates = Collections.LIST[Type]()
426
427
if let pipe = lookup.get_unspecialized_pipe_type() then
428
candidates.add(pipe)
429
fi
430
431
candidates.add(lookup.get_unspecialized_iterable_type())
432
candidates.add(lookup.get_unspecialized_iterator_type())
433
434
return TYPE_ARGUMENT_EXTRACTOR.extract_from_any(slot, candidates)
435
si
436
437
// Pipe[T], the return type of a generator yielding T, or null when
438
// Pipe is unavailable (no runtime referenced).
439
generator_return_type(element_type: Type) -> Type? is
440
let pipe = IoC.CONTAINER.instance.innate_symbol_lookup.get_unspecialized_pipe_type()
441
442
if let classy: Classy = pipe?.symbol?.unspecialized_symbol then
443
return Types.GENERIC(LOCATION.internal, classy, Collections.LIST[Type]([element_type]))
444
fi
445
446
return null
447
si
448
449
// Free helper: returns the STATE_MACHINE held by any of the
450
// generator function and generator literal forms, or null if `f`
451
// is a plain function.
452
state_machine_for(f: Function?) -> STATE_MACHINE? is
453
if !f? then
454
return null
455
fi
456
457
if isa STATIC_GENERATOR_METHOD(f) then
458
return f.state_machine
459
fi
460
461
if isa INSTANCE_GENERATOR_METHOD(f) then
462
return f.state_machine
463
fi
464
465
if isa GLOBAL_GENERATOR_FUNCTION(f) then
466
return f.state_machine
467
fi
468
469
if isa INSTANCE_GENERATOR_CLOSURE(f) then
470
return f.state_machine
471
fi
472
473
if isa STATIC_GENERATOR_CLOSURE(f) then
474
return f.state_machine
475
fi
476
477
if isa GLOBAL_GENERATOR_CLOSURE(f) then
478
return f.state_machine
479
fi
480
481
return null
482
si
483
484
// Concrete generator-function forms — thin extensions of the
485
// existing function/method classes that additionally carry a
486
// STATE_MACHINE bookkeeping object. Each form differs only in
487
// its CLR-level signature shape (instance, static, global).
488
489
class STATIC_GENERATOR_METHOD: STATIC_METHOD is
490
state_machine: STATE_MACHINE public
491
492
describe_kind(context: DESCRIBE_CONTEXT) -> string? =>
493
"class generator"
494
495
is_accessible_to(accessor: Classy?) -> bool =>
496
_underscore_is_accessible_to(accessor)
497
498
init(location: LOCATION, span: LOCATION, owner: Scope, name: string, enclosing_scope: Scope) is
499
super.init(location, span, owner, name, enclosing_scope)
500
501
state_machine = STATE_MACHINE(self)
502
si
503
si
504
505
class INSTANCE_GENERATOR_METHOD: INSTANCE_METHOD is
506
state_machine: STATE_MACHINE public
507
508
describe_kind(context: DESCRIBE_CONTEXT) -> string? =>
509
"generator"
510
511
is_accessible_to(accessor: Classy?) -> bool =>
512
_underscore_is_accessible_to(accessor)
513
514
init(location: LOCATION, span: LOCATION, owner: Scope, name: string, enclosing_scope: Scope) is
515
super.init(location, span, owner, name, enclosing_scope)
516
517
state_machine = STATE_MACHINE(self)
518
si
519
520
// Inside the body, `self` and instance-member access go via
521
// the state-machine frame's _outer_self field rather than
522
// ldarg.0 (which would point at the state machine itself).
523
// Force the frame's declare() so _outer_self_field is
524
// available — compile-expressions reaches here before
525
// _pre_generator_function (the regular declare site) but
526
// after return-type resolution, so the lazy frame creation
527
// succeeds.
528
load_self(location: LOCATION, loader: SYMBOL_LOADER) -> Value is
529
let frame = state_machine.frame
530
531
if frame? then
532
frame.declare()
533
534
let outer_self_field = frame.outer_self_field
535
536
if outer_self_field? then
537
let context = IoC.CONTAINER.instance.symbol_table.current_instance_context
538
if context? then
539
return IR.Values.Load.OUTER_SELF(context, context.type, outer_self_field)
540
fi
541
fi
542
fi
543
544
return super.load_self(location, loader)
545
si
546
si
547
548
// A generator declared in a trait body. Always has a body — the
549
// generator classification comes from finding `yield` in one — so
550
// there is no abstract counterpart, and it is a default trait
551
// method for inheritance purposes like any other bodied trait
552
// member.
553
class DEFAULT_TRAIT_GENERATOR_METHOD: INSTANCE_GENERATOR_METHOD is
554
describe_kind(context: DESCRIBE_CONTEXT) -> string? =>
555
"default trait generator"
556
557
is_default_trait_method: bool => true
558
559
init(location: LOCATION, span: LOCATION, owner: Scope, name: string, enclosing_scope: Scope) is
560
super.init(location, span, owner, name, enclosing_scope)
561
si
562
563
try_instance_override_me(into: Classy, overrider: Function, logger: Logger) is
564
super.try_instance_override_me(into, overrider, logger)
565
566
_check_ineffective_trait_override(into, overrider, logger)
567
si
568
si
569
570
class GLOBAL_GENERATOR_FUNCTION: GLOBAL_FUNCTION is
571
state_machine: STATE_MACHINE public
572
573
describe_kind(context: DESCRIBE_CONTEXT) -> string? =>
574
"global generator"
575
576
init(location: LOCATION, span: LOCATION, owner: Scope, name: string, enclosing_scope: Scope) is
577
super.init(location, span, owner, name, enclosing_scope)
578
579
state_machine = STATE_MACHINE(self)
580
si
581
si
582
583
// Generator literal forms: a function literal whose body yields. Each
584
// is the corresponding plain closure carrying a STATE_MACHINE, as the
585
// async literal forms carry an ASYNC_STATE_MACHINE, so emission
586
// routes the literal's body into MoveNext and its own method
587
// constructs the frame.
588
class INSTANCE_GENERATOR_CLOSURE: INSTANCE_CLOSURE is
589
state_machine: STATE_MACHINE public
590
591
init(location: LOCATION, owner: Scope, name: string, enclosing_scope: Scope, is_recursive: bool) is
592
super.init(location, owner, name, enclosing_scope, is_recursive)
593
594
state_machine = STATE_MACHINE(self)
595
si
596
597
to_string() -> string => "[instance generator closure {name}]"
598
si
599
600
class STATIC_GENERATOR_CLOSURE: STATIC_CLOSURE is
601
state_machine: STATE_MACHINE public
602
603
init(location: LOCATION, owner: Scope, name: string, enclosing_scope: Scope, is_recursive: bool) is
604
super.init(location, owner, name, enclosing_scope, is_recursive)
605
606
state_machine = STATE_MACHINE(self)
607
si
608
609
to_string() -> string => "[static generator closure {name}]"
610
si
611
612
class GLOBAL_GENERATOR_CLOSURE: GLOBAL_CLOSURE is
613
state_machine: STATE_MACHINE public
614
615
init(location: LOCATION, owner: Scope, name: string, enclosing_scope: Scope, is_recursive: bool) is
616
super.init(location, owner, name, enclosing_scope, is_recursive)
617
618
state_machine = STATE_MACHINE(self)
619
si
620
621
to_string() -> string => "[global generator closure {name}]"
622
si
623
si