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.