Lines Matching full:suspend
18 LLVM coroutines are functions that have one or more `suspend points`_.
19 When a suspend point is reached, the execution of a coroutine is suspended and
21 to continue execution from the last suspend point or it can be destroyed.
57 the initial entrypoint of the coroutine, which executes until a suspend point
63 must unwind the coroutine without attempting to suspend it.
106 Because the resume and destroy functions are shared across all suspend
107 points, suspend points must store the index of the active suspend in
133 In this lowering, every suspend point takes a list of "yielded values"
138 these continuation functions, one for each suspend point.
143 - In normal returned-continuation lowering, the coroutine may suspend
153 suspend itself exactly once (or throw an exception). The ramp
165 vary between suspend points.
193 Values live accross a suspend point need to be stored in the coroutine frame to
197 Every suspend point takes an `context projection function` argument which
198 describes how-to obtain the continuations `async context` and every suspend
204 a parameter to the `llvm.coro.suspend.async` intrinsic.
221 call {i8*, i8*, i8*} (i8*, i8*, ...) @llvm.coro.suspend.async(
241 function per suspend point.
246 The suspend point takes a function and its arguments. The function is intended
253 call {i8*, i8*, i8*} (i8*, i8*, ...) @llvm.coro.suspend.async(
275 <suspend> // returns a coroutine handle on first suspend
299 %0 = call i8 @llvm.coro.suspend(token none, i1 false)
300 switch i8 %0, label %suspend [i8 0, label %loop
305 br label %suspend
306 suspend:
326 The `suspend` block contains code to be executed when coroutine runs to
331 The `loop` blocks represents the body of the coroutine. The `coro.suspend`_
341 suspend points. In the coroutine shown in the previous section, use of virtual register
342 `%inc` is separated from the definition by a suspend point, therefore, it
359 execution of the coroutine until a suspend point is reached:
464 Multiple Suspend Points
467 Let's consider the coroutine that has more than one suspend point:
474 <suspend>
476 <suspend>
488 %2 = call i8 @llvm.coro.suspend(token none, i1 false)
489 switch i8 %2, label %suspend [i8 0, label %loop.resume
495 %3 = call i8 @llvm.coro.suspend(token none, i1 false)
496 switch i8 %3, label %suspend [i8 0, label %loop
499 In this case, the coroutine frame would include a suspend index that will
500 indicate at which suspend point the coroutine needs to resume. The resume
518 br label %suspend
523 br label %suspend
525 suspend:
531 If different cleanup code needs to get executed for different suspend points,
536 Using suspend index in a coroutine state and having a switch in `f.resume` and
539 every suspend point, and instead of storing an index, the resume and destroy
540 function pointers are updated at every suspend. Early testing showed that the
544 Distinct Save and Suspend
563 <suspend>
568 <suspend>
585 %suspend1 = call i1 @llvm.coro.suspend(token %save1, i1 false)
586 switch i8 %suspend1, label %suspend [i8 0, label %resume1
591 %suspend2 = call i1 @llvm.coro.suspend(token %save2, i1 false)
592 switch i8 %suspend1, label %suspend [i8 0, label %resume2
629 %0 = call i8 @llvm.coro.suspend(token none, i1 false)
630 switch i8 %0, label %suspend [i8 0, label %loop
635 br label %suspend
636 suspend:
676 .. _final suspend:
678 Final Suspend
681 A coroutine author or a frontend may designate a particular suspend to be final,
682 by setting the second argument of the `coro.suspend`_ intrinsic to `true`.
683 Such a suspend point has two properties:
685 * it is possible to check whether a suspended coroutine is at the final suspend
688 * a resumption of a coroutine stopped at the final suspend point leads to
690 suspend point is destroying it via `coro.destroy`_ intrinsic.
692 From the user perspective, the final suspend point represents an idea of a
698 until the final suspend point is reached after which point the coroutine is
716 Usually, final suspend point is a frontend injected suspend point that does not
717 correspond to any explicitly authored suspend point of the high level language.
718 For example, for a Python generator that has only one suspend point:
726 Python frontend would inject two more suspend points, so that the actual code
734 <SUSPEND> // injected suspend point, so that the coroutine starts suspended
736 current_value = i; <SUSPEND>; // corresponds to "yield i"
738 <SUSPEND final=true> // injected final suspend point
833 switched-resume coroutine is at the final suspend point or not.
843 Using this intrinsic on a coroutine that does not have a `final suspend`_ point
1231 multiple-suspend returned-continuation coroutine.
1281 unique-suspend returned-continuation coroutine.
1329 reached a ``llvm.coro.suspend.retcon`` has undefined behavior.
1392 .. _coro.suspend:
1395 'llvm.coro.suspend' Intrinsic
1399 declare i8 @llvm.coro.suspend(token <save>, i1 <final>)
1404 The '``llvm.coro.suspend``' marks the point where execution of a
1416 the `coro.suspend` intrinsic.
1419 The second argument only accepts constants. If more than one suspend point is
1423 Example (normal suspend point):
1428 %0 = call i8 @llvm.coro.suspend(token none, i1 false)
1429 switch i8 %0, label %suspend [i8 0, label %resume
1432 Example (final suspend point):
1438 %s.final = call i8 @llvm.coro.suspend(token none, i1 true)
1439 switch i8 %s.final, label %suspend [i8 0, label %trap
1448 If a coroutine that was suspended at the suspend point marked by this intrinsic
1451 basic block indicated by the 1-case. To suspend, coroutine proceed to the
1454 If suspend intrinsic is marked as final, it can consider the `true` branch
1481 the coroutine from the corresponding suspend point should be done at the point
1487 Separate save and suspend points are necessary when a coroutine is used to
1500 %suspend1 = call i1 @llvm.coro.suspend(token %save1, i1 false)
1501 switch i8 %suspend1, label %suspend [i8 0, label %resume1
1504 .. _coro.suspend.async:
1506 'llvm.coro.suspend.async' Intrinsic
1510 declare {i8*, i8*, i8*} @llvm.coro.suspend.async(
1519 The '``llvm.coro.suspend.async``' intrinsic marks the point where
1526 Lowering will replace this intrinsic with the resume function for this suspend
1534 suspend point. It should take 3 arguments. Lowering will `musttail` call this
1566 .. _coro.suspend.retcon:
1568 'llvm.coro.suspend.retcon' Intrinsic
1572 declare i1 @llvm.coro.suspend.retcon(...)
1577 The '``llvm.coro.suspend.retcon``' intrinsic marks the point where
1581 `llvm.coro.suspend.retcon`` does not support separate save points;
1600 a call to ``llvm.coro.suspend.retcon`` after resuming abnormally.
1603 executes a call to ``llvm.coro.suspend.retcon`` after resuming in any way.
1637 parameter copy is only used prior to control flow reaching any of the suspend
1658 co_await read_async(); // introduces suspend point
1662 Note that, uses of `b` is used after a suspend point and thus must be copied
1664 after suspend.
1683 of `a` with `a'`, since it is not used after suspend.
1686 after suspend and therefore, it has to reside in the coroutine frame.