exexec

v0.2.0

exexec v0.2.0 Exexec View Source

Execute and control OS processes from Elixir.

An idiomatic Elixir wrapper for Serge Aleynikov's excellent erlexec, Exexec provides an Elixir interface as well as some nice Elixir-y goodies on top.

Link to this section Summary

Types

command()
command_option()
command_options()
exec_option()
exec_options()
exit_code()
gid()
on_run()
os_pid()
output_device()
output_device_option()
output_file_option()
output_file_options()
signal()

Functions

kill(pid, signal)

Send signal to pid.

manage(os_pid, options \\ [])

Start an Exexec process to manage existing os_pid with options options.

os_pid(pid)

Returns the OS pid for Exexec process pid.

pid(os_pid)

Returns the Exexec pid for os_pid.

run(command, options \\ [])

Run an external command with options.

run_link(command, options \\ [])

Run an external command with options, linking to the current process.

send(pid, data)

Send data to the stdin of pid.

set_gid(os_pid, gid)

Change group ID of os_pid to gid.

signal(signal)

Convert integer signal to atom, or return signal.

start()

Start Exexec.

start(options)

Start Exexec with options.

start_link()

Start Exexec and link to calling process.

start_link(options)

Start Exexec with options and link to calling process.

status(exit_code)

Interpret exit_code.

stop(pid)

Stop pid.

stop_and_wait(pid, timeout \\ 5000)

Stop pid and wait for it to exit for timeout milliseconds.

which_children()

Return a list of OS pids managed by Exexec.

Link to this section Types

Link to this type

command() View Source 
command() :: String.t() | [Path.t() | [String.t()]]

Link to this type

command_option() View Source 
command_option() ::
  {:monitor, boolean()}
  | {:sync, boolean()}
  | {:executable, Path.t()}
  | {:cd, Path.t()}
  | {:env, %{optional(String.t()) => String.t()}}
  | {:kill_command, String.t()}
  | {:kill_timeout, non_neg_integer()}
  | {:kill_group, boolean()}
  | {:group, String.t()}
  | {:user, String.t()}
  | {:success_exit_code, exit_code()}
  | {:nice, -20..20}
  | {:stdin, boolean() | :null | :close | Path.t()}
  | {:stdout, :stderr | output_device_option()}
  | {:stderr, :stdout | output_device_option()}
  | {:pty, boolean()}

Link to this type

command_options() View Source 
command_options() :: [command_option()]

Link to this type

exec_option() View Source 
exec_option() ::
  {:debug, boolean() | non_neg_integer()}
  | {:root, boolean()}
  | {:verbose, boolean()}
  | {:args, [String.t()]}
  | {:alarm, non_neg_integer()}
  | {:user, String.t()}
  | {:limit_users, [String.t()]}
  | {:port_path, Path.t()}
  | {:env, %{optional(String.t()) => String.t()}}

Link to this type

exec_options() View Source 
exec_options() :: [exec_option()]

Link to this type

exit_code() View Source 
exit_code() :: non_neg_integer()

Link to this type

gid() View Source 
gid() :: non_neg_integer()

Link to this type

on_run() View Source 
on_run() ::
  {:ok, pid(), os_pid()}
  | {:ok, [{output_device(), [binary()]}]}
  | {:error, any()}

Link to this type

os_pid() View Source 
os_pid() :: non_neg_integer()

Link to this type

output_device() View Source 
output_device() :: :stdout | :stderr

Link to this type

output_device_option() View Source 
output_device_option() ::
  boolean()
  | :null
  | :close
  | :print
  | Path.t()
  | {Path.t(), output_file_options()}
  | pid()
  | (output_device(), os_pid(), binary() -> any())

Link to this type

output_file_option() View Source 
output_file_option() :: {:append, boolean()} | {:mode, non_neg_integer()}

Link to this type

output_file_options() View Source 
output_file_options() :: [output_file_option()]

Link to this type

signal() View Source 
signal() :: pos_integer()

Link to this section Functions

Link to this function

kill(pid, signal) View Source 
kill(pid() | os_pid() | port(), signal()) :: :ok | {:error, any()}

Send signal to pid.

pid can be an Exexec pid, OS pid, or port.

Link to this function

manage(os_pid, options \\ []) View Source 
manage(os_pid() | port(), command_options()) ::
  {:ok, pid(), os_pid()} | {:error, any()}

Start an Exexec process to manage existing os_pid with options options.

os_pid can also be a port.

Link to this function

os_pid(pid) View Source 
os_pid(pid()) :: {:ok, os_pid()} | {:error, any()}

Returns the OS pid for Exexec process pid.

Link to this function

pid(os_pid) View Source 
pid(os_pid()) :: {:ok, pid()} | {:error, any()}

Returns the Exexec pid for os_pid.

Link to this function

run(command, options \\ []) View Source 
run(command(), command_options()) :: on_run()

Run an external command with options.

Link to this function

run_link(command, options \\ []) View Source 
run_link(command(), command_options()) :: on_run()

Run an external command with options, linking to the current process.

If the external process exits with code 0, the linked process will not exit.

Link to this function

send(pid, data) View Source 
send(pid() | os_pid(), binary() | :eof) :: :ok

Send data to the stdin of pid.

pid can be an Exexec pid or an OS pid.

Link to this function

set_gid(os_pid, gid) View Source 
set_gid(os_pid(), gid()) :: :ok | {:error, any()}

Change group ID of os_pid to gid.

Link to this function

signal(signal) View Source 
signal(signal()) :: atom() | integer()

Convert integer signal to atom, or return signal.

Link to this function

start() View Source 
start() :: {:ok, pid()} | {:error, any()}

Start Exexec.

Link to this function

start(options) View Source 
start(exec_options()) :: {:ok, pid()} | {:error, any()}

Start Exexec with options.

Link to this function

start_link() View Source 
start_link() :: {:ok, pid()} | {:error, any()}

Start Exexec and link to calling process.

Link to this function

start_link(options) View Source 
start_link(exec_options()) :: {:ok, pid()} | {:error, any()}

Start Exexec with options and link to calling process.

Link to this function

status(exit_code) View Source 
status(exit_code()) ::
  {:status, signal()} | {:signal, signal() | :atom, boolean()}

Interpret exit_code.

If the program exited by signal, returns {:signal, signal, core} where signal is the atom or integer signal and core is whether a core file was generated.

Link to this function

stop(pid) View Source 
stop(pid() | os_pid() | port()) :: :ok | {:error, any()}

Stop pid.

pid can be an Exexec pid, OS pid, or port.

The OS process is terminated gracefully. If :kill_command was specified, that command is executed and a timer is started. If the process doesn't exit immediately, then by default after 5 seconds SIGKILL will be sent to the process.

Link to this function

stop_and_wait(pid, timeout \\ 5000) View Source 
stop_and_wait(pid() | os_pid() | port(), integer()) :: :ok | {:error, any()}

Stop pid and wait for it to exit for timeout milliseconds.

See Exexec.stop/1.

Link to this function

which_children() View Source 
which_children() :: [os_pid()]

Return a list of OS pids managed by Exexec.