In real world, there are a lot of useful programs and you want to re-use it rather than re-write it in Scheme. For that purpose, this library can be useful.
The concept of this library is similar with Java's Process class. Users can create process object and run/call whenever they want. However most of the time process can be invoked immediately, so there are high level APIs for that purpose.
This section describe from top to down.
Exports high level APIs and low level APIs for operating process.
name must be string and indicate the process name be called.
arg1 and the rest must be string which will be passed to process.
The run procedure invokes name process and waits until it ends.
Then returns process' exit status.
The call procedure invokes name process and continue the Scheme
process, so it does not wait the called process. Then returns process object.
If you need to finish the process, make sure you call the process-waitprocedure described below.
Both procedures' output will be redirects current-output-port and
current-error-port. If you need to redirect it other place use
create-process described below.
_ :key (stdout #f) (stderr #f) (call? #t) reader (transcoder #f)
name must be string and indicate a process name.
args must be list of string will be passed to the process.
The create-process procedure creates and invokes a process indicated
name. Keyword arguments decide how to invoke and where to redirect the
outputs.
If stdout is #f or non output-port and call? is #f then
create-process raises &assertion.
stdout keyword argument indicates the port where to redirect the standard output of the process. This can be either binary output port or textual output port.
stderr keyword argument indicates the port where to redirect the standard error of the process. This can be either binary output port or textual output port. If this argument is #f, then stdout will be used.
call? keyword argument decides the default behaviour. If this is #t and
reader is not a procedure, then the create-process uses
async-process-read. If this is #f and reader is not a procedure,
then it uses sync-process-read. If reader is provided, then it
uses given reader.
reader keyword argument must be procedure which takes 4 arguments, process object, redirection of standard output and error, and transcoder respectively. This procedure decides how to handle the output.
Note: on Windows, both standard output end error has limitation. So if you replace the default behaviour, make sure you must read the output from the process, otherwise it can cause deat lock.
transcoder keyword argument must be transcoder or #f. This can be used in the procedure which specified reader keyword argument.
The procedure create-process creates a process and call it. The
returning value is depending on the above keyword parameters. If _reader_and stdout is provided, then the result value is the value returned from
reader procedure. Otherwise the created process object.
Process output reader. This reader creates 2 threads to read standard ouput and standard error. The reader returns immediately after the threads are executed.
Process output reader. This reader creates 2 threads to read standard ouput and standard error. The reader waits until the given process is finished.
This section describe low level APIs however some of these might be used even
if you use call described above.
Returns #f if obj is process object, otherwise #f.
name must be string and indicates the process name which will be invoked.
args must be empty list or list of strings and will be passed to the process.
Creates a process object.
process must be a process object.
Returns the binary output port which is redirected to the process' standard input.
process must be a process object.
Returns the binary input port which is redirected to the process' standard output.
process must be a process object.
Returns the binary input port which is redirected to the process' standard error.
process must be a process object.
Invokes the process and wait until it ends.
On POSIX envionment this procesure returns the result status of the process.
process must be a process object.
Invokes the process and continue the Scheme program.
process must be a process object.
Wait the given process until it ends and returns the exit status of the given process.
If the keyword argument timeout is specified, then it must be an
integer represents second or time object represents absolute time, then
the procedure waits either the given process is finished or until the
specified timeout period is passed. When the timeout period
has passed and yet the process is not finished, then the procedure returns
#f.
NOTE: The exit status are platform dependent. On Windows, the value will be 32 bit integer. On POSIX, the value will be 8 bit unsigned integer.
NOTE: On POSIX environment, timeout only works if the given
process is created by make-process related procedures. If the
process is created by pid->process, then it raises an error with
ECHILD.
process must be a process object.
Kill the given process and returns the exit status of the given
process. If the process is already terminated before the process-killis called, then returning value is its status code. Otherwise -1.
If the keyword argument children? is given and if it's true value, then
the procedure kills the child processes. The process of killing child processes
is not the same between Windows and POSIX. On Windows, the process seeks all
possible child processes. On POSIX, it simply calls killpg (2).
process must be a process object.
Return #t if the given process is still active. Otherwise #f.
On Windows, the procedure uses GetExitCodeProcess which means
if the process returns STILL_ACTIVE(259), then this procedure
return #t even if the process itself is already terminated.
On POSIX, the procedure uses kill (2) sending 0 to check the
existance of the process.
Returns pid of current Sagittarius process. The returning value is an integer.
pid must be an integer represents process id.
Creates a process form given pid.
NOTE: the created process doesn't have any ports. Those values are set to #f.
Users can choose how to communicate processes. One of the typical ways is
using socket. (sagittarius process) provides shared memory for
simple IPC.
Returns #t if given obj is a shared memory object, otherwise #f.
Creates or opens shared memory named name.
name must be an string and must be a valid shared memory name. If there is already a shared memory with the same name, then this procedure maps to it and ignores the size argument.
size must be an integer. When a new shared memory is created, then its size is restricted to the given size.
Optional argument option must be an enumeration which created by
file-options. If no-create is specified, and there is
no shared memory with given name, then &i/o-file-does-not-existis raised. If no-truncate is specified, then the created shared
memory is intact, otherwise it is truncted.
Closes given shared-memory and invalidate the allocated memory.
This procedure also removes the given shared-memory. On some platform, for example Linux, if shared memory is not explicitly unliked, then it stays until the OS is restarted. To avoid it, users need to call this procedure.
NOTE: invalidation means that the bytevector returned by
shared-memory->bytevector will be 0 length bytevector.
Returns actual instance of shared memory as a bytevector.
Modifying the returning bytevector also modifies the actual shared memory.
To do synchronisation of this, use semaphore provided by
(sagittarius threads).