Lacca (Lacca v0.1.7) View Source

Link to this section Summary

Functions

Returns true if the inferior process is alive, otherwise returns false.

Returns a specification to start this module under a supervisor.

Attempts to terminate the process immediately. Caller should expect that the process will not be gracefully terminated; similarly to calling SIGKILL on a POSIX operating system.

Returns {:ok, binary} which includes any data received from the child's stderr file descriptor. Note that the internal buffer is then cleared, such that subsequent reads will not return this same data again.

Returns {:ok, binary} which includes any data received from the child's stdout file descriptor. Note that the internal buffer is then cleared, such that subsequent reads will not return this same data again.

Starts the Lacca client without linking it to the caller's process.

Starts a Lacca client process which will run the executable located at exec_path with the specified command line arguments. The returned handle, of the form {:ok, pid}.

Shuts down the Lacca client process and closes the underlying resin port.

Returns :ok once the data has been sent to the underlying resin daemon.

Link to this section Functions

Specs

alive?(pid()) :: boolean()

Returns true if the inferior process is alive, otherwise returns false.

Returns a specification to start this module under a supervisor.

See Supervisor.

Specs

kill(pid()) :: :ok | {:error, String.t()}

Attempts to terminate the process immediately. Caller should expect that the process will not be gracefully terminated; similarly to calling SIGKILL on a POSIX operating system.

Specs

read_stderr(pid()) :: {:ok, String.t()}

Returns {:ok, binary} which includes any data received from the child's stderr file descriptor. Note that the internal buffer is then cleared, such that subsequent reads will not return this same data again.

Specs

read_stdout(pid()) :: {:ok, String.t()}

Returns {:ok, binary} which includes any data received from the child's stdout file descriptor. Note that the internal buffer is then cleared, such that subsequent reads will not return this same data again.

Specs

start(String.t(), [String.t()]) :: GenServer.on_start()

Starts the Lacca client without linking it to the caller's process.

See start_link/2 for more information.

Link to this function

start_link(exec_path, args)

View Source

Specs

start_link(String.t(), [String.t()]) :: GenServer.on_start()

Starts a Lacca client process which will run the executable located at exec_path with the specified command line arguments. The returned handle, of the form {:ok, pid}.

The pid represents the lacca client, which communicates w/ a resin daemon via an external Port. The program at exec_path is supervised by this resin daemon, and is referred to as the inferior process.

Note that stdout and stderr from the process are captured inside StringIO buffers internally. This data will remain in-memory until this server is either stopped, or the buffers are flushed using the respective API functions: read_stdout/1 and read_stderr/1.

Errors

This method will raise ArgumentError if the resin daemon cannot be found on your system's executable PATH. The configuration key located at :resin, :daemon_path can be used to force this process to run the daemon from a non-standard location.

Specs

stop(pid()) :: :ok

Shuts down the Lacca client process and closes the underlying resin port.

Note that resin will not ask the child process to terminate when shutting down. Calling this, without calling kill/1 et al. first, is essentially the same as just closing the stdin of the inferior process.

In the case that the inferior process does not exit upon reading EOF from stdin it will continue running unsupervised in the background. If you need to guarantee that the inferior process does not continue running: you must call kill/1, or similar, and wait for alive?/1 to return false before stopping the Lacca client.

Specs

write_stdin(pid(), String.t()) :: :ok | {:error, String.t()}

Returns :ok once the data has been sent to the underlying resin daemon.

Note that this function returns immediately after having sent the packet to the daemon, no guarantees as to the delivery to the child process are afforded. (i.e: the child may have closed its stdin prematurely, the child may have exited in the interim, it may be deadlocked and not processing stdin, etc.)