# coro-spawn
Documentation for the coro-spawn module, version 3.0.3.
coro-spawn is single-function module that provides spawning child-processes with a synchronous interface making use of Lua coroutines.
Throughout the documentation, we will refer to the function return of this module as spawn. And it is obtained by calling require("coro-spawn").
# Installation
lit install creationix/coro-spawn
# Functions
# spawn(path, options)
Spawns a process of an executable at path using the provided options.
Note: The
optionsparameter is NOT optional, if you don’t want to provide any options, pass an empty table.
This method does not require running in a coroutine
# Parameters
| Param | Type | Description |
|---|---|---|
| path | string | The path of the executable to spawn. |
| options | table | Various options to control the process flow. See Spawn Options. |
# Returns
| Return | Type | Description | Provided On |
|---|---|---|---|
| result | Process/nil | Immediately returns with the proper streams and wrappers representing the process on success, otherwise nil. You probably want to call waitExit after this, see Process Fields. |
Always |
| err | string | A string explaining what went wrong when trying to spawn the process. | Failure Only |
# Examples
- List the previous directory contents to stdout
local proc, err = spawn('dir', { -- Spawn a process of the executable command "dir"
stdio = {0, 1, 2}, -- Use same stdio as the parent process
cwd = "../" -- Set the working directory to the previous directory
})
if not proc then -- Any errors?
print("Something went wrong!\n" .. err); return
end
local code, sig = proc.waitExit() -- Wait until the executed command finishes
print("\nFinished! exit-code: " .. code .. " exit-signal: " .. sig)
# Structures
# Spawn Options
A table that contains various configurations to control the process flow. All of the fields are optional.
# Fields
| Field | Type | Description |
|---|---|---|
| stdio | table | An array of listed values from index 1 to 3 where each index represents stdin, stdout, stderr in order. - If the value is a boolean, true means automatically create and assign a pipe for the corresponding handle, false and nil to ignore. - If the value is a pipe it will be assigned to the corresponding handle index as read-write stream. - If it’s a number, then the child process inherits that same zero-indexed fd from the parent process. |
| args | table | The command line arguments as a list of strings. |
| env | table | Set environment variables for the new process. |
| cwd | string | Set the current working directory for the sub-process. |
| uid | number | Set the child process’ user id. |
| gid | number | Set the child process’ group id. |
| verbatim | boolean | If true, don’t perform any kind of escaping when converting the argument list into a command line string. This option is only implemented on Windows systems. |
| detached | boolean | If true, spawn the child process in a detached state, this will make it a process group leader, and will effectively enable the child to keep running after the parent exits. |
| hide | boolean | If true, hide the subprocess console window that would normally be created. This option is only implemented on Windows systems. |
# Stdio
A table structure that represents a stdio handle, either a stdin, stdout or stderr, depending on the context.
# Fields
| Field | Type | Description | Provided On |
|---|---|---|---|
| handle | pipe | The uv pipe handle used to bind said stream. | Always |
| read | function | Reads data from a readable stream. See coro-channel reader. | stdout & stderr Only |
| write | function | Writes data to a writable stream. See coro-channel writer. | stdin Only |
# Process
A table structure that represents the the spawned process.
# Fields
| Field | Type | Description |
|---|---|---|
| handle | uv_process_t | The handle object of the spawned process. |
| pid | number | The PID process number assigned to the spawned process. |
| waitExit | function | Calling this will yield the current coroutine and resume it when the process finishes, will immediately returns if the process has already finished. Returns exitCode and exitSignal. |
| stdin | stdio/nil | The used stdin stream, or nil if no handle is created. |
| stdout | stdio/nil | The used stdout stream, or nil if no handle is created. |
| stderr | stdio/nil | The used stderr stream, or nil if no handle is created. |