linux/Process · windows/Process
Process is a cross-platform process wrapper with explicit creation, waiting, and termination operations. Creation reports success and failure through result strings. A failed creation leaves the wrapper uninitialized. Waiting and forced termination use assertion- and abort-based failure handling.
Command arguments and encoding
create consumes one non-empty command sequence whose first item is the program path.create also accepts one single String-like command value and treats it as a one-item command sequence.create2 accepts the same command sequence together with one options object.- Each command item is converted through
String view semantics before process creation.
- On Linux, the command sequence is passed as separate program-path and argument items.
- On Windows, process creation consumes one command-line string.
create uses the default Windows command-line encoding.create2 and toProcess2 may override that encoding through options.encodeCommand.
Process
Methods
create |
(commands -- result) |
Initializes one process from command arguments and returns one result string. Success returns the empty string. |
Preconditions
- The wrapper is not already initialized.
- The command sequence is not empty.
create2 |
(commands options -- result) |
Windows-only creation variant that accepts one options object in addition to the command sequence. |
isCreated |
(-- created) |
Reports whether the wrapper currently refers to one created process. |
kill |
(--) |
Requests termination of the created process. |
Preconditions
- The wrapper currently refers to one created process.
wait |
(needExitStatus -- exitStatus) |
Waits for process termination. The maximal stack effect is shown. When needExitStatus is FALSE, no exitStatus is produced. |
Preconditions
- The wrapper currently refers to one created process.
Remarks
- Destroying a created
Process waits without requesting the exit status.
Helper constructors
toProcess |
(commands -- process result) |
Constructs one Process, initializes it through create, and returns the wrapper together with the result string. |
toProcess2 |
(commands options -- process result) |
Windows-only helper that constructs one Process, initializes it through create2, and returns the wrapper together with the result string. |
Lifecycle and results
- A newly constructed
Process is uninitialized.
- A successful
create or create2 call initializes the Process wrapper.
- A non-empty result string leaves the wrapper uninitialized.
create, create2, toProcess, and toProcess2 return the empty string on success and one non-empty result string on failure.- A created
Process owns one process resource until wait completes or the wrapper is destroyed.
kill leaves the created state unchanged until wait completes.wait clears the created state after the process terminates.kill and wait use assertion-based preconditions, and low-level failures inside them abort.wait(FALSE) waits for termination and returns no exit status.wait(TRUE) returns one Int32 exit-status value.- On Windows, that value is the process exit code converted to
Int32.
- On Linux, a normal exit returns the normal exit status and any other termination form returns the negated raw wait status.
Examples
Linux exit-status example
"linux/Process" use
"String" use
"control" use
{} Int32 {} [
process: result: ("/bin/sh" "-c" "exit 7") toProcess;;
[result.size 0 =] "create failed" ensure
(TRUE @process.wait toString LF) printList
0
] "main" exportFunction
Expected Output
7
Linux failure-result example
"linux/Process" use
"String" use
"control" use
{} Int32 {} [
process: result: "/definitely/not/found/command" toProcess;;
(result.size 0 > toString " " @process.isCreated ~ toString LF) printList
0
] "main" exportFunction
Expected Output
TRUE TRUE