exexec v0.0.1 Exexec

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.

Summary

Functions

Send signal to pid

Start an Exexec process to manage existing os_pid with options options

Returns the OS pid for Exexec process pid

Returns the Exexec pid for os_pid

Run an external command with options

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

Send data to the stdin of pid

Change group ID of os_pid to gid

Convert integer signal to atom, or return signal

Start Exexec

Start Exexec with options

Start Exexec and link to calling process

Start Exexec with options and link to calling process

Interpret exit_code

Stop pid

Stop pid and wait for it to exit for timeout milliseconds

Return a list of OS pids managed by Exexec

Types

command_option ::
  {:monitor, boolean} |
  {:sync, boolean} |
  {:executable, Path.t} |
  {:cd, Path.t} |
  {:env, %{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}
exec_option ::
  {:debug, boolean | non_neg_integer} |
  {:verbose, boolean} |
  {:args, [String.t]} |
  {:alarm, non_neg_integer} |
  {:user, String.t} |
  {:limit_users, [String.t]} |
  {:port_path, Path.t} |
  {:env, %{String.t => String.t}}
exit_code :: non_neg_integer
gid :: non_neg_integer
on_run ::
  {:ok, pid, os_pid} |
  {:ok, [{output_device, [binary]}]} |
  {:error, any}
os_pid :: non_neg_integer
output_device :: :stdout | :stderr
output_device_option ::
  boolean |
  :null |
  :close |
  :print |
  Path.t |
  {Path.t, output_file_options} |
  pid |
  (output_device, os_pid, binary -> any)
output_file_option ::
  {:append, boolean} |
  {:mode, non_neg_integer}
signal :: pos_integer

Functions

kill(pid, signal)

Specs

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

Send signal to pid.

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

manage(os_pid, options \\ [])

Specs

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.

os_pid(pid)

Specs

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

Returns the OS pid for Exexec process pid.

pid(os_pid)

Specs

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

Returns the Exexec pid for os_pid.

run(command, options \\ [])

Specs

Run an external command with options.

run_link(command, options \\ [])

Specs

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.

send(pid, data)

Specs

send(pid | os_pid, binary) :: :ok

Send data to the stdin of pid.

pid can be an Exexec pid or an OS pid.

set_gid(os_pid, gid)

Specs

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

Change group ID of os_pid to gid.

signal(signal)

Specs

signal(signal) :: atom | integer

Convert integer signal to atom, or return signal.

start()

Specs

start :: {:ok, pid} | {:error, any}

Start Exexec.

start(options)

Specs

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

Start Exexec with options.

start_link()

Specs

start_link :: {:ok, pid} | {:error, any}

Start Exexec and link to calling process.

start_link(options)

Specs

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

Start Exexec with options and link to calling process.

status(exit_code)

Specs

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.

stop(pid)

Specs

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.

stop_and_wait(pid, timeout \\ 5000)

Specs

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.

which_children()

Specs

which_children :: [os_pid]

Return a list of OS pids managed by Exexec.