Lightning.Collaboration.DocumentSupervisor (Lightning v2.19.0-pre)

View Source

Manages the lifecycle of collaborative workflow document processes.

This GenServer coordinates a SharedDoc and PersistenceWriter for each collaborative workflow document. It starts both processes with proper dependencies, registers the SharedDoc with the :pg process group for cluster-wide coordination, and handles graceful shutdown by ensuring the SharedDoc flushes data to the PersistenceWriter before termination.

Uses a transient restart strategy, only restarting if the supervisor itself crashes, not when child processes exit normally. Monitors both child processes and stops itself if either child crashes.

Optionally monitors an :owner pid (passed through the child spec). When that owner goes :DOWN, the supervisor stops :normal โ€” running terminate/2's flush, and not restarting (transient). This is the owner-monitored self-cleanup seam from .claude/guidelines/testable-supervision-trees.md ยง3: any caller gets deterministic teardown by passing owner: self(). With no owner (the production default) the document outlives its starter as before.

Summary

Functions

Returns a specification to start this module under a supervisor.

Gracefully stops the DocumentSupervisor and its children.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

start_link(args, opts \\ [])

stop(pid, timeout \\ 15000)

Gracefully stops the DocumentSupervisor and its children.

Synchronous: returns only once terminate/2 has run, which flushes the PersistenceWriter (via the SharedDoc) and stops both children. Because the child spec uses restart: :transient, a :normal stop is not restarted by the DynamicSupervisor.

The default timeout must stay above what terminate/2 can take, or a slow flush makes this exit :timeout while the tree is still running and unflushed โ€” and Collaborate.stop_document/2 reports that as :ok. terminate/2 bounds each child stop at 5s, so 15s leaves headroom over the 10s worst case.