ChildProcess

A running program is a process. A process spawned from another process is known as a child process. Child processes terminate along with their parent.

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.

Options

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

Options to customize the execution of a child process.

  • 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

Spawning processes

type alias FailedRun = { exitCode : Int, stdout : Bytes, stderr : Bytes }

Return value when a process terminates due to an error

The exit code provides some hint of what went wrong, but what it means depends on the program which was run.
type alias SuccessfulRun = { stdout : Bytes, stderr : Bytes }

Return value when a process terminates without error
run :
Permission
-> String
-> Array String
-> RunOptions
-> Task FailedRun SuccessfulRun

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

run permission "cat" [ "my_file" ] defaultRunOptions
runWithDefaultOptions :
Permission
-> String
-> Array String
-> Task FailedRun SuccessfulRun

Same as run, but with defaultRunOptions passed in as options.