The simple-inferiors Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The simple-inferiors Reference Manual

This is the simple-inferiors Reference Manual, version 1.1.0, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 09:20:59 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

About Simple-Inferiors

This is a library to allow easy handling of external processes, and primarily to get their output. It handles proper copying of stdout and stderr of the process simultaneously, both in a sequential and parallel fashion. It also features a lazy directory switching mechanism, to avoid running into parallelism problems when having to chdir.

How To

Load simple-inferiors with ASDF or Quicklisp

(ql:quickload :simple-inferiors)

Run a program!

(simple-inferiors:run "bash" '("-c" "for i in `seq 1 10`; do echo $i; done"))

Not very exciting. By default the output is discarded and you only get the exit code. Let's see what it says:

(simple-inferiors:run "bash" '("-c" "for i in `seq 1 10`; do echo $i; done")
                      :output T)

By default the streams will be copied character by character. This allows the most immediate fetching of the output from the process, at the cost of being very CPU intensive. If you can afford it, you may want to switch to a more efficient method, such as copying line by line:

(simple-inferiors:run "bash" '("-c" "for i in `seq 1 10`; do echo $i; done")
                      :output T :copier :line)

The output actually doesn't change for this tiny test case, but the performance can be radically different for larger outputs. You may also pass a number to specify a custom buffer size, or a function to handle the stream copying yourself.

When the stack is unwound, simple-inferiors tries to terminate the external process. By default it will try to ask the process to terminate with 0.1 second delays and then it will try to kill it if it still hasn't terminated. In order to control this stopping, you must supply a different handler to run.

(simple-inferiors:run "bash" '("-c" "sleep 60") 
                      :handler (lambda (c p oi oo ei eo) 
                                 (simple-inferiors:handle-process-sequential c p oi oo ei eo :stop-attempts 100)))

You may also use handle-process-parallel if you would like to use threads to handle the stdout and stderr of the process instead of attempting to read both simultaneously sequentially, or provide your own handler function entirely.

If you need to handle different directories for your process, you can use with-chdir. Note that with-chdir does not actually perform a chdir and instead rebinds *cwd*. The chdir is only performed (if at all necessary) at the very last stage when a process is run. This avoids clashing if parallelism is involved. with-chdir merges the passed location (resolved by location) with the current *cwd*. If *cwd* is NIL (such as at the very beginning), the cwd is used to merge the path. If you need to absolutely definitely perform a chdir, you may use with-exchdir. Note that it will signal an invalid-location-error if changing directory to an inexistent location is attempted.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 simple-inferiors

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://github.com/Shinmera/simple-inferiors

License

Artistic

Description

A very simple library to use inferior processes.

Version

1.1.0

Dependencies
Source

simple-inferiors.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 simple-inferiors.asd

Location

simple-inferiors.asd

Systems

simple-inferiors (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 simple-inferiors/package.lisp

Parent

simple-inferiors (system)

Location

package.lisp

Packages

simple-inferiors


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 simple-inferiors/process.lisp

Dependency

package.lisp (file)

Parent

simple-inferiors (system)

Location

process.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 simple-inferiors/documentation.lisp

Dependency

process.lisp (file)

Parent

simple-inferiors (system)

Location

documentation.lisp


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 simple-inferiors

Source

package.lisp (file)

Nickname

org.shirakumo.simple-inferiors

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *cwd*

The variable containing the current directory, virtually.
This variable is only resolved once needed, such as when using WITH-EXCHDIR.

See WITH-CHDIR
See WITH-EXCHDIR

Package

simple-inferiors

Source

process.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: with-chdir (NEW-PATH) &body BODY

Changes the directory lazily.
This merges the passed NEW-PATH (resolved through LOCATION) with *CWD* (resolved through LOCATION) and binds that to *CWD*.

See LOCATION
See *CWD*

Package

simple-inferiors

Source

process.lisp (file)

Macro: with-exchdir (&optional NEW-PATH) &body BODY

Changes the directory directly.
If NEW-PATH is not passed, *CWD* is used instead. Either way it is resolved through LOCATION and checked by CHECK-LOCATION before the actual directory change is performed. This will /also/ act like WITH-CHDIR by additionally rebinding *CWD*.

Note that since a binary can only ever be in one directory at once, you should avoid using this unless necessary, or unless you are sure that the system is not paralellised.

See LOCATION
See CHECK-LOCATION
See *CWD*

Package

simple-inferiors

Source

process.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: copy-stream INPUT OUTPUT &key CONSUME-ALL BUFFER

Copies data from INPUT to OUTPUT using the given BUFFER format.
If CONSUME-ALL is non-NIL, all data is read from INPUT until EOF is reached.

BUFFER can be one of
(EQL :LINE) => The stream is copied one line at a time.
(EQL :CAHRACTER) => The stream is copied one character at a time.
INTEGER => A character buffer of size BUFFER is used.

Note that this function tries to be as non-blocking as possible if CONSUME-ALL is NIL. This means that it will only copy anything if there is something to read, but might also read more than one line, character, or buffer at a time, if more data is available.

Once nothing more can be copied, FINISH-OUTPUT on OUTPUT is called.

Package

simple-inferiors

Source

process.lisp (file)

Function: ensure-copier COPIER-ISH

Ensures that COPIER-ISH is an actual function usable for copying streams.

COPIER-ISH can be one of
FUNCTION => The function is used directly.
INTEGER => MAKE-COPIER is called with the COPIER-ISH.
KEYWORD => MAKE-COPIER is called with the COPIER-ISH.
SYMBOL => The function associated with the symbol is used.

The function must accept an INPUT and OUTPUT stream, as well as in the very least a keyword argument called CONSUME-ALL that, when non-NIL, will copy the whole INPUT to OUTPUT in one go until EOF is reached.

See MAKE-COPIER

Package

simple-inferiors

Source

process.lisp (file)

Function: handle-process-parallel COPIER PROCESS OUT-IN OUT-OUT ERR-IN ERR-OUT &key STOP-ATTEMPTS STOP-SLEEP

Handles the PROCESS using COPIER with the OUT-IN, OUT-OUT, ERR-IN, and ERR-OUT streams in parallel. For that, it opens two threads for the respective stream pairs that handle the copying and joins them with the initial thread on unwinding.

As all handlers, this is responsible for copying the data from the IN to the respective OUT streams as well as ensuring that the process is stopped and all remaining data is read on unwinding.

Package

simple-inferiors

Source

process.lisp (file)

Function: handle-process-sequential COPIER PROCESS OUT-IN OUT-OUT ERR-IN ERR-OUT &key COOLDOWN STOP-ATTEMPTS STOP-SLEEP

Handles the PROCESS using COPIER with the OUT-IN, OUT-OUT, ERR-IN, and ERR-OUT streams sequentially.
Between copies, it will sleep for COOLDOWN seconds to make sure no excessive CPU is wasted trying to read repeatedly.

As all handlers, this is responsible for copying the data from the IN to the respective OUT streams as well as ensuring that the process is stopped and all remaining data is read on unwinding.

Package

simple-inferiors

Source

process.lisp (file)

Function: make-copier BUFFER

Creates a copier function that accepts an input and output stream as well as optional extra arguments using BUFFER. This simply creates a wrapper lambda around COPY-STREAM.

See COPY-STREAM

Package

simple-inferiors

Source

process.lisp (file)

Function: run PROGRAM ARGS &key INPUT OUTPUT ERROR ON-NON-ZERO-EXIT HANDLER COPIER

Runs an inferior process, supplying PROGRAM with ARGS and using INPUT for STDIN, OUTPUT for STDOUT, and ERROR FOR STDERR.

The current *CWD* is resolved to an actual location, checked for validity, and then used as the location to start the process in. Depending on implementation support, this may have to fall back on using a manual chdir for launching the process.

HANDLER must be a function of six arguments:
COPIER => The function computed by ENSURE-COPIER on COPIER:
PROCESS => The process object used by EXTERNAL-PROGRAM.
OUT-IN => The receiving STDOUT stream from the process.
OUT-OUT => The outputting stream computed by WITH-RESOLVED-STREAM on OUTPUT.
ERR-IN => The receiving STDERR stream from the process.
ERR-OUT => The outputting stream computed by WITH-RESOLVED-STREAM on ERROR.
The handler must ensure that the process is stopped and all data has been copied when an unwind takes place. Furthermore it should not return until the process is done.

ON-NON-ZERO-EXIT can be one of
NIL => NIL is returned.
:RETURN => The exit code is returned.
:ERROR => A INFERIOR-PROCESS-FAILED-ERROR is signalled.
:WARN => A INFERIOR-PROCESS-FAILED-WARNING is signalled.

See *CWD*
See ENSURE-COPIER
See HANDLE-PROCESS-SEQUENTIAL
See HANDLE-PROCESS-PARALLEL

Package

simple-inferiors

Source

process.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Generic functions

Generic Function: failed-args CONDITION

Accesses the program arguments passed to RUN that failed to execute properly.

See INFERIOR-PROCESS-FAILED-CONDITION

Package

simple-inferiors

Writer

(setf failed-args) (generic function)

Methods
Method: failed-args (CONDITION inferior-process-failed-condition)
Source

process.lisp (file)

Generic Function: (setf failed-args) NEW-VALUE CONDITION
Package

simple-inferiors

Reader

failed-args (generic function)

Methods
Method: (setf failed-args) NEW-VALUE (CONDITION inferior-process-failed-condition)
Source

process.lisp (file)

Generic Function: failed-exit CONDITION

Accesses the exit code returned from the program that failed to execute properly in RUN.

See INFERIOR-PROCESS-FAILED-CONDITION

Package

simple-inferiors

Writer

(setf failed-exit) (generic function)

Methods
Method: failed-exit (CONDITION inferior-process-failed-condition)
Source

process.lisp (file)

Generic Function: (setf failed-exit) NEW-VALUE CONDITION
Package

simple-inferiors

Reader

failed-exit (generic function)

Methods
Method: (setf failed-exit) NEW-VALUE (CONDITION inferior-process-failed-condition)
Source

process.lisp (file)

Generic Function: failed-program CONDITION

Accesses the program string passed to RUN that failed to execute properly.

See INFERIOR-PROCESS-FAILED-CONDITION

Package

simple-inferiors

Writer

(setf failed-program) (generic function)

Methods
Method: failed-program (CONDITION inferior-process-failed-condition)
Source

process.lisp (file)

Generic Function: (setf failed-program) NEW-VALUE CONDITION
Package

simple-inferiors

Reader

failed-program (generic function)

Methods
Method: (setf failed-program) NEW-VALUE (CONDITION inferior-process-failed-condition)
Source

process.lisp (file)

Generic Function: location THING

Attempts to resolve the THING to a pathname.

THING can be one of
NULL => UIOP:GETCWD
PATHNAME => THING
STRING => UIOP:PARSE-NATIVE-NAMESTRING

This generic function is intended to be extended with methods by the user to allow using objects as locations directly.

Package

simple-inferiors

Source

process.lisp (file)

Writer

(setf location) (generic function)

Methods
Method: location (NULL null)
Method: location (PATHNAME pathname)
Method: location (STRING string)
Method: location (CONDITION invalid-location-error)
Generic Function: (setf location) NEW-VALUE CONDITION
Package

simple-inferiors

Reader

location (generic function)

Methods
Method: (setf location) NEW-VALUE (CONDITION invalid-location-error)
Source

process.lisp (file)

Generic Function: valid-location-p THING

Checks whether THING is a valid (existing) location.

See LOCATION

Package

simple-inferiors

Source

process.lisp (file)

Methods
Method: valid-location-p THING

Previous: , Up: Exported definitions   [Contents][Index]

5.1.5 Conditions

Condition: inferior-process-failed-error ()

Error variant of INFERIOR-PROCESS-FAILED-CONDITION

See INFERIOR-PROCESS-FAILED-CONDITION

Package

simple-inferiors

Source

process.lisp (file)

Direct superclasses
Condition: inferior-process-failed-warning ()

Warning variant of INFERIOR-PROCESS-FAILED-CONDITION

See INFERIOR-PROCESS-FAILED-CONDITION

Package

simple-inferiors

Source

process.lisp (file)

Direct superclasses
Condition: invalid-location-error ()

Signalled if an attempt is made to change directory to a location that does not exist.

See LOCATION

Package

simple-inferiors

Source

process.lisp (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: location
Initargs

:location

Readers

location (generic function)

Writers

(setf location) (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: with-resolved-stream (STREAM-ISH &key ARGS) &body BODY

Resolves the STREAM-ISH to an actual stream and rebinds the symbol.

See CALL-WITH-RESOLVED-STREAM.

Package

simple-inferiors

Source

process.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: %start-process PROGRAM ARGS &rest KARGS
Package

simple-inferiors

Source

process.lisp (file)

Function: call-with-resolved-stream FUNC STREAM-ISH &key ARGS

Resolved STREAM-ISH to an actual stream and calls FUNC with it as its only argument.

STREAM can be one of
NULL => Uses an empty broadcast-stream.
STREAM => Uses the stream directly.
PATHNAME => OPENs the file (passing ARGS) and uses the obtained file-stream. (EQL :STRING) => Uses a string-output-stream.
(EQL T) => Uses *standard-output*

Package

simple-inferiors

Source

process.lisp (file)

Function: check-location THING

Checks whether THIGN is a valid location and if it isn’t, signals an INVALID-LOCATION-ERROR.

See VALID-LOCATION-P
See INVALID-LOCATION-ERROR

Package

simple-inferiors

Source

process.lisp (file)

Function: ensure-process-stopped PROCESS &rest ARGS &key ATTEMPTS SLEEP

Only tries to stop the PROCESS if it is still running.

See STOP-PROCESS

Package

simple-inferiors

Source

process.lisp (file)

Function: stop-process PROCESS &key ATTEMPTS SLEEP

Attempt to stop the PROCESS.
It will first try to send a SIGINT every SLEEP seconds for ATTEMPTS times. If the process is still running at that point, a SIGKILL is sent. If the process still won’t quite after a SIGKILL, STOP-PROCESS simply gives up.

Package

simple-inferiors

Source

process.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Conditions

Condition: inferior-process-failed-condition ()

Condition used for when a process returns with a non-zero exit code.

See FAILED-PROGRAM
See FAILED-ARGS
See FAILED-EXIT

Package

simple-inferiors

Source

process.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses
Direct methods
Direct slots
Slot: program
Initargs

:program

Readers

failed-program (generic function)

Writers

(setf failed-program) (generic function)

Slot: args
Initargs

:args

Readers

failed-args (generic function)

Writers

(setf failed-args) (generic function)

Slot: exit
Initargs

:exit

Readers

failed-exit (generic function)

Writers

(setf failed-exit) (generic function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, simple-inferiors.asd: The simple-inferiors<dot>asd file
File, Lisp, simple-inferiors/documentation.lisp: The simple-inferiors/documentation<dot>lisp file
File, Lisp, simple-inferiors/package.lisp: The simple-inferiors/package<dot>lisp file
File, Lisp, simple-inferiors/process.lisp: The simple-inferiors/process<dot>lisp file

L
Lisp File, simple-inferiors.asd: The simple-inferiors<dot>asd file
Lisp File, simple-inferiors/documentation.lisp: The simple-inferiors/documentation<dot>lisp file
Lisp File, simple-inferiors/package.lisp: The simple-inferiors/package<dot>lisp file
Lisp File, simple-inferiors/process.lisp: The simple-inferiors/process<dot>lisp file

S
simple-inferiors.asd: The simple-inferiors<dot>asd file
simple-inferiors/documentation.lisp: The simple-inferiors/documentation<dot>lisp file
simple-inferiors/package.lisp: The simple-inferiors/package<dot>lisp file
simple-inferiors/process.lisp: The simple-inferiors/process<dot>lisp file

Jump to:   F   L   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
C   E   F   G   H   L   M   R   S   V   W  
Index Entry  Section

%
%start-process: Internal functions

(
(setf failed-args): Exported generic functions
(setf failed-args): Exported generic functions
(setf failed-exit): Exported generic functions
(setf failed-exit): Exported generic functions
(setf failed-program): Exported generic functions
(setf failed-program): Exported generic functions
(setf location): Exported generic functions
(setf location): Exported generic functions

C
call-with-resolved-stream: Internal functions
check-location: Internal functions
copy-stream: Exported functions

E
ensure-copier: Exported functions
ensure-process-stopped: Internal functions

F
failed-args: Exported generic functions
failed-args: Exported generic functions
failed-exit: Exported generic functions
failed-exit: Exported generic functions
failed-program: Exported generic functions
failed-program: Exported generic functions
Function, %start-process: Internal functions
Function, call-with-resolved-stream: Internal functions
Function, check-location: Internal functions
Function, copy-stream: Exported functions
Function, ensure-copier: Exported functions
Function, ensure-process-stopped: Internal functions
Function, handle-process-parallel: Exported functions
Function, handle-process-sequential: Exported functions
Function, make-copier: Exported functions
Function, run: Exported functions
Function, stop-process: Internal functions

G
Generic Function, (setf failed-args): Exported generic functions
Generic Function, (setf failed-exit): Exported generic functions
Generic Function, (setf failed-program): Exported generic functions
Generic Function, (setf location): Exported generic functions
Generic Function, failed-args: Exported generic functions
Generic Function, failed-exit: Exported generic functions
Generic Function, failed-program: Exported generic functions
Generic Function, location: Exported generic functions
Generic Function, valid-location-p: Exported generic functions

H
handle-process-parallel: Exported functions
handle-process-sequential: Exported functions

L
location: Exported generic functions
location: Exported generic functions
location: Exported generic functions
location: Exported generic functions
location: Exported generic functions

M
Macro, with-chdir: Exported macros
Macro, with-exchdir: Exported macros
Macro, with-resolved-stream: Internal macros
make-copier: Exported functions
Method, (setf failed-args): Exported generic functions
Method, (setf failed-exit): Exported generic functions
Method, (setf failed-program): Exported generic functions
Method, (setf location): Exported generic functions
Method, failed-args: Exported generic functions
Method, failed-exit: Exported generic functions
Method, failed-program: Exported generic functions
Method, location: Exported generic functions
Method, location: Exported generic functions
Method, location: Exported generic functions
Method, location: Exported generic functions
Method, valid-location-p: Exported generic functions

R
run: Exported functions

S
stop-process: Internal functions

V
valid-location-p: Exported generic functions
valid-location-p: Exported generic functions

W
with-chdir: Exported macros
with-exchdir: Exported macros
with-resolved-stream: Internal macros

Jump to:   %   (  
C   E   F   G   H   L   M   R   S   V   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
A   E   L   P   S  
Index Entry  Section

*
*cwd*: Exported special variables

A
args: Internal conditions

E
exit: Internal conditions

L
location: Exported conditions

P
program: Internal conditions

S
Slot, args: Internal conditions
Slot, exit: Internal conditions
Slot, location: Exported conditions
Slot, program: Internal conditions
Special Variable, *cwd*: Exported special variables

Jump to:   *  
A   E   L   P   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   I   P   S  
Index Entry  Section

C
Condition, inferior-process-failed-condition: Internal conditions
Condition, inferior-process-failed-error: Exported conditions
Condition, inferior-process-failed-warning: Exported conditions
Condition, invalid-location-error: Exported conditions

I
inferior-process-failed-condition: Internal conditions
inferior-process-failed-error: Exported conditions
inferior-process-failed-warning: Exported conditions
invalid-location-error: Exported conditions

P
Package, simple-inferiors: The simple-inferiors package

S
simple-inferiors: The simple-inferiors system
simple-inferiors: The simple-inferiors package
System, simple-inferiors: The simple-inferiors system

Jump to:   C   I   P   S