Process

spawn

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

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.

Parameters

state

the server's initial state

Returns 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()

run

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

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.

Parameters

command

the executable to run

args

its arguments, one per element

Returns 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")

stream

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

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.

Parameters

command

the executable to run

args

its arguments, one per element

Returns 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

exec

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

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.

Parameters

command

the executable to run

args

its arguments, one per element

Returns 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

self

self : Pid

Returns the calling process's own Pid.

Returns this process's identifier

Examples

Telling another process where to answer

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

exit

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

Sends an exit signal carrying reason to pid.

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

Parameters

pid

the process to signal

reason

the exit reason

Examples

Process.exit(worker, :shutdown)

register

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

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

Parameters

pid

the process to register

name

the name to register it under

Examples

Process.register(Process.self, :main)

whereIs

whereIs(name: Atom) -> Pid?

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

Parameters

name

the registered name

Returns 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) }

named

named(name: String) -> Process.Shared<X>

The handle on the slot called name. Nothing is stored or read until put or get.

Parameters

name

the slot's name

Returns a handle on the slot

sleep

sleep(duration: Duration) -> Void

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

start

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

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.

Parameters

f

the work to run

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

awaitAll

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

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.

Parameters

tasks

the tasks to wait for

Returns 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 })