doc(action-plugin): describe single-process staging

Remove the stale warning that every nontrivial stage respawns the plugin and
therefore makes linear bind chains quadratic. Document that Dune now builds
dependencies between stages while preserving the running plugin process, and
that each dynamic-run invocation starts the program only once.

Signed-off-by: Rudi Grinberg <me@rgrinberg.com>

Author: rgrinberg

doc/reference/actions/dynamic-run.rst

@@ -8,6 +8,9 @@ dynamic-run
    Execute a program that was linked against the ``dune-action-plugin`` library.
    ``<prog>`` is resolved in the same way as in :doc:`run`.
 
+   The program remains running while Dune builds dependencies that it discovers,
+   so each ``dynamic-run`` invocation starts the program only once.
+
    Example::
 
    (dynamic-run ./plugin.exe)

otherlibs/dune-action-plugin/src/dune_action_plugin.mli

@@ -8,15 +8,9 @@ module V1 : sig
       dependencies of a computation. Dependencies can be declared dynamically -
       the list of dependencies can depend on previous dependencies.
 
-      Note: Monadic "bind" is provided, but it can be very costly. It's called
-      [stage] to discourage people from overusing it. When dune decides that the
-      action needs to be re-run, it runs (nontrivial) stages one by one, and
-      starts a process from scratch for every stage. So a linear chain of binds
-      leads to a linear number of program re-runs, and therefore overall
-      quadratic time complexity. This also means that using non-deterministic
-      mutable state can lead to surprising results. (note that with the current
-      implementation, nontrivial stages are those that have some dependencies,
-      so a stage that merely writes out some targets is "free") *)
+      Monadic "bind" is called [stage] to make dynamic dependency boundaries
+      explicit. Dune builds the dependencies of each stage while keeping the
+      plugin process running, then resumes the computation in that process. *)
 
   module Path = Path
 
@@ -40,8 +34,8 @@ module V1 : sig
       [stage a ~f] is a computation that is equivalent to staging computation
       [bt] after computation [at].
 
-      Note: This is a monadic "bind" function. This function is costly so
-      different name was chosen to discourage excessive use. *)
+      This is a monadic "bind" function. The name highlights that dependencies
+      introduced by [f] are discovered in a later stage. *)
   val stage : 'a t -> f:('a -> 'b t) -> 'b t
 
   (** {1 Syntax sugar for applicative subset} *)