CommandRunner v0.2.0 CommandRunner View Source

A server to run Unix shell commands.

Setup

The recommended way is to use CommandRunner as part of your application supervision tree.

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      {CommandRunner, name: MyApp.CommandRunner}
    ]

    Supervisor.start_link(
      children,
      strategy: :one_for_one,
      name: MyApp.Supervisor
    )
  end
end

Link to this section Summary

Types

server()

Type describing the command runner server.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

command_running?(server, ref)

Determines whether the command with the specified ref is running on the given server.

os_pid(server, ref)

Gets the OS process ID for the command with the specified ref on the given server.

run_command(server, cmd, opts \\ [], ref \\ make_ref())

Runs a particular command and returns the exit code and result data.

start_link(opts \\ [])

Starts a command runner.

stop(server, reason \\ :normal)

Stops the given command runner and terminates all running commands.

stop_command(server, ref)

Stops the command with the given ref and brutally kills the associated OS process.

Link to this section Types

server()

Specs

server() :: GenServer.server()

Type describing the command runner server.

Link to this section Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

command_running?(server, ref)

Specs

command_running?(server(), reference()) :: boolean()

Determines whether the command with the specified ref is running on the given server.

Examples

iex> ref = make_ref()
...> Task.async(fn ->
...>   CommandRunner.run_command(MyApp.Runner, "sleep 2", [], ref)
...> end)
...> CommandRunner.command_running?(MyApp.Runner, ref)
true

iex> CommandRunner.run_command(MyApp.Runner, "echo 'Hey!'", [], ref)
...> CommandRunner.command_running?(MyApp.Runner, ref)
false

os_pid(server, ref)

Specs

os_pid(server(), reference()) :: nil | non_neg_integer()

Gets the OS process ID for the command with the specified ref on the given server.

Examples

iex> ref = make_ref()
...> Task.async(fn ->
...>   CommandRunner.run_command(MyApp.Runner, "sleep 2", [], ref)
...> end)
...> CommandRunner.os_pid(MyApp.Runner, ref)
6458

iex> CommandRunner.run_command(MyApp.Runner, "echo 'Hey!'", [], ref)
nil

run_command(server, cmd, opts \\ [], ref \\ make_ref())

Specs

run_command(server(), binary(), Keyword.t(), reference()) ::
  {exit_code :: integer(), binary()} | :running | :stopped

Runs a particular command and returns the exit code and result data.

Options

:cd - Path to the working directory that the script is executed in.
:env - A map containing environment variables that are passed to the command.

Examples

iex> CommandRunner.run_command(MyApp.Runner, "echo 'Hello World'")
{0, "Hello World\n"}

iex> CommandRunner.run_command(MyApp.Runner, "which foo")
{1, ""}

Only one command with the same ref can run in a single command runner process.

iex> ref = make_ref()
...> Task.async(fn ->
...>   CommandRunner.run_command(MyApp.Runner, "sleep 2", [], ref)
...> end)
...> CommandRunner.run_command(MyApp.Runner, "echo 'Hello'", [], ref)
:running

Other processes may stop a command. The caller is notified about that.

iex> ref = make_ref()
...> task = Task.async(fn ->
...>   CommandRunner.run_command(MyApp.Runner, "sleep 2", [], ref)
...> end)
...> CommandRunner.stop_command(MyApp.Runner, ref)
...> Task.await(task)
:stopped

start_link(opts \\ [])

Specs

start_link(Keyword.t()) :: GenServer.on_start()

Starts a command runner.

stop(server, reason \\ :normal)

Specs

stop(server(), term()) :: :ok

Stops the given command runner and terminates all running commands.

stop_command(server, ref)

Specs

stop_command(server(), reference()) :: :ok

Stops the command with the given ref and brutally kills the associated OS process.

Example

iex> ref = make_ref()
...> Task.async(fn ->
...>   CommandRunner.run_command(MyApp.Runner, "sleep 2", [], ref)
...> end)
...> CommandRunner.stop_command(MyApp.Runner, ref)
:ok