2023-04-05

(sph process create)

create child processes and process chains

part of sph-lib

module name

(sph process create)

exported bindings

procedure: execute-with-pipes proc path arguments #:search-path? [input? output? error?] ->
procedure:{port ... -> any} string list boolean boolean boolean -> any:proc-result integer:exit-status
executes a program and calls proc with pipes to or from the standard streams depending on if input/output/error are true.
path is a filesystem path to an executable.
you might have to close ports for proc to return.
pipe ports are closed when proc returns.
example:
(execute-with-pipes (l (input error) #t) \"/usr/bin/echo\" (list \"test\") #t #f #t)
procedure: process-chain first-input last-output execute-arguments #:search-path? ->
port/any port/any (string/(string:executable string:argument ...) ...) -> (integer:pid ...)
creates a new process for each execute-argument and sets standard input and output of the processes in a chaining manner:
input is the first-input or the input from the previous process, the output is the output to the next process or the last-output.
error port for each process is the current-error-port of the process calling process-chain pipes.
if any process could not be created then all previously created processed are sent SIGTERM and the result is an empty list.
tip: if you want to call procedures in between you could start guile processes or use pipe-chain, create the processes yourself and threads for guile code
procedure: process-chain->string first-input process-chain-arguments ... ->
false/port any ... -> string
procedure: process-chain-finish process-chain-result ->
false/(integer:pid ...) -> integer
wait for the termination of the processes and return the exit status
procedure: process-chain-finish-success? process-chain-result ->
false/(integer:pid ...) -> boolean
wait for the termination of the processes and check if its exit status is 0
procedure: process-chain-path-pipe first-input last-output config #:search-path? ->
port/string/any port/string/any (#(symbol symbol string/(string:executable string ...)/procedure:{false/string false/string -> string/(string:executable string ...)}) ...) -> (integer:pid ...)
first-input last-output (#(port/path/nothing port/path/nothing path/(path argument ...)/procedure:{path-in path-out -> execute-arguments} ...) ...) -> (integer:pid ...)
like process-chain but uses path-pipe-chain internally and so allows automatically created paths (named pipes) between processes.
example:
(path-pipe-process-chain #f (current-output-port)
(list
(vector (q nothing) (q port) (list \"echo\" \"test\"))
(vector (q path) (q path) (l (in out) (\"program\" \"--from\" in \"--to\" out)))))
expected result:
assuming that \"program\" reads from file in and writes to file out, \"test\" should appear on the current output port
procedure: process-create executable #:env #:keep-descriptors #:search-path? #:path-open-flags [arguments input-port output-port error-port] ->
string:path/file-name [(string ...) port/string/integer/false ... #:key (env (environ)) (keep-descriptors (list)) search-path? (path-open-flags integer)] -> process-id
\"executable\" is the path or file name (if search-path? is true) of a file to execute to become the new process.
if the given string for \"executable\" does not start with a slash and search-path? is true (default is false for security), it is searched in the directories in the PATH environment variable.
the optional parameters are to set the standard streams.
with the key parameters the environment variables for the new process can be set in the format (environ) returns.
no file descriptors from the parent process are transferred to the child except if listed in keep-descriptors or given using the input/output/error-port parameters.
when a string is given as port argument, it is interpreted as a filesystem path and #:path-open-flags can be used to add to O_WRONLY|O_CREAT.
returns the process id of the newly created child process or false if the process could not be created
variable: sph-process-create-description