.. index:: pair: page; Process Launcher
.. _doxid-process_launcher:

Process Launcher
================

The :ref:`ProcessLauncher <doxid-class_process_launcher>` is in charge of spawning Engines in independent computational environments. Depending on the desired behavior, engines can be created in separate :ref:`processes <doxid-class_basic_fork>`, :ref:`containers <doxid-launch_command_1docker_launcher>`, or machines.

Default settings specify forking the NRPCoreSim process and launching the engine in the newly spawned child process. This setup suffices for local simulation execution of engines that do not require a vast amount of compute resources, or do not induce dependency conflicts. However a more complex launching process may be required to address such situations. For this purpose, we have introduced convenient mechanisms available through the :ref:`ProcessLauncher <doxid-class_process_launcher>` class.

Developers can create new process launchers by creating a new class derived from the :ref:`ProcessLauncher <doxid-class_process_launcher>` template. This new class must define the different :ref:`launch commands <doxid-launch_command>` available to different types of :ref:`ProcessLauncher <doxid-class_process_launcher>`, as well as the name of the configuration. On top of this, the new class must be made visible to the NRPCoreSim executable by adding it to the MainProcessLauncherManager definition in ``nrp_general_library/process_launchers/process_launcher_manager.h``.

Once this is done, the user can set the NRPCoreSim to utilize the new behavior by changing the ``ProcessLauncherType`` parameter in the simulation configuration file. The default value of this parameter is ``Basic``, which will instruct NRPCoreSim to use :ref:`ProcessLauncherBasic <doxid-class_process_launcher_basic>`.

An example of a new process launcher is shown here. Note the ``LAUNCH_CMD#`` is always a Launch Command. More information about launch commands can be found in this :ref:`page <doxid-launch_command>`.

.. ref-code-block:: cpp

	// Create a new ProcessLauncher. This launcher can be selected by changing the ProcessLauncherType parameter in the simulation configuration file to "NewBehavior"
	class NewProcessLauncher
	    : public :ref:`ProcessLauncher <doxid-class_process_launcher>`<NewProcessLauncher, "NewBehavior", LAUNCH_CMD1, LAUNCH_CMD2, ...>
	{}

Add it to the MainProcessLauncherManager along with the already existing basic :ref:`ProcessLauncher <doxid-class_process_launcher>` :

.. ref-code-block:: cpp

	...
	// Include header with defined class
	#include "new_process_launcher.h"
	...
	using :ref:`MainProcessLauncherManager <doxid-class_process_launcher_manager>` = :ref:`ProcessLauncherManager\<ProcessLauncherBasic, NewProcessLauncher> <doxid-class_process_launcher_manager>`;

All ProcessLaunchers must contain at least one Launch Command.

As a final note, :ref:`ProcessLauncher <doxid-class_process_launcher>` can also be used in NRPCore experiments to launch arbitrary commands unrelated to Engines. These commands will be managed by NRPCoreSim in the same way as Engine processes. For information on how to use this feature in experiments see :ref:`here <doxid-process_launcher_schema>`.