Description
Runs a subprocess while concurrently draining bounded stdout and stderr. Bytes beyond each retained bound are discarded until EOF, so truncation cannot fill a child pipe and deadlock the command. Timeout or cancellation attempts hard structured cleanup and closes the parent descriptors before propagating the corresponding exception. Cleanup failures are suppressed in favor of that original exception. Cleanup is not part of the command-progress deadline and can delay exception delivery.
Error_Truncated
function Error_Truncated (Item : Result) return Boolean
Report whether stderr exceeded its retention bound.
Parameters
- Item
Completed capture result
Return value
True when stderr bytes were drained and discarded
Output_Truncated
function Output_Truncated (Item : Result) return Boolean
Report whether stdout exceeded its retention bound.
Parameters
- Item
Completed capture result
Return value
True when stdout bytes were drained and discarded
Result
type Result is private;
Complete bounded command result.
Run
function Run
(Item : Command;
Standard_Input : String := "";
Maximum_Output : Natural := 64 * 1_024;
Maximum_Error : Natural := 64 * 1_024;
Timeout : Duration := 30.0;
Token : access Flyology.Cancellation.Token := null) return Result
Run Item with optional stdin bytes and bounded output retention. The child stdin, stdout, and stderr pipes are progressed together; large input therefore cannot deadlock against simultaneous child output.
Parameters
- Item
Typed command to spawn
- Standard_Input
Complete stdin payload; EOF follows the payload
- Maximum_Output
Maximum retained stdout bytes
- Maximum_Error
Maximum retained stderr bytes
- Timeout
Shared monotonic command-progress deadline in seconds; negative is unlimited, synchronous spawn cannot be interrupted, and structured cleanup can extend return time
- Token
Optional cancellation source that must outlive the call
Return value
Reaped status and bounded output
Raised exceptions
- Spawn_Error
Command cannot be spawned
- Timeout_Error
The shared deadline expires
- Operation_Cancelled
Token is requested
- Process_Error
Process cleanup or observation fails
- Pipe_Error
Standard-stream progress fails
- Device_Error
Readiness polling fails
Standard_Error
function Standard_Error (Item : Result) return String
Return retained stderr bytes.
Parameters
- Item
Completed capture result
Return value
At most Maximum_Error bytes
Standard_Output
function Standard_Output (Item : Result) return String
Return retained stdout bytes.
Parameters
- Item
Completed capture result
Return value
At most Maximum_Output bytes
Status
function Status (Item : Result) return Exit_Status
Return the root process status.
Parameters
- Item
Completed capture result
Return value
Reaped exit status