Module

Node.ChildProcess

This module contains various types and functions to allow you to spawn and interact with child processes.

It is intended to be imported qualified, as follows:

import Node.ChildProcess (ChildProcess, CHILD_PROCESS)
import Node.ChildProcess as ChildProcess

The Node.js documentation forms the basis for this module and has in-depth documentation about runtime behaviour.

#Handle

data Handle

A handle for inter-process communication (IPC).

#ChildProcess

newtype ChildProcess

Opaque type returned by spawn, fork and exec. Needed as input for most methods in this module.

#stdin

stdin :: ChildProcess -> Writable ()

The standard input stream of a child process. Note that this is only available if the process was spawned with the stdin option set to "pipe".

#stdout

stdout :: ChildProcess -> Readable ()

The standard output stream of a child process. Note that this is only available if the process was spawned with the stdout option set to "pipe".

#stderr

stderr :: ChildProcess -> Readable ()

The standard error stream of a child process. Note that this is only available if the process was spawned with the stderr option set to "pipe".

#pid

pid :: ChildProcess -> Pid

The process ID of a child process. Note that if the process has already exited, another process may have taken the same ID, so be careful!

#connected

connected :: ChildProcess -> Effect Boolean

Indicates whether it is still possible to send and receive messages from the child process.

#kill

kill :: Signal -> ChildProcess -> Effect Unit

Send a signal to a child process. In the same way as the unix kill(2) system call, sending a signal to a child process won't necessarily kill it.

The resulting effects of this function depend on the process and the signal. They can vary from system to system. The child process might emit an "error" event if the signal could not be delivered.

#send

send :: forall props. Record props -> Handle -> ChildProcess -> Effect Boolean

Send messages to the (nodejs) child process.

See the node documentation for in-depth documentation.

#disconnect

disconnect :: ChildProcess -> Effect Unit

Closes the IPC channel between parent and child.

#Error

type Error = { code :: String, errno :: String, syscall :: String }

An error which occurred inside a child process.

#toStandardError

toStandardError :: Error -> Error

Convert a ChildProcess.Error to a standard Error, which can then be thrown inside an Effect or Aff computation (for example).

#Exit

data Exit

Specifies how a child process exited; normally (with an exit code), or due to a signal.

Constructors

Instances

#onExit

onExit :: ChildProcess -> (Exit -> Effect Unit) -> Effect Unit

Handle the "exit" signal.

#onClose

onClose :: ChildProcess -> (Exit -> Effect Unit) -> Effect Unit

Handle the "close" signal.

#onDisconnect

onDisconnect :: ChildProcess -> Effect Unit -> Effect Unit

Handle the "disconnect" signal.

#onMessage

onMessage :: ChildProcess -> (Foreign -> Maybe Handle -> Effect Unit) -> Effect Unit

Handle the "message" signal.

#onError

onError :: ChildProcess -> (Error -> Effect Unit) -> Effect Unit

Handle the "error" signal.

#spawn

spawn :: String -> Array String -> SpawnOptions -> Effect ChildProcess

Spawn a child process. Note that, in the event that a child process could not be spawned (for example, if the executable was not found) this will not throw an error. Instead, the ChildProcess will be created anyway, but it will immediately emit an 'error' event.

#SpawnOptions

type SpawnOptions = { cwd :: Maybe String, detached :: Boolean, env :: Maybe (Object String), gid :: Maybe Gid, stdio :: Array (Maybe StdIOBehaviour), uid :: Maybe Uid }

Configuration of spawn. Fields set to Nothing will use the node defaults.

#defaultSpawnOptions

defaultSpawnOptions :: SpawnOptions

A default set of SpawnOptions. Everything is set to Nothing, detached is false and stdio is ChildProcess.pipe.

#exec

exec :: String -> ExecOptions -> (ExecResult -> Effect Unit) -> Effect ChildProcess

Similar to spawn, except that this variant will:

  • run the given command with the shell,
  • buffer output, and wait until the process has exited before calling the callback.

Note that the child process will be killed if the amount of output exceeds a certain threshold (the default is defined by Node.js).

#execFile

execFile :: String -> Array String -> ExecOptions -> (ExecResult -> Effect Unit) -> Effect ChildProcess

Like exec, except instead of using a shell, it passes the arguments directly to the specified command.

#ExecOptions

type ExecOptions = { cwd :: Maybe String, encoding :: Maybe Encoding, env :: Maybe (Object String), gid :: Maybe Gid, killSignal :: Maybe Signal, maxBuffer :: Maybe Int, shell :: Maybe String, timeout :: Maybe Number, uid :: Maybe Uid }

Configuration of exec. Fields set to Nothing will use the node defaults.

#ExecResult

type ExecResult = { error :: Maybe Error, stderr :: Buffer, stdout :: Buffer }

The combined output of a process calld with exec.

#defaultExecOptions

defaultExecOptions :: ExecOptions

A default set of ExecOptions. Everything is set to Nothing.

#execSync

execSync :: String -> ExecSyncOptions -> Effect Buffer

Generally identical to exec, with the exception that the method will not return until the child process has fully closed. Returns: The stdout from the command.

#execFileSync

execFileSync :: String -> Array String -> ExecSyncOptions -> Effect Buffer

Generally identical to execFile, with the exception that the method will not return until the child process has fully closed. Returns: The stdout from the command.

#ExecSyncOptions

type ExecSyncOptions = { cwd :: Maybe String, env :: Maybe (Object String), gid :: Maybe Gid, input :: Maybe String, killSignal :: Maybe Signal, maxBuffer :: Maybe Int, stdio :: Array (Maybe StdIOBehaviour), timeout :: Maybe Number, uid :: Maybe Uid }

#defaultExecSyncOptions

#fork

fork :: String -> Array String -> Effect ChildProcess

A special case of spawn for creating Node.js child processes. The first argument is the module to be run, and the second is the argv (command line arguments).

#StdIOBehaviour

data StdIOBehaviour

Behaviour for standard IO streams (eg, standard input, standard output) of a child process.

  • Pipe: creates a pipe between the child and parent process, which can then be accessed as a Stream via the stdin, stdout, or stderr functions.
  • Ignore: ignore this stream. This will cause Node to open /dev/null and connect it to the stream.
  • ShareStream: Connect the supplied stream to the corresponding file descriptor in the child.
  • ShareFD: Connect the supplied file descriptor (which should be open in the parent) to the corresponding file descriptor in the child.

Constructors

#pipe

pipe :: Array (Maybe StdIOBehaviour)

Create pipes for each of the three standard IO streams.

#inherit

inherit :: Array (Maybe StdIOBehaviour)

Share stdin with stdin, stdout with stdout, and stderr with stderr.

#ignore

ignore :: Array (Maybe StdIOBehaviour)

Ignore all streams.

Modules