The ECL manual

Juan Jose Garcia-Ripoll

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
1.1. Reading this manual
1.1.1. Common Lisp users
1.1.2. C/C++ programmers
1.2. C Reference
1.2.1. One type for everything: cl_object
1.2.2. Naming conventions
1.2.3. Only in Common Lisp
2. Evaluation and compilation
2.1. Declarations
2.2. C Reference
ecl_process_env — Per-thread environment
ANSI Dictionary — Common Lisp and C equivalence
3. Types and classes
3.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
4. Data and control flow
4.1. Minimal compilation
4.2. Function types
4.3. C Calling conventions
4.4. C Reference
ecl_bds_bind — Bind a special variable
ecl_bds_unwind — Undo one variable binding
ecl_setq — C equivalent of setq
ecl_symbol_value — C equivalent of symbol-value
ecl_va_arg — Accepting a variable number of arguments
ecl_nth_value, ecl_nvalues — Accessing output values
ecl_return0, ecl_return1, ... — Returning multiple values
ECL_BLOCK_BEGIN — C macro for block
ECL_CATCH_BEGIN — C macro for catch
ECL_UNWIND_PROTECT_BEGIN — C macro for unwind-protect
ANSI Dictionary — Common Lisp and C equivalence
5. Structures
5.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
6. Conditions
6.1. C Reference
ECL_HANDLER_CASE — C macro for handler-case
ECL_RESTART_CASE — C macro for restart-case
Conditions C dictionary — Common Lisp and C equivalence
7. Objects
7.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
8. Symbols
8.1. C Reference
ecl_make_keyword — Find a lisp keyword
ecl_make_symbol — Find a lisp symbol
ANSI Dictionary — Common Lisp and C equivalence
9. Packages
9.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
10. Numbers
10.1. Numeric types
10.2. Random-States
10.3. C Reference
Number C types — Numeric C types understood by ECL
Number constructors — Creating Lisp types from C numbers
Number accessors — Unchecked conversion from Lisp types to C numbers
Number coercion — Checked conversion from Lisp types to C numbers
Numbers C dictionary — Common Lisp and C equivalence
11. Characters
11.1. Unicode vs. POSIX locale
11.1.1. Character types
11.1.2. Character names
11.2. #\Newline characters
11.3. C Reference
C types — C character types
Constructors — Creating and extracting characters from Lisp objects
Predicates — C predicates for Lisp characters
Character case — C functions related to the character case
ANSI Dictionary — Common Lisp and C equivalence
12. Conses
12.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
13. Arrays
13.1. Array limits
13.2. Specializations
13.3. C Reference
Types and constants — C types, limits and enumerations
ecl_aet_to_symbol, ecl_symbol_to_aet — To and from element types
Constructors — Creating arrays and vectors
Accessors — Reading and writing array elements
Array properties — Array size, fill pointer, etc
ANSI Dictionary — Common Lisp and C equivalence
14. Strings
14.1. String types & Unicode
14.2. C Reference
Base string constructors — Building strings for C data
String accessors — Reading and writing characters into a string
Strings C dictionary — Common Lisp and C equivalence
15. Sequences
15.1. C Reference
Sequences C dictionary — Common Lisp and C equivalence
16. Hash tables
16.1. C Reference
Hash tables C dictionary — Common Lisp and C equivalence
17. Filenames
17.1. Syntax
17.2. Wild pathnames and matching
17.3. C Reference
Filenames C dictionary — Common Lisp and C equivalence
18. Files
18.1. Dictionary
18.2. C Reference
Files C dictionary — Common Lisp and C equivalence
19. Streams
19.1. ANSI Streams
19.1.1. Supported types
19.1.2. Element types
19.1.3. External formats
19.2. C Reference
Streams C dictionary — Common Lisp and C equivalence
20. Printer
20.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
21. Reader
21.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
22. System Construction
22.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
23. Environment
23.1. Dictionary
disassemble — Display the assembly code of a function
trace — Follow execution of functions
23.2. C Reference
ANSI Dictionary — Common Lisp and C equivalence
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
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. Multithreading 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.
Common Lisp symbols
C/C++ index
List of Figures
List of Tables