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
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

Execute 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.

Spawning processes

type alias SpawnOptions =
{ shell : Shell
, workingDirectory : WorkingDirectory
, environmentVariables : EnvironmentVariables
, runDuration : RunDuration
, connection : Connection
}

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 close the new process is connected to the application
type Connection
= Integrated
| Ignored
| Detached

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 and that the application will wait for its termination.
  • Ignored means that stdin, stdout and stderr is seperate but that the application will still wait for its termination.
  • Detached means that the application can terminate even if the spawned process is still running.
defaultSpawnOptions : SpawnOptions

A nice default set of options for the spawn function.
spawn :
Permission
-> String
-> Array String
-> SpawnOptions
-> Task x Id

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" ] defaultSpawnOptions
spawnWithDefaultOptions : Permission -> String -> Array String -> Task x Id

Same as [spawn], but with defaultSpawnOptions passed in as options.
spawnAndNotifyOnExit :
Permission
-> (Int -> msg)
-> String
-> Array String
-> SpawnOptions
-> Cmd msg

Spawn a process with the given name, arguments and options, and let it run in the background. When the process completes, trigger the given message with the exit code.

spawnAndNotifyOnExit permission SleepFinished "sleep" [ "2" ] defaultSpawnOptions