porcelain v2.0.3 Porcelain.Process

Module for working with external processes launched with Porcelain.spawn/3 or Porcelain.spawn_shell/2.

Summary

Functions

__struct__()

A struct representing a wrapped OS processes which provides the ability to exchange data with it

alive?(process)

Check if the process is still running

await(process, timeout \\ :infinity)

Wait for the external process to terminate

send_input(process, data)

Send iodata to the process’s stdin

signal(process, sig)

Send an OS signal to the processes

stop(process)

Stops the process created with Porcelain.spawn/3 or Porcelain.spawn_shell/2. Also closes the underlying Erlang port

Types

signal :: :int | :kill | non_neg_integer

t :: %Porcelain.Process{err: term, out: term, pid: term}

Functions

__struct__()

A struct representing a wrapped OS processes which provides the ability to exchange data with it.

alive?(process)

Specs

alive?(t) :: true | false

Check if the process is still running.

await(process, timeout \\ :infinity)

Specs

await(t, non_neg_integer | :infinity) ::
  {:ok, Porcelain.Result.t} |
  {:error, :noproc | :timeout}

Wait for the external process to terminate.

Returns Porcelain.Result struct with the process’s exit status and output. Automatically closes the underlying port in this case.

If timeout value is specified and the external process fails to terminate before it runs out, atom :timeout is returned.

send_input(process, data)

Specs

send_input(t, iodata) :: iodata

Send iodata to the process’s stdin.

End of input is indicated by sending an empty message.

Caveat: when using Porcelain.Driver.Basic, it is not possible to indicate the end of input. You should stop the process explicitly using stop/1.

signal(process, sig)

Specs

signal(t, signal) :: signal

Send an OS signal to the processes.

No further communication with the process is possible after sending it a signal.

stop(process)

Specs

stop(t) :: true

Stops the process created with Porcelain.spawn/3 or Porcelain.spawn_shell/2. Also closes the underlying Erlang port.

May cause “broken pipe” message to be written to stderr.

Caveats

When using Porcelain.Driver.Basic, Porcelain will merely close the Erlang port connected to that process. This normally causes an external process to terminate provided that it is listening on its stdin. If not, the external process will continue running.

See http://erlang.org/pipermail/erlang-questions/2010-March/050227.html for some background info.

When using Porcelain.Driver.Goon, a SIGTERM signal will be sent to the external process. If it doesn’t terminate after :goon_stop_timeout seconds, a SIGKILL will be sent to the process.