The ECL manual

Juan Jose Garcia-Ripoll


Preface
1. About this book
2. What is ECL?
3. History
4. Copyright of ECL
5. Copyright of this manual
6. Installation
6.1. Supported platforms
6.2. Autoconf based configuration
6.3. Platform specific instructions
6.3.1. Microsoft compilers
6.3.2. OpenBSD and NetBSD
I. Standards
1. Overview
2. Evaluation and compilation
2.1. Declarations
2.1.1. OPTIMIZE
3. Data and control flow
3.1. Minimal compilation
3.2. Functions
4. Symbols
5. Packages
6. Numbers
6.1. Numeric types
6.2. Random-States
7. Characters
7.1. Character types
7.2. Character names
7.3. Line Divisions
8. Arrays
8.1. Array limits
8.2. Specializations
9. Strings
10. Hash tables
11. Pathnames
11.1. Syntax
11.2. Wild pathnames and matching
12. Files
12.1. Mapping pathnames to files
12.2. Dictionary
12.2.1. DIRECTORY
13. Streams
13.1. Stream types
13.2. Input/Output model
14. Printer
15. Environment
15.1. Dictionary
disassemble — Display the assembly code of a function
trace — Follow execution of functions
II. Extensions and libraries
1. System building
1.1. Introduction
1.2. System definition files
1.3. Practical examples
1.4. ASDF Reference
asdf:make-build — Block-build an ASDF system definition
asdf:load-fasl-op — Compile and load one ore more libraries using unified FASL
2. Operating System Interface
2.1. Processes
2.2. Command line arguments
2.3. OS Reference
ext:*help-message* — Command line help message
ext:*lisp-init-file-list*ECL initialization files.
ext:+default-command-arg-rules+ECL command line options
ext:command-args — List of command line arguments.
ext:process-command-args — Process command line arguments.
ext:quit — Exit ECL.
ext:run-program — Start and communicate with a child process.
ext:system — Invoke a command using the shell.
3. Foreign Function Interface
3.1. What is a FFI?
3.2. Two kinds of FFI
3.3. Foreign objects
3.4. Higher level interfaces
3.4.1. UFFI example
3.4.2. CFFI example
3.4.3. Low level example
3.5. FFI Reference
ffi:clines — Insert C declarations and definitions
ffi:c-inline — Inline C code in a lisp form.
4. Multithreading
4.1. Tasks, threads or processes
4.2. MP Reference
mp:all-processes — Return the list of active processes.
mp:exit-process — Exit the task from which it is invoked.
mp:interrupt-process — Interrupt a task.
mp:get-lock — Try to obtain a lock.
mp:giveup-lock — Release a lock we have obtained before.
mp:make-lock — Create a new lock.
mp:make-process — Create a new thread.
mp:process-active-p — Determine whether a task is running.
mp:process-enable — Start up a task which was not running.
mp:process-kill — Try to stop a running task.
mp:process-name — Return the name of a task.
mp:process-preset — Associate a function to a process.
mp:process-run-function — Create a task and execute a function in it.
mp:with-lock — Synchronize a piece of code between different tasks.
5. Memory Management
5.1. Introduction
5.2. Boehm-Weiser garbage collector
5.3. Memory limits
5.4. Memory Conditions
5.5. Finalization
5.6. Memory Management Reference
ext:stack-overflow — Stack overflow condition.
ext:storage-exhausted — Memory overflow condition.
ext:get-finalizer — Return finalizer associated to an object.
ext:get-limit — Query a memory or stack limit.
ext:set-finalizer — Associate a finalizer to an object.
ext:set-limit — Set a memory or stack limit.
6. Meta-Object Protocol (MOP)
6.1. Introduction
6.2. Classes
6.3. Slots
6.4. Generic functions and methods
6.5. Sealed slots and classes
7. Signals and interrupts
7.1. Problems associated to signals
7.2. Kinds of signals
7.2.1. Synchronous signals
7.2.2. Asynchronous signals
7.3. Signals and interrupts in ECL
7.3.1. Handling of asynchronous signals
7.3.2. Handling of synchronous signals
7.4. Considerations when embedding ECL
7.5. Signals Reference
ext:with-interrupts — Execute code with interrupts optionally enabled.
ext:without-interrupts — Execute code without being interrupted.
8. Embedding ECL
8.1. Introduction
8.2. Embedding Reference
CL_CATCH_ALL — Create a protected region.
CL_UNWIND_PROTECT — Create a protected region.
cl_boot — Setup the lisp environment.
cl_shutdown — Close the lisp environment.
ecl_set_option — Set a boot option.
ecl_get_option — Read the value of a boot option.
ecl_clear_interrupts — Clear all pending signals and exceptions.
ecl_disable_interrupts — Postpone handling of signals and exceptions.
ecl_enable_interrupts — Activate handling of signals and exceptions.
III. Internals
1. Building programs
1.1. What can ECL do?
1.2. Compiling files
1.3. Building standalone executables
1.4. Building libraries
1.5. File names
1.6. Compiler examples
1.6.1. The hello.lisp file
1.6.2. Example of loadable object file
1.6.3. Example of standalone program
1.6.4. Combining files into a larger FASL
2. Manipulating Lisp objects
2.1. Objects representation
2.2. Constructing objects
2.3. Integers
2.4. Characters
2.5. Arrays
2.6. Strings
2.7. Bitvectors
2.8. Streams
2.9. Structures
2.10. Instances
2.11. Bytecodes
3. The interpreter
3.1. ECL stacks
3.2. Procedure Call Conventions
3.3. The lexical environment
3.4. The interpreter stack
4. The compiler
4.1. The compiler translates to C
4.2. The compiler mimics human C programmer
4.3. Implementation of Compiled Closures
4.4. Use of Declarations to Improve Efficiency
4.5. Inspecting generated C code
5. Porting ECL
IV. UFFI Reference
I. Primitive Types
def-constant — Binds a symbol to a constant.
def-foreign-type — Defines a new foreign type.
null-char-p — Tests a character for NULL value.
II. Aggregate Types
def-enum — Defines a C enumeration.
def-struct — Defines a C structure.
get-slot-value — Retrieves a value from a slot of a structure.
get-slot-pointer — Retrieves a pointer from a slot of a structure.
def-array-pointer — Defines a pointer to a array of type.
deref-array — Deference an array.
def-union — Defines a foreign union type.
III. Objects
allocate-foreign-object — Allocates an instance of a foreign object.
free-foreign-object — Frees memory that was allocated for a foreign boject.
with-foreign-object — Wraps the allocation of a foreign object around a body of code.
size-of-foreign-type — Returns the number of data bytes used by a foreign object type.
pointer-address — Returns the address of a pointer.
deref-pointer — Deferences a pointer.
ensure-char-character — Ensures that a dereferenced :char pointer is a character.
ensure-char-integer — Ensures that a dereferenced :char pointer is an integer.
make-null-pointer — Create a NULL pointer.
null-pointer-p — Tests a pointer for NULL value.
+null-cstring-pointer+ — A constant NULL cstring pointer.
with-cast-pointer — Wraps a body of code with a pointer cast to a new type.
def-foreign-var — Defines a symbol macro to access a variable in foreign code
IV. Strings
convert-from-cstring — Converts a cstring to a Lisp string.
convert-to-cstring — Converts a Lisp string to a cstring.
free-cstring — Free memory used by cstring.
with-cstring — Binds a newly created cstring.
convert-from-foreign-string — Converts a foreign string into a Lisp string.
convert-to-foreign-string — Converts a Lisp string to a foreign string.
allocate-foreign-string — Allocates space for a foreign string.
V. Functions & Libraries
def-function — Declares a function.
load-foreign-library — Loads a foreign library.
find-foreign-library — Finds a foreign library file.
Bibliography

List of Figures

1. ECL's family tree
3.1. FFI components

List of Tables

1. Supported platforms
2.1. Behavior for different leves of DEBUG
2.2. Behavior for different leves of SAFETY
3.1. Function related constants
5.1. ECL packages
6.1. Numeric types in ECL
7.1. Examples of character names
9.1. Common Lisp string types
11.1. Examples of physical namestrings
12.1. Examples of using DIRECTORY
14.1. Implementation specific printed representation
1.1. Code distribution models
3.1. DFFI support
5.1. Customizable memory limits
8.1. Boot options for embedded ECL