.. index:: pair: page; Process Launcher Schema
.. _doxid-process_launcher_schema:

Process Launcher Schema
=======================

:ref:`ProcessLauncher <doxid-class_process_launcher>` is in responsible for spawning and managing external processes in NRPCore simulations. Typically it is used to bring up Engine server processes, but it can be used to execute arbitrary commands. The schema listed below allows user to specify which commands should be executed in a given NRPCore experiment.

The :ref:`Simulation Schema <doxid-simulation_schema>` contains a parameter *ExternalProcesses* of type array which elements are of type ``json://nrp-core/process_launcher.json#:ref:`ProcessLauncher <doxid-class_process_launcher>```, i.e, the type defined in the schema listed below. This parameter can be use to specify which commands should be launched alongside with the experiment.

Below is a list of all the parameters needed to configure a :ref:`ProcessLauncher <doxid-class_process_launcher>`.



.. _doxid-process_launcher_schema_1process_launcher_schema_parameters:

Parameters
~~~~~~~~~~

===============  ==============================  ======  ==========================  ========  =====  
Name             Description                     Type    Default                     Required  Array  
===============  ==============================  ======  ==========================  ========  =====  
ProcCmd          Process Launch command          string                              X                
ProcStartParams  Process Start Parameters        string                                        X      
ProcEnvParams    Process Environment Parameters  string                                        X      
                                                 object  {"LaunchType":"BasicFork"}                   
===============  ==============================  ======  ==========================  ========  =====





.. _doxid-process_launcher_schema_1process_launcher_schema_example:

Example
~~~~~~~

Below is listed an example experiment configuration using :ref:`ProcessLauncher <doxid-class_process_launcher>` to launch a "custom" command in a forked process.

.. ref-code-block:: cpp

	{
	    "SimulationName": "test_sim",
	    "SimulationDescription": "Just writting a greetings message from a forked process using an environment variable",
	    "SimulationTimeout": 1,
	    "ExternalProcesses" : [
	        {
	            "ProcCmd": "export MSG=$GREETINGS_MSG && echo $MSG",
	            "ProcEnvParams": ["GREETINGS_MSG=\"Hello World!\""]
	        }
	    ]
	}





.. _doxid-process_launcher_schema_1process_launcher_schema_schema:

Schema
~~~~~~

.. ref-code-block:: cpp

	{
	  "$schema": "http://json-schema.org/draft-07/schema#",
	  "title": "Process Launcher",
	  "description": "Process Launcher configuration schema",
	  "$id": "#ProcessLauncher",
	  "type": "object",
	  "properties" : {
	    "ProcCmd" : {
	      "type" : "string",
	      "description": "Process Launch command"
	    },
	    "ProcStartParams" : {
	      "type" : "array",
	      "items": {"type" : "string"},
	      "description": "Process Start Parameters"
	    },
	    "ProcEnvParams" : {
	      "type" : "array",
	      "items": {"type" : "string"},
	      "description": "Process Environment Parameters"
	    },
	    "LaunchCommand" : {
	      "$schema": "http://json-schema.org/draft-07/schema#",
	      "title": "Launch Command",
	      "description": "LaunchCommand that will be used to launch the process",
	      "$id": "#LaunchCommand",
	      "type":"object",
	      "oneOf":[
	        { "$ref": "json://nrp-core/launch_commands/empty_launch_cmd.json#/empty_launch_cmd" },
	        { "$ref": "json://nrp-core/launch_commands/basicfork_cmd.json#/basicfork_cmd" },
	        { "$ref": "json://nrp-core/launch_commands/docker_launcher_cmd.json#/docker_launcher_cmd" }
	      ],
	      "default":{"LaunchType":"BasicFork"}
	    }
	  },
	  "required": ["ProcCmd"]
	}