Process Commands

.pylintrc

@@ -64,6 +64,7 @@ disable=print-statement,
         too-many-locals,
         too-many-branches,
         too-few-public-methods,
+        too-many-public-methods,
         too-many-lines,
         no-self-use,
         fixme,

doc/guides/processes.rst

@@ -562,3 +562,40 @@ The above pseudocode is simplified, and for all but the most simple
 processes you will be better off using Vivarium's built-in simulation
 capabilities. We hope though that this helps you understand how
 processes are simulated and the purpose of the API we defined.
+
+-------------------
+Parallel Processing
+-------------------
+
+Process Commands
+================
+
+When a :term:`process` is run in parallel, we can't interact with it in
+the normal Python way. Instead, we can only exchange messages with it
+through a pipe. Vivarium structures these exchanges using :term:`process
+commands`.
+
+Vivarium provides some built-in commands, which are documented in
+:py:meth:`vivarium.core.process.Process.send_command`. Also see that
+method's documentation for instructions on how to add support for your
+own commands.
+
+Process commands are designed to be used asynchronously, so to retrieve
+the result of running a command, you need to call
+:py:meth:`vivarium.core.process.Process.get_command_result`. As a
+convenience, you can also call
+:py:meth:`vivarium.core.process.Process.run_command` to send a command
+and get its result as a return value in one function call.
+
+Running Processes in Parallel
+=============================
+
+In normal situations though, you shouldn't have to worry about process
+commands. Instead, just pass ``'_parallel': True`` in a process's
+configuration dictionary, and the Vivarium Engine will handle the
+parallelization for you. Just remember that parallelization requires
+that processes be serialized and deserialized at the start of the
+simulation, and this serialization only preserves the process
+parameters. This means that if you instantiate a process and then change
+its instance variables, those changes won't be preserved when the
+process gets parallelized.

doc/reference/api/vivarium.core.process.rst

@@ -1,4 +1,5 @@
 .. automodule:: vivarium.core.process
    :members:
    :undoc-members:
+   :private-members: _handle_parallel_process
    :show-inheritance:

doc/reference/glossary.rst

@@ -233,6 +233,16 @@ Glossary
         subclass either :py:class:`vivarium.core.process.Process`
         or another process class.
 
+    Process Command
+    Process command
+    process command
+    Process Commands
+    Process commands
+    process commands
+        Instructions that let Vivarium communicate with parallel
+        processes in a remote-procedure-call-like fashion. See :doc:`the
+        processes guide </guides/processes>` for details.
+
     Raw Data
     Raw data
     raw data

vivarium/core/engine.py

@@ -174,7 +174,7 @@ def get(self) -> Update:
             The result of calling the function.
         """
         return self.f(
-            self.defer.get(),
+            self.defer.get_command_result(),
             self.args)
 
 
@@ -215,11 +215,11 @@ def __init__(
             self.interval,
             self.states)
 
-    def get(self) -> Update:
+    def get_command_result(self) -> Update:
         """Return the computed update.
 
-        This method is analogous to the ``.get()`` method in
-        :py:class:`vivarium.core.process.ParallelProcess` so that
+        This method is analogous to the ``.get_command_result()`` method
+        in :py:class:`vivarium.core.process.ParallelProcess` so that
         parallel and non-parallel updates can be intermixed in the
         simulation engine.
         """
@@ -711,7 +711,8 @@ def _invoke_process(
                 self.parallel[path] = ParallelProcess(
                     process, bool(self.profiler))
             # trigger the computation of the parallel process
-            self.parallel[path].update(interval, states)
+            self.parallel[path].send_command(
+                'next_update', (interval, states))
 
             return self.parallel[path]
         # if not parallel, perform a normal invocation