Processprelude

function spawn

Starts a process running the serving implementation attached to state's type, and returns a handle on it.

The state you pass is the server's initial state. Every slot in the serving block becomes a method on the returned Server, and each answers a Result: a call can time out or find the process gone.

spawn(state) : X -> Server<X>

Parameters

state X

the server's initial state

Returns: Server<X> — a handle on the running server

Examples

let api = Process.spawn(RateLimiter { remaining: 2 })
api.allowed?()   # => Ok(true)
api.allowed?()   # => Ok(true)
api.allowed?()   # => Ok(false)
api.stop()

function run

Runs an executable with an argument vector and captures its output.

No shell is involved, so nothing is glob-expanded or word-split and arguments containing spaces need no quoting. Output is captured as UTF-8 strings.

A non-zero exit status is still Ok: the program ran and said something, which is information, not a failure to run it. Error means the child could not be started at all.

run(command, args) : String -> [String] -> Result<ProcessResult, String>

Parameters

command String

the executable to run

args [String]

its arguments, one per element

Returns: Result<ProcessResult, String> — the captured result, or why it could not start

Examples

match Process.run("echo", ["hello"]) do
  Ok(r)    => IO.printLine(r.stdout.trim)   # prints: hello
  Error(e) => IO.printError(e)
end

A non-zero status is still Ok

Process.run("false", [])   # => Ok(ProcessResult { exitCode: 1, ... })

A command that does not exist is an Error

Process.run("no-such-command", [])   # => Error("executable not found")

Reading a command's output as data

Process.run("git", ["rev-parse", "HEAD"])
  .map { |r| r.stdout.trim }
  .or("unknown")

function stream

Runs an executable with the CALLER's stdout and stderr, so its output appears as it is produced rather than in one block when it exits.

Answers the exit code; nothing is captured: that is the trade, and it is what a long-running child a person is watching needs (kexhq/kex#187).

run remains the one to use when the output is data to be READ.

stream(command, args) : String -> [String] -> Result<Integer, String>

Parameters

command String

the executable to run

args [String]

its arguments, one per element

Returns: Result<Integer, String> — the exit code, or why it could not start

Examples

Watching a build as it runs

match Process.stream("make", ["-j8"]) do
  Ok(0)    => IO.printLine("build succeeded")
  Ok(code) => IO.printError("build failed with ${code}")
  Error(e) => IO.printError(e)
end

function exec

Runs an executable and returns just its exit code, discarding its output.

A command that could not be started answers 127, the shell's convention for "command not found". Use run when you need the output or want to tell a failed start from a failed run.

exec(command, args) : String -> [String] -> Integer

Parameters

command String

the executable to run

args [String]

its arguments, one per element

Returns: Integer — the exit code, or 127 if it could not start

Examples

Process.exec("true", [])              # => 0
Process.exec("false", [])             # => 1
Process.exec("no-such-command", [])   # => 127

Testing for a tool's presence

let haveGit = Process.exec("git", ["--version"]) == 0

function self

Returns the calling process's own Pid.

self() : Pid

Returns: Pid — this process's identifier

Examples

Telling another process where to answer

worker.send((Process.self, :ping))

function exit

Sends an exit signal carrying reason to pid.

:normal is the ordinary shutdown reason; :kill cannot be trapped.

exit(pid, reason) : Pid -> X -> Void

Parameters

pid Pid

the process to signal

reason X

the exit reason

Returns: Void —

Examples

Process.exit(worker, :shutdown)

function register

Registers pid under the atom name, so it can be found by name rather than by passing the Pid around.

register(pid, name) : Pid -> Atom -> Void

Parameters

pid Pid

the process to register

name Atom

the name to register it under

Returns: Void —

Examples

Process.register(Process.self, :main)

function whereis

Returns the Pid registered under name, or None when nothing is.

whereis(name) : Atom -> Pid?

Parameters

name Atom

the registered name

Returns: Pid? — the process, or None

Examples

Process.whereis(:main)        # => Just(pid)
Process.whereis(:not_there)   # => None

Sending to a named process if it is there

Process.whereis(:logger).map { |pid| pid.send(message) }

function sleep

Suspends for an elapsed duration. Negative durations are treated as zero.

sleep(duration) : Duration -> Void

function start

Runs f in a new process and returns a handle on its result.

The block starts immediately, so starting several tasks and awaiting them afterwards is what makes them run at the same time.

start(f) : Block<X> -> Task

Parameters

f Block<X>

the work to run

Returns: Task — a handle on the result

Examples

let t = Task.start do 1 + 1 end
t.await   # => 2

Two pieces of work at once

let a = Task.start do slowThing("a") end
let b = Task.start do slowThing("b") end
(a.await, b.await)

function awaitAll

Waits for every task in tasks and returns their results, in the order the tasks were given.

Each result comes back wrapped in a Result, so one task failing does not cost you the others' answers. That differs from Task.await on a single task, which hands back the value itself.

awaitAll(tasks) : [Task] -> [X]

Parameters

tasks [Task]

the tasks to wait for

Returns: [X] — their results, in order

Examples

let tasks = [Task.start do 1 end, Task.start do 2 end]
Task.awaitAll(tasks)   # => [Ok(1), Ok(2)]

Fanning work out over a list

let results = Task.awaitAll(paths.map { |p| Task.start do process(p) end })