docs/REFORKING.md in pitchfork-0.9.0 vs docs/REFORKING.md in pitchfork-0.10.0
- old
+ new
@@ -64,12 +64,15 @@
103 \_ pitchfork (gen:0) worker[1]
104 \_ pitchfork (gen:0) worker[2]
105 \_ pitchfork (gen:0) worker[3]
```
-When a reforking is triggered, one of the workers is selected to fork a new `mold`.
+As the diagram shows, while workers are forked from the mold, they become children of the master process.
+We'll see how does that work [later](#forking-sibling-processes).
+When a reforking is triggered, one of the workers is selected to fork a new `mold`:
+
```
PID COMMAND
100 \_ pitchfork master
101 \_ pitchfork (gen:0) mold
102 \_ pitchfork (gen:0) worker[0]
@@ -77,10 +80,13 @@
104 \_ pitchfork (gen:0) worker[2]
105 \_ pitchfork (gen:0) worker[3]
105 \_ pitchfork (gen:1) mold
```
+Again, while the mold was forked from a worker, it becomes a child of the master process.
+We'll see how does that work [later](#forking-sibling-processes).
+
When that new mold is ready, `pitchfork` terminates the old mold and starts a slow rollout of older workers and replace them with fresh workers
forked from the mold:
```
PID COMMAND
@@ -102,11 +108,11 @@
106 \_ pitchfork (gen:1) worker[0]
```
etc.
-### Forking Sibling Processes
+### Forking Sibling Processes
Normally on unix systems, when calling `fork(2)`, the newly created process is a child of the original one, so forking from the mold should create
a process tree such as:
```
@@ -117,7 +123,10 @@
```
However the `pitchfork` master process registers itself as a "child subreaper" via [`PR_SET_CHILD_SUBREAPER`](https://man7.org/linux/man-pages/man2/prctl.2.html).
This means any descendant process that is orphaned will be re-parented as a child of the master rather than a child of the init process (pid 1).
-With this in mind, the mold fork twice to create an orphaned process that will get re-attached to the master, effectively forking a sibling rather than a child.
-The need for `PR_SET_CHILD_SUBREAPER` is the main reason why reforking is only available on Linux.
+With this in mind, the mold forks twice to create an orphaned process that will get re-attached to the master,
+effectively forking a sibling rather than a child. Similarly, workers do the same when forking new molds.
+This technique eases killing previous generations of molds and workers.
+
+The need for `PR_SET_CHILD_SUBREAPER` is the main reason why reforking is only available on Linux.