lsh

• Index

Contents

• Functions
• Output
• Children methods

Modules

• lsh
• lsh.cmd
• lsh.cmd.child
• lsh.cmd.status
• lsh.fio
• lsh.fio.fh
• lsh.memfd
• lsh.path
• lsh.pipeline
• lsh.pipeline.children
• lsh.pipeline.pstatus
• lsh.stringx
• lsh.time

Topics

• README

Examples

• cmd.lua
• libc.lua
• memfd.lua
• path.lua
• pipeline.lua
• stringx.lua
• test.lua

Module lsh.pipeline.children

Representation of a running or exited pipeline's children processes.

Functions

new (pl)

Constructs the new children handle struct from cmds defined in pipeline instance and executes it.

Output

output

The output of a finished process.

Children methods

type ()	Returns the instance type.
kill (self[, signal])	Send a signal to all child processes.
ids (self)	Returns the array of OS-assigned process identifiers of all child processes.
wait (self)	Waits for all child proceses to exit completely, returning the pstatus that it exited with.
try_wait (self)	Attempts to collect the exit statuses of the child processes if they have already exited.
wait_with_output (self)	Simultaneously waits for all child processes to exit and collect all remaining output on the stdout/stderr handles, returning an output struct.

Functions

new (pl)

Constructs the new children handle struct from cmds defined in pipeline instance and executes it.

Input cmd is cloned and contained inside child instance to be available for introspection.

There is no need to use this method directly, see lsh.pipeline.run and lsh.pipeline.spawn for practical program execution.

Parameters:

• pl lsh.pipeline

Returns:

lsh.pipeline.children children

Output

output

The output of a finished process.

This is returned by either the pipeline.output method, or the wait_with_output method of a children instance.

Fields:

• stdout stdout of pipeline instance (if any)
• stderr stderr of pipeline instance (if any)
• status pstatus struct

Children methods

type ()

Returns the instance type.

Returns:

the string "children"

kill (self[, signal])

Send a signal to all child processes.

See: lsh.cmd.child.kill

Parameters:

• self lsh.pipeline.children
• signal string signal name (optional)

Returns:

1. bool signal status
2. string error message

Usage:

local sh = require 'lsh'

local children = sh.pipeline():add('sleep', 10):spawn()
child:kill()

ids (self)

Returns the array of OS-assigned process identifiers of all child processes.

Parameters:

• self lsh.pipeline.children

Returns:

table array of process identifiers

wait (self)

Waits for all child proceses to exit completely, returning the pstatus that it exited with.

This function will continue to have the same return value after it has been called at least once.

Parameters:

• self lsh.pipeline.children

Returns:

lsh.pipeline.pstatus pstatus struct

try_wait (self)

Attempts to collect the exit statuses of the child processes if they have already exited.

This function will not block the calling thread and will only check to see if the child processes have exited or not. If the child processes have exited then process IDs are reaped. This function is guaranteed to repeatedly return a successful exit status so long as the child processes have already exited.

If all child processes have exited, then pstatus is returned. If the exit statuses are not available at this time then false is returned.

Parameters:

• self lsh.pipeline.children

Returns:

lsh.pipeline.pstatus pstatus struct

Or

false

Or

1. nil
2. err

wait_with_output (self)

Simultaneously waits for all child processes to exit and collect all remaining output on the stdout/stderr handles, returning an output struct.

By default, stdin, stdout and stderr are inherited from the parent. In order to capture the output into output it is necessary to create new memfd instances between parent and child. Use stdout(sh.memfd()) or stderr(sh.memfd()), respectively.

Parameters:

• self lsh.pipeline.children

Returns:

lsh.cmd.children.output output struct

Or

1. nil
2. err