ChildProcess

A running program is a process. A process spawned from another process is known as a child process.

This module allow you to spawn child processes.

Initialization

type Permission

This value represents the permission to spawn child processes.

Only code you trust should have access to this value.
initialize : Task Permission

Initialize the ChildProcess subsystem, which gains you the permission to spawn child processes.

Running processes

type alias RunOptions =
{ shell : Shell
, workingDirectory : WorkingDirectory
, environmentVariables : EnvironmentVariables
, maximumBytesWrittenToStreams : Int
, runDuration : RunDuration
}

Options to customize the execution of a child process created with run.

  • shell is the shell to run the process in (if any)
  • workingDirectory specifies the working directory of the process
  • environmentVariables specifies the environment variables the process has access to
  • maximumBytesWrittenToStreams specifies an upper bound of bytes that can be returned from the process
  • runDuration specifies a maximum amount of time a process is allowed to run before exiting
defaultRunOptions : RunOptions

A nice default set of options for the run function
type Shell
= NoShell
| DefaultShell
| CustomShell String

Which shell should the child process run in?

  • NoShell executes the process directly, without any shell. A little bit more efficient, but you lose some convinience as shell behaviour (like glob patterns) isn't available for arguments
  • DefaultShell executes the process in the default shell for the currently running system
  • CustomShell executes the process in the specified shell.
type WorkingDirectory
= InheritWorkingDirectory
| SetWorkingDirectory String

What should be the working directory of the process?

  • InheritWorkingDirectory inherits the working directory from its parent
  • SetWorkingDirectory sets the working directory to the specified value (doesn't affect parent)
type EnvironmentVariables
= InheritEnvironmentVariables
| MergeWithEnvironmentVariables (Dict String String)
| ReplaceEnvironmentVariables (Dict String String)

What should be the environment variables of the process?

  • InheritEnvironmentVariables inherits the environment variables from its parent
  • MergeWithEnvironmentVariables inherits the environment variables from its parent, with the specified modifications
  • ReplaceEnvironmentVariables sets the environment variables to the specified dictionary
type RunDuration
= NoLimit
| Milliseconds Int

How long is the process allowed to run before it's forcefully terminated?

  • NoLimit means it can run forever
  • Milliseconds sets the limit to the specified number of milliseconds
run :
Permission
-> String
-> Array String
-> RunOptions
-> Task FailedRun SuccessfulRun

Execute a process with a given name, arguments and options, and wait for it to terminate.

run permission "cat" [ "my_file" ] defaultRunOptions
type alias SuccessfulRun = { stdout : Bytes, stderr : Bytes }

Return value when a process terminates without error
type FailedRun
= InitError ({ program : String, arguments : Array String, errorCode : String })
| ProgramError ({ exitCode : Int, stdout : Bytes, stderr : Bytes })

Return value when a process terminates due to an error.

Running a child process can either fail due to a system error, like the requested program not being installed, or due to an error in the program itself, like calling it with arguments it doesn't recognize.

Spawning processes

spawn :
Permission
-> String
-> Array String
-> SpawnOptions msg
-> Cmd msg

Spawn a process with a given name, arguments and options, and let it run in the background. This is mostly helpful for starting long-running processes.

spawn permission "tail" [ "my_file" ] mySpawnOptions
type alias SpawnOptions msg =
{ shell : Shell
, workingDirectory : WorkingDirectory
, environmentVariables : EnvironmentVariables
, runDuration : RunDuration
, connection : Connection msg
, onExit : Int -> msg
}

Options to customize the execution of a child process created with spawn.

  • shell is the shell to run the process in (if any)
  • workingDirectory specifies the working directory of the process
  • environmentVariables specifies the environment variables the process has access to
  • runDuration specifies a maximum amount of time a process is allowed to run before exiting
  • connection let's you specify how the new process is connected to the application, and which message to receive when the process starts
  • onExit is the message that is triggered when the process exits. The message receives the exit code.
type alias StreamIO =
{ input : Writable Bytes
, output : Readable Bytes
, error : Readable Bytes
}

Streams that can be used to communicate with a spawned child process.
type Connection msg
= Integrated (Id -> msg)
| External ({ processId : Id, streams : StreamIO } -> msg)
| Ignored (Id -> msg)
| Detached (Id -> msg)

What relation should the newly spawned process have with the running application?

  • Integrated means that the spawned process shares the stdin, stdout and stderr streams.
  • External means that a new streams are created for stdin, stdout and stderr and passed to the application, which can use those streams for communicating with the new process.
  • Ignored means the same as External, but anything written to stdin, stdout and stderr is discarded/ignored.
  • Detached means the same as Ignored, but that the application will exit even if the child process hasn't finished executing.
defaultSpawnOptions : Connection msg -> (Int -> msg) -> SpawnOptions msg

A nice default set of options for the spawn function.