https://github.com/sof3/await-rt
The low-level runtime of the await-generator library
https://github.com/sof3/await-rt
Last synced: 8 months ago
JSON representation
The low-level runtime of the await-generator library
- Host: GitHub
- URL: https://github.com/sof3/await-rt
- Owner: SOF3
- License: apache-2.0
- Created: 2023-08-26T07:59:05.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-10-30T01:02:57.000Z (about 2 years ago)
- Last Synced: 2025-03-31T20:11:41.577Z (10 months ago)
- Language: PHP
- Size: 19.5 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# await-rt
await-rt is the low-level runtime of the [await-generator][lib-repo] library.
See the await-generator repo or the [book][book] for beginner-level introduction.
## Specification
await-rt executes generators that conform to the await-generator protocol:
- The state transition of a generator:
- A generator must not start executing until it is passed to `Await::run()`.
- When passed to `Await::run()`,
the generator enters the *running* state.
It immediately rewinds and synchronously executes until its first suspension point.
The control flow will be returned to the caller of `Await::run()` *eventually*.
- When a generator in any state suspends with the string `"identity"`,
it is synchronously resumed with an object of arbitrary class
unique to the `Await::run()` call that rewinded the generator.
- When a generator in *running* state suspends with the string `"resolve"`,
it is synchronously resumed with a "resolve closure" of type `Closure(value=): void`.
The generator state changes to *scheduling/single*.
- When a generator in *scheduling/single* state
suspends with the string `"reject"`,
it is synchronously resumed with a "reject closure" of type `Closure(Throwable): void`.
The generator state changes to *scheduling/double*.
- When a generator in *scheduling/single* or *scheduling/double* state suspends with the string `"once"`,
the generator state changes to *pending* and is not actively resumed.
- When a generator is in *scheduling/single* or *scheduling/double* state
and the resolve closure is invoked,
the generator state changes to *ready/single* or *ready/double*.
Since the generator is supposed to be executing in the scheduling state,
the closure returns normally, returning the control flow to the generator.
- When a generator is in *scheduling/double* state and the reject closure is invoked,
the generator state changes to *failed*.
Since the generator is supposed to be executing in the scheduling state,
the closure returns normally, returning the control flow to the generator.
- When a generator is in *ready/single* or *ready/double* state and suspends with the string `"once"`,
the generator state changes to *running*,
and the generator is synchronously resumed with
the value previously passed to the resolve closure (or null if none passed).
- When a generator is in *failed* state and suspends with the string `"once"`,
the generator state changes to *running*,
and the generator is synchronously interrupted with
the throwable value previously passed to the reject closure.
This is effectively the same as replacing `yield "once"` with `throw $throwable`.
- When a generator is in *pending* state and the resolve closure is invoked,
the generator is synchronously resumed with the value passed (or null if none passed).
The control flow will be returned to the caller of the resolve closure *eventually*.
- When a generator is in *pending* state and the reject closure is invoked,
the generator is synchronously interrupted with the value passed (or null if none passed).
The control flow will be returned to the caller of the reject closure *eventually*.
no earlier than the next time the generatoe enters *pending*, *return* or *throw* state,
but the exact moment is undefined.
- When a generator is in *runnning* state and returns from the generator,
control flow is returned to the *eventual rewinds*.
- When a generator is in *runnning* state and throws out of the generator,
control flow is returned to the *eventual rewinds* with an active exception throwing.
- Note: This is different from await-generator v3,
where the exeption would be wrapped with an `AwaitException` instead.
- All state transitions not specified above
results in throwing an exception of an arbitrary type that extends or equals `\Exception`.
- Calling a resolve closure after the generator is resumed to the *running* state
results in throwing an exception of an arbitrary type that extends or equals `\Exception`.
- The terms *eventually* or *eventual rewinds* refer to the following:
When the control flow is passed into the await runtime,
i.e. through calling `Await::run`, resolve closure or reject closure,
the exact moment or order that the control flow is returned to the caller is undefined,
but is guaranteed to take place eventually provided that
the generator does not actively trigger any code that blocks indefinitely.
However, it is guaranteed that, if there are no other callers,
if the generator enters *running* state and then *return* or *throw* immediately,
the control flow is immediately returned to the caller.
```mermaid
stateDiagram
[*] --> running: Await..run
running --> scheduling/single: yield "resolve"
scheduling/single --> scheduling/double: yield "reject"
scheduling/single --> ready/single: invoke resolve closure
scheduling/double --> ready/double: invoke resolve closure
scheduling/double --> fail: invoke reject closure
ready/single --> ready/double: yield "reject"
scheduling/single --> pending: yield "once"
scheduling/double --> pending: yield "once"
ready/single --> running: yield "once"
ready/double --> running: yield "once"
failed --> running: yield "once"
pending --> running: invoke resolve closure\ninvoke reject closure
running --> [*]: return
running --> [*]: throw
```
[lib-repo]: https://github.com/SOF3/await-generator
[book]: https://sof3.github.io/await-generator/master