Skip to content

Commit

Permalink
splice the lifecycle diagrams into supervisor docs
Browse files Browse the repository at this point in the history
  • Loading branch information
samspills committed Aug 28, 2024
1 parent 30af681 commit 2b9ef41
Showing 1 changed file with 51 additions and 0 deletions.
51 changes: 51 additions & 0 deletions docs/std/supervisor.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,38 @@ title: Supervisor

`Spawn[F]#background`: ties the lifecycle of the spawned fiber to that of the fiber that invoked `background`

The following diagrams illustrate the lifecycle of the spawned fiber in both cases.
In each example, some fiber A is spawning another fiber B.
Each box represents the lifecycle of a fiber.
If a box is enclosed within another box, it means that the lifecycle of the former is confined within the lifecycle of the latter.
In other words, if an outer fiber terminates, the inner fibers are guaranteed to be terminated as well.

`Spawn[F]#start`:
```
Fiber A lifecycle
+---------------------+
| | |
+-----------------|---+
|
|A starts B
Fiber B lifecycle |
+-----------------|---+
| + |
+---------------------+
```

`Spawn[F]#background:`
```
Fiber A lifecycle
+------------------------+
| | |
| Fiber B lifecycle |A starts B
| +------------------|-+ |
| | | | |
| +--------------------+ |
+------------------------+
```

But what if we want to spawn a fiber that should outlive the scope that created
it, but we still want to control its lifecycle?

Expand All @@ -31,6 +63,25 @@ object Supervisor {
Any fibers created via the supervisor will be finalized when the supervisor itself
is finalized via `Resource#use`.

The lifecycle of fibers spawned with `Supervisor` can be illustrated in the same style as above:

```
Supervisor lifecycle
+---------------------+
| Fiber B lifecycle |
| +-----------------+ |
| | + | |
| +---------------|-+ |
+-----------------|---+
|
| A starts B
Fiber A lifecycle |
+-----------------|---+
| | |
+---------------------+
```


There are two finalization strategies according to the `await` parameter of the constructor:
- `true` - wait for the completion of the active fibers
- `false` - cancel the active fibers
Expand Down

0 comments on commit 2b9ef41

Please sign in to comment.