From 4077fac8cb7e632a9ac1db7037d529ecb1f1db91 Mon Sep 17 00:00:00 2001 From: Alexander Marks Date: Sat, 22 Oct 2022 11:11:03 -0700 Subject: [PATCH 1/2] Services state diagram --- src/execution/service.ts | 56 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/src/execution/service.ts b/src/execution/service.ts index 6323ca6cd..cdd374f58 100644 --- a/src/execution/service.ts +++ b/src/execution/service.ts @@ -17,6 +17,62 @@ import type {Result} from '../error.js'; /** * Execution for a {@link ServiceScriptConfig}. + * + * ``` + * ┌─────────┐ + * ╭─◄─ abort ────┤ INITIAL │ + * │ └────┬────┘ + * │ │ + * ▼ execute + * │ │ + * │ ┌───────▼────────┐ + * ├─◄─ abort ─┤ FINGERPRINTING ├──── depExecErr ────►───╮ + * │ └───────┬────────┘ │ + * │ │ │ + * ▼ fingerprinted │ + * │ │ │ + * │ ┌─────▼─────┐ │ + * ├─◄─ abort ───┤ UNSTARTED │ │ + * │ └─────┬─────┘ ▼ + * │ │ │ + * │ start │ + * │ │ ╭─╮ │ + * │ │ │ start │ + * │ ┌────▼──▼─┴┐ │ + * │ ╭◄─ abort ┤ STARTING ├─── startErr or ────►──────┤ + * │ │ └────┬────┬┘ depServiceStartErr │ + * ▼ │ │ │ │ + * │ │ │ ▼ │ + * │ │ │ ╰─── depServiceExit ──►──╮ │ + * │ │ started │ │ + * │ ▼ │ ╭─╮ ▼ │ + * │ │ │ │ start │ │ + * │ │ ┌────▼─▼─┴┐ │ │ + * │ ├◄─ abort ┤ STARTED ├── exit ─────────────►──│───┤ + * │ │ └────┬─┬─┬┘ │ │ + * │ │ │ │ ╰─── detach ──╮ │ │ + * │ │ │ ▼ │ │ │ + * │ │ │ ╰───── depServiceExit ───►──┤ │ + * │ │ │ │ │ │ + * │ │ allConsumersDone │ │ │ + * │ ▼ (unless directly invoked) │ │ │ + * │ │ │ ▼ ▼ ▼ + * ▼ │ │ ╭─╮ │ │ │ + * │ │ │ │ start │ │ │ + * │ │ ┌────▼──▼─┴┐ │ │ │ + * │ ╰─────────► STOPPING ◄─────────────◄─────────╯ │ + * │ └┬─▲─┬─────┘ │ │ + * │ abort │ │ │ │ + * │ ╰─╯ │ │ │ + * │ exit │ │ + * │ │ ╭─╮ │ │ ╭─╮ + * │ │ │ start │ │ │ start + * │ ┌────▼─▼─┴┐ ┌────▼─────┐ ┌───▼─▼─┴┐ + * ╰──────────────► STOPPED │ │ DETACHED │ │ FAILED │ + * └┬─▲──────┘ └┬─▲───────┘ └┬─▲─────┘ + * abort │ *all* │ abort │ + * ╰─╯ ╰─╯ ╰─╯ + * ``` */ export class ServiceScriptExecution extends BaseExecutionWithCommand { private readonly _terminated = new Deferred>(); From 20010b4323c3031e9df06945de2245e5fdcf4b7e Mon Sep 17 00:00:00 2001 From: Alexander Marks Date: Sat, 22 Oct 2022 12:13:10 -0700 Subject: [PATCH 2/2] Document the lifetime of a ServiceScriptExecution --- src/execution/service.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/execution/service.ts b/src/execution/service.ts index cdd374f58..2fdf3bc83 100644 --- a/src/execution/service.ts +++ b/src/execution/service.ts @@ -18,6 +18,13 @@ import type {Result} from '../error.js'; /** * Execution for a {@link ServiceScriptConfig}. * + * Note that this class represents a service _bound to one particular execution_ + * of the script graph. In non-watch mode (`npm run ...`), there will be one + * instance of this class per service. In watch mode (`npm run --watch ...`), + * there will be one instance of this class per service _per watch iteration_, + * and the underlying child process will be transfered between instances of this + * class whenever possible to avoid restarts. + * * ``` * ┌─────────┐ * ╭─◄─ abort ────┤ INITIAL │