class_docstr: A process launcher that invokes the current script as many times as desired in a single node.
  
  This launcher needs to be invoked on each node.
  In its default behavior, the main process in each node then spawns N-1 child processes via :func:`subprocess.Popen`,
  where N is the number of devices (e.g. GPU) per node. It is very similar to how :mod:`torch.distributed.run`
  launches processes.
  
  For example, if the script gets invoked with the command
  
  .. code-block:: bash
  
      python train.py --devices 4
  
  The launcher will create three additional subprocesses that get called like so:
  
  .. code-block:: bash
  
      LOCAL_RANK=1 python train.py --devices 4
      LOCAL_RANK=2 python train.py --devices 4
      LOCAL_RANK=3 python train.py --devices 4
  
  It is implied that the main process which launched the others has ``LOCAL_RANK=0``.
  Beside the local rank, the following other environment variables also get set, but unlike the local rank, these
  get determined by the cluster environment:
  
  1. `MASTER_ADDR`: The IP address of the main node.
  2. `MASTER_PORT`: The port number of the main node through which all processes communicate.
  3. `NODE_RANK`: The index of the node the current process is running on. Ranges from 0 to ``num_nodes - 1``.
  4. `WORLD_SIZE`: The total number of processes across all nodes, i.e., ``num_processes * num_nodes``.
  
  Arguments:
      cluster_environment: A cluster environment that provides access to world size, node rank, etc.
      num_processes: The number of processes to launch in the current node.
      num_nodes: The total number of nodes that participate in this process group.
class_docstr_tok: ["A","process","launcher","that","invokes","the","current","script","as","many","times","as","desired","in","a","single","node",".","This","launcher","needs","to","be","invoked","on","each","node",".","In","its","default","behavior",",","the","main","process","in","each","node","then","spawns","N-1","child","processes","via",":","func",":","`","subprocess.Popen","`",",","where","N","is","the","number","of","devices","(","e.g",".","GPU",")","per","node",".","It","is","very","similar","to","how",":","mod",":","`","torch.distributed.run","`","launches","processes",".","For","example",",","if","the","script","gets","invoked","with","the","command","..","code-block",":",":","bash","python","train.py","--","devices","4","The","launcher","will","create","three","additional","subprocesses","that","get","called","like","so",":","..","code-block",":",":","bash","LOCAL_RANK=1","python","train.py","--","devices","4","LOCAL_RANK=2","python","train.py","--","devices","4","LOCAL_RANK=3","python","train.py","--","devices","4","It","is","implied","that","the","main","process","which","launched","the","others","has","``","LOCAL_RANK=0","``",".","Beside","the","local","rank",",","the","following","other","environment","variables","also","get","set",",","but","unlike","the","local","rank",",","these","get","determined","by","the","cluster","environment",":","1",".","`","MASTER_ADDR","`",":","The","IP","address","of","the","main","node",".","2",".","`","MASTER_PORT","`",":","The","port","number","of","the","main","node","through","which","all","processes","communicate",".","3",".","`","NODE_RANK","`",":","The","index","of","the","node","the","current","process","is","running","on",".","Ranges","from","0","to","``","num_nodes","-","1","``",".","4",".","`","WORLD_SIZE","`",":","The","total","number","of","processes","across","all","nodes",",","i.e.",",","``","num_processes","*","num_nodes","``",".","Arguments",":","cluster_environment",":","A","cluster","environment","that","provides","access","to","world","size",",","node","rank",",","etc",".","num_processes",":","The","number","of","processes","to","launch","in","the","current","node",".","num_nodes",":","The","total","number","of","nodes","that","participate","in","this","process","group","."]
docstr: Creates new processes, then calls the given function.
  
  Arguments:
      function: A callback function to execute after all processes have been created.
          It is up to the implementation of this function to synchronize the processes, e.g., with barriers.
      *args: Optional positional arguments to be passed to the given function.
      trainer: Optional reference to the :class:`~lightning.pytorch.trainer.trainer.Trainer`.
      **kwargs: Optional keyword arguments to be passed to the given function.
docstr_tok: ["Creates","new","processes",",","then","calls","the","given","function",".","Arguments",":","function",":","A","callback","function","to","execute","after","all","processes","have","been","created",".","It","is","up","to","the","implementation","of","this","function","to","synchronize","the","processes",",","e.g.",",","with","barriers",".","*","args",":","Optional","positional","arguments","to","be","passed","to","the","given","function",".","trainer",":","Optional","reference","to","the",":","class",":","`","~lightning.pytorch.trainer.trainer.Trainer","`",".","*","*","kwargs",":","Optional","keyword","arguments","to","be","passed","to","the","given","function","."]
code: def launch(
      self,
      function: Callable,
      *args: Any,
      trainer: Optional["pl.Trainer"] = None,
      **kwargs: Any,
  ) -> Any:
      """Creates new processes, then calls the given function.
  
      Arguments:
          function: A callback function to execute after all processes have been created.
              It is up to the implementation of this function to synchronize the processes, e.g., with barriers.
          *args: Optional positional arguments to be passed to the given function.
          trainer: Optional reference to the :class:`~lightning.pytorch.trainer.trainer.Trainer`.
          **kwargs: Optional keyword arguments to be passed to the given function.
  
      """
      self.cluster_environment.validate_settings(
          num_devices=self.num_processes, num_nodes=self.num_nodes
      )
      if not self.cluster_environment.creates_processes_externally:
          self._call_children_scripts()
          _launch_process_observer(self.procs)
  
      _set_num_threads_if_needed(num_processes=self.num_processes)
      return function(*args, **kwargs)
  
file_path: pytorch-lightning/src/lightning/pytorch/strategies/launchers/subprocess_script.py
imports: import logging
  import os
  import subprocess
  from typing import Any, Callable, List, Optional
  from lightning_utilities.core.imports import RequirementCache
  from typing_extensions import override
  import lightning.pytorch
  from lightning.fabric.plugins import ClusterEnvironment
  from lightning.fabric.strategies.launchers.subprocess_script import _basic_subprocess_cmd, _hydra_subprocess_cmd, _launch_process_observer
  from lightning.fabric.utilities.distributed import _set_num_threads_if_needed
  from lightning.pytorch.strategies.launchers.launcher import _Launcher
  from lightning.pytorch.trainer.connectors.signal_connector import _SIGNUM
label_desc: Use image node_id 3 for calling the _SubprocessScriptLauncher obj's underlying member method code with example usage: obj.launch(function) and returns: function