The shellpool Reference Manual

Table of Contents

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

The shellpool Reference Manual

This is the shellpool Reference Manual, version 0.0.3, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:34:07 2018 GMT+0.


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

1 Introduction

Shellpool

Shellpool is a way to run external programs from within a Common Lisp program. It features:

Note: Shellpool is not suitable for running sub-commands that need access to command-line input from the user or for TTY-based programs.

Resources

Related Lisp Libraries

If shellpool isn't quite right for you, here are some related Lisp libraries.

License and History

Shellpool is Copyright (C) 2014-2015 Kookamara LLC. It has an MIT/X11 style license. It was written by Jared Davis.

Shellpool is a successor to "tshell", a mechanism for running external programs from Clozure Common Lisp. Tshell was developed by Centaur Technology and was distributed as a library for ACL2; it was also released under the MIT license. It was mainly used for running SAT solvers, which are programs that can easily get "stuck" on hard problems, and hence often need to be interrupted. It worked very well for this purpose.

Unfortunately tshell was inherently single-threaded and wasn't portable beyond CCL on Linux. Shellpool is a complete rewrite that solves these problems, by explicitly having a pool of shells (to support multiple threads), by adding compatibility wrappers (to support multiple Lisps), and by reworking the core Bash code (to support multiple OSes).

Shellpool has now replaced Tshell in the ACL2 books and is now being used, in production, on an everyday basis.


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 shellpool

Author

Jared Davis <jared@kookamara.com>

License

An MIT/X11-style license; see the file LICENSE.

Description

A library for running external programs from Common Lisp. (https://github.org/jaredcdavis/shellpool)

Version

0.0.3

Dependencies
Source

shellpool.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 shellpool.asd

Location

shellpool.asd

Systems

shellpool (system)


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

3.1.2 shellpool/src/packages.lisp

Parent

shellpool (system)

Location

src/packages.lisp

Packages

shellpool


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

3.1.3 shellpool/src/main.lisp

Dependency

src/packages.lisp (file)

Parent

shellpool (system)

Location

src/main.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 shellpool

Source

src/packages.lisp (file)

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: *debug*

Change to T for verbose debugging messages.

Package

shellpool

Source

src/main.lisp (file)

Special Variable: *max-shells*

Purely a safety valve. We’ll cause an error if you try to start more than this many shells at once, since that would probably cause problems on your system. We make this a parameter so you can reconfigure it if you really need to create so many shells.

Package

shellpool

Source

src/main.lisp (file)


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

5.1.2 Functions

Function: ensure &optional N

Ensure that at least n shells are running, starting up shells if needed.

Package

shellpool

Source

src/main.lisp (file)

Function: run SCRIPT &key EACH-LINE
Package

shellpool

Source

src/main.lisp (file)

Function: run& SCRIPT
Package

shellpool

Source

src/main.lisp (file)

Function: start &optional N

Start some number of shells and ensure that the aux shell is running.

Package

shellpool

Source

src/main.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Constants

Constant: +allkids+
Package

shellpool

Source

src/main.lisp (file)

Constant: +death-line+
Package

shellpool

Source

src/main.lisp (file)

Constant: +exit-line+
Package

shellpool

Source

src/main.lisp (file)

Constant: +pid-line+
Package

shellpool

Source

src/main.lisp (file)

Constant: +status-line+
Package

shellpool

Source

src/main.lisp (file)

Constant: nl

Newline as a string. Convenient in string concatenations as a way to insert newlines without having to ruin your indenting.

Package

shellpool

Source

src/main.lisp (file)


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

5.2.2 Special variables

Special Variable: *state*
Package

shellpool

Source

src/main.lisp (file)


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

5.2.3 Macros

Macro: debug-msg &rest ARGS

Like (format t ...) but only prints if debugging is enabled.

Package

shellpool

Source

src/main.lisp (file)

Macro: define-constant NAME VALUE &optional DOC
Package

shellpool

Source

src/main.lisp (file)

Macro: with-file-to-be-deleted FILENAME &rest FORMS
Package

shellpool

Source

src/main.lisp (file)

Macro: with-runner NAME &rest FORMS
Package

shellpool

Source

src/main.lisp (file)

Macro: with-state-lock &rest FORMS
Package

shellpool

Source

src/main.lisp (file)


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

5.2.4 Functions

Function: add-runners N
Package

shellpool

Source

src/main.lisp (file)

Function: bash-alive-p SH
Package

shellpool

Source

src/main.lisp (file)

Function: bash-err SH
Package

shellpool

Source

src/main.lisp (file)

Function: bash-in SH
Package

shellpool

Source

src/main.lisp (file)

Function: bash-out SH
Package

shellpool

Source

src/main.lisp (file)

Function: copy-runner INSTANCE
Package

shellpool

Source

src/main.lisp (file)

Function: copy-state INSTANCE
Package

shellpool

Source

src/main.lisp (file)

Function: default-each-line LINE TYPE
Package

shellpool

Source

src/main.lisp (file)

Function: find-bash ()
Package

shellpool

Source

src/main.lisp (file)

Function: kill PID
Package

shellpool

Source

src/main.lisp (file)

Function: make-bash ()
Package

shellpool

Source

src/main.lisp (file)

Function: make-run-command-string FILENAME
Package

shellpool

Source

src/main.lisp (file)

Function: make-runner &key (ERR ERR) (SH SH)
Package

shellpool

Source

src/main.lisp (file)

Function: make-state &key (LOCK LOCK) (AUX AUX) (SEM SEM) (RUNNERS RUNNERS) (TOTAL TOTAL)
Package

shellpool

Source

src/main.lisp (file)

Function: parse-pid-line LINE
Package

shellpool

Source

src/main.lisp (file)

Function: runner-err INSTANCE
Function: (setf runner-err) VALUE INSTANCE
Package

shellpool

Source

src/main.lisp (file)

Function: runner-p OBJECT
Package

shellpool

Source

src/main.lisp (file)

Function: runner-sh INSTANCE
Function: (setf runner-sh) VALUE INSTANCE
Package

shellpool

Source

src/main.lisp (file)

Function: state-aux INSTANCE
Function: (setf state-aux) VALUE INSTANCE
Package

shellpool

Source

src/main.lisp (file)

Function: state-lock INSTANCE
Function: (setf state-lock) VALUE INSTANCE
Package

shellpool

Source

src/main.lisp (file)

Function: state-p OBJECT
Package

shellpool

Source

src/main.lisp (file)

Function: state-runners INSTANCE
Function: (setf state-runners) VALUE INSTANCE
Package

shellpool

Source

src/main.lisp (file)

Function: state-sem INSTANCE
Function: (setf state-sem) VALUE INSTANCE
Package

shellpool

Source

src/main.lisp (file)

Function: state-total INSTANCE
Function: (setf state-total) VALUE INSTANCE
Package

shellpool

Source

src/main.lisp (file)

Function: strpos X Y

Determines the position of the first occurrence of the substring X in the string Y, or returns NIL if there is no such occurrence.

Package

shellpool

Source

src/main.lisp (file)

Function: strpos-fast X Y N XLEN YLEN
Package

shellpool

Source

src/main.lisp (file)

Function: strprefixp X Y

Determines if the string X comes at the start of the string Y. Example: (strprefixp "foo" "foobar") is true.

Package

shellpool

Source

src/main.lisp (file)

Function: strprefixp-impl X Y XN YN XLEN YLEN
Package

shellpool

Source

src/main.lisp (file)

Function: strsuffixp X Y

Determines if the string X comes at the end of the string Y. Example: (strsuffixp "bar" "foobar") is true.

Package

shellpool

Source

src/main.lisp (file)


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

5.2.5 Structures

Structure: runner ()
Package

shellpool

Source

src/main.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: err
Readers

runner-err (function)

Writers

(setf runner-err) (function)

Slot: sh
Readers

runner-sh (function)

Writers

(setf runner-sh) (function)

Structure: state ()
Package

shellpool

Source

src/main.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: lock
Readers

state-lock (function)

Writers

(setf state-lock) (function)

Slot: aux
Readers

state-aux (function)

Writers

(setf state-aux) (function)

Slot: sem
Readers

state-sem (function)

Writers

(setf state-sem) (function)

Slot: runners
Readers

state-runners (function)

Writers

(setf state-runners) (function)

Slot: total
Readers

state-total (function)

Writers

(setf state-total) (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, shellpool.asd: The shellpool<dot>asd file
File, Lisp, shellpool/src/main.lisp: The shellpool/src/main<dot>lisp file
File, Lisp, shellpool/src/packages.lisp: The shellpool/src/packages<dot>lisp file

L
Lisp File, shellpool.asd: The shellpool<dot>asd file
Lisp File, shellpool/src/main.lisp: The shellpool/src/main<dot>lisp file
Lisp File, shellpool/src/packages.lisp: The shellpool/src/packages<dot>lisp file

S
shellpool.asd: The shellpool<dot>asd file
shellpool/src/main.lisp: The shellpool/src/main<dot>lisp file
shellpool/src/packages.lisp: The shellpool/src/packages<dot>lisp file

Jump to:   F   L   S  

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

A.2 Functions

Jump to:   (  
A   B   C   D   E   F   K   M   P   R   S   W  
Index Entry  Section

(
(setf runner-err): Internal functions
(setf runner-sh): Internal functions
(setf state-aux): Internal functions
(setf state-lock): Internal functions
(setf state-runners): Internal functions
(setf state-sem): Internal functions
(setf state-total): Internal functions

A
add-runners: Internal functions

B
bash-alive-p: Internal functions
bash-err: Internal functions
bash-in: Internal functions
bash-out: Internal functions

C
copy-runner: Internal functions
copy-state: Internal functions

D
debug-msg: Internal macros
default-each-line: Internal functions
define-constant: Internal macros

E
ensure: Exported functions

F
find-bash: Internal functions
Function, (setf runner-err): Internal functions
Function, (setf runner-sh): Internal functions
Function, (setf state-aux): Internal functions
Function, (setf state-lock): Internal functions
Function, (setf state-runners): Internal functions
Function, (setf state-sem): Internal functions
Function, (setf state-total): Internal functions
Function, add-runners: Internal functions
Function, bash-alive-p: Internal functions
Function, bash-err: Internal functions
Function, bash-in: Internal functions
Function, bash-out: Internal functions
Function, copy-runner: Internal functions
Function, copy-state: Internal functions
Function, default-each-line: Internal functions
Function, ensure: Exported functions
Function, find-bash: Internal functions
Function, kill: Internal functions
Function, make-bash: Internal functions
Function, make-run-command-string: Internal functions
Function, make-runner: Internal functions
Function, make-state: Internal functions
Function, parse-pid-line: Internal functions
Function, run: Exported functions
Function, run&: Exported functions
Function, runner-err: Internal functions
Function, runner-p: Internal functions
Function, runner-sh: Internal functions
Function, start: Exported functions
Function, state-aux: Internal functions
Function, state-lock: Internal functions
Function, state-p: Internal functions
Function, state-runners: Internal functions
Function, state-sem: Internal functions
Function, state-total: Internal functions
Function, strpos: Internal functions
Function, strpos-fast: Internal functions
Function, strprefixp: Internal functions
Function, strprefixp-impl: Internal functions
Function, strsuffixp: Internal functions

K
kill: Internal functions

M
Macro, debug-msg: Internal macros
Macro, define-constant: Internal macros
Macro, with-file-to-be-deleted: Internal macros
Macro, with-runner: Internal macros
Macro, with-state-lock: Internal macros
make-bash: Internal functions
make-run-command-string: Internal functions
make-runner: Internal functions
make-state: Internal functions

P
parse-pid-line: Internal functions

R
run: Exported functions
run&: Exported functions
runner-err: Internal functions
runner-p: Internal functions
runner-sh: Internal functions

S
start: Exported functions
state-aux: Internal functions
state-lock: Internal functions
state-p: Internal functions
state-runners: Internal functions
state-sem: Internal functions
state-total: Internal functions
strpos: Internal functions
strpos-fast: Internal functions
strprefixp: Internal functions
strprefixp-impl: Internal functions
strsuffixp: Internal functions

W
with-file-to-be-deleted: Internal macros
with-runner: Internal macros
with-state-lock: Internal macros

Jump to:   (  
A   B   C   D   E   F   K   M   P   R   S   W  

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

A.3 Variables

Jump to:   *   +  
A   C   E   L   N   R   S   T  
Index Entry  Section

*
*debug*: Exported special variables
*max-shells*: Exported special variables
*state*: Internal special variables

+
+allkids+: Internal constants
+death-line+: Internal constants
+exit-line+: Internal constants
+pid-line+: Internal constants
+status-line+: Internal constants

A
aux: Internal structures

C
Constant, +allkids+: Internal constants
Constant, +death-line+: Internal constants
Constant, +exit-line+: Internal constants
Constant, +pid-line+: Internal constants
Constant, +status-line+: Internal constants
Constant, nl: Internal constants

E
err: Internal structures

L
lock: Internal structures

N
nl: Internal constants

R
runners: Internal structures

S
sem: Internal structures
sh: Internal structures
Slot, aux: Internal structures
Slot, err: Internal structures
Slot, lock: Internal structures
Slot, runners: Internal structures
Slot, sem: Internal structures
Slot, sh: Internal structures
Slot, total: Internal structures
Special Variable, *debug*: Exported special variables
Special Variable, *max-shells*: Exported special variables
Special Variable, *state*: Internal special variables

T
total: Internal structures

Jump to:   *   +  
A   C   E   L   N   R   S   T  

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

A.4 Data types

Jump to:   P   R   S  
Index Entry  Section

P
Package, shellpool: The shellpool package

R
runner: Internal structures

S
shellpool: The shellpool system
shellpool: The shellpool package
state: Internal structures
Structure, runner: Internal structures
Structure, state: Internal structures
System, shellpool: The shellpool system

Jump to:   P   R   S