Commit 3c3a02ea authored by Marius Gerbershagen's avatar Marius Gerbershagen

doc: improvements to extensions section

    Use consistent formatting, fix errors and typos.
parent af2c1526
......@@ -2,6 +2,11 @@
@section Defun preprocessor
@cindex Defun preprocessor
The defun preprocessor allows for convenient definition of Lisp
functions with optional and keyword arguments and the use of Lisp
symbols in ECL's own C source code. It generates the C code necessary
to use optional function arguments and to access symbols in ECL's
builtin symbol table.
Usage:
@verbatim
......
......@@ -15,12 +15,12 @@
@node Compiling with ECL
@subsection Compiling with ECL
In this section we will introduce topics on compiling Lisp programs. ECL
is especially powerful on combining lisp programs with C programs. You
can embed ECL as a lisp engine in C programs, or call C functions via
@ref{Foreign Function Interface}. We explain file types generated by
some compilation approaches. A GNU/Linux system and gcc as a development
environment are assumed.
In this section we will introduce topics on compiling Lisp
programs. ECL is especially powerful on combining lisp programs with C
programs. You can embed ECL as a lisp engine in C programs, or call C
functions via @ref{Foreign Function Interface}. We explain file types
generated by some compilation approaches. For the examples,
a GNU/Linux system and gcc as a development environment are assumed.
You can generate the following files with ECL:
......@@ -92,7 +92,7 @@ bundles. FASC files are faster to compile, but generally slower to run.
@cindex Native FASL
@ftindex DLOPEN
@cfindex --enable-shared [YES|no]]
@cfindex --enable-shared [YES|no]
If you want to make a library which is loaded dynamically from a lisp
......@@ -217,8 +217,8 @@ main(int argc, char **argv)
/* setup the lisp runtime */
cl_boot(argc, argv);
/* call the init function via read_VV */
read_VV(OBJNULL, init_hello_goodbye);
/* call the init function via ecl_init_module */
ecl_init_module(NULL, init_hello_goodbye);
/* ... */
......@@ -233,11 +233,13 @@ main(int argc, char **argv)
Because the program itself does not know the type of the init
function, a prototype declaration is inserted. After booting up the
lisp environment, it invokes @code{init_hello_goodbye} via
@code{read_VV}. @code{init_hello_goodbye} takes an argument, and
@code{read_VV} supplies an appropriate one. Now that the
@code{ecl_init_module}. @code{init_hello_goodbye} takes an argument, and
@code{ecl_init_module} supplies an appropriate one. Now that the
initialization is finished, we can use functions and other stuff
defined in the library.
@strong{DEPRECATED} @code{read_VV} - equivalent to @code{ecl_init_module}
@node Shared library
@subsubsection Shared library
......@@ -282,7 +284,7 @@ Like with native FASL, the program may be built also from libraries.
@node Summary
@subsubsection Summary
In this post, some file types that can be compiled with ECL were
In this section, some file types that can be compiled with ECL were
introduced. Each file type has an adequate purpose:
@itemize
......@@ -383,9 +385,9 @@ To use it, we write a simple C program:
@verbatim
/* test.c */
#include <ecl/ecl.h>
extern void init_dll_example(cl_object);
int main (int argc, char **argv) {
extern void init_dll_example(cl_object);
cl_boot(argc, argv);
ecl_init_module(NULL, init_dll_example);
......
......@@ -10,7 +10,7 @@
* Higher level interfaces:: Usage examples
* SFFI Reference:: Static FFI reference
@c * LFFI Reference:: Library FFI reference /dlopen/
@c * DFFI Reference:: Dynamic FFI reference
* DFFI Reference:: Dynamic FFI reference
* UFFI Reference:: UFFI reference manual
@end menu
......@@ -141,7 +141,7 @@ higher level interface (Section 3.4).
The most important component of the object is the memory region where
data is stored. By default ECL assumes that the user will perform
automatic management of this memory, deleting the object when it is no
manual management of this memory, deleting the object when it is no
longer needed. The first reason is that this block may have been
allocated by a foreign routine using @code{malloc()}, or
@code{mmap()}, or statically, by referring to a C constant. The second
......@@ -302,5 +302,5 @@ Build and load this module with (compile-file "ecl.lsp" :load t)
@end lisp
@include extensions/ffi_sffi.txi
@c @include extensions/ffi_dffi.txi
@include extensions/ffi_dffi.txi
@include extensions/ffi_uffi.txi
......@@ -23,19 +23,19 @@ This special form inserts C code from strings passed in the
sources. Contrary to @code{ffi:c-inline}, this function may have no
executable statements, accepts no input value and returns no value.
The main use of @code{FFI:CLINES} is to declare or define C variables
The main use of @code{ffi:clines} is to declare or define C variables
and functions that are going to be used later in other FFI
statements. All statements from @var{arguments} are grouped at the
beginning of the produced header file.
@code{FFI:CLINES} is a special form that can only be used in lisp
@code{ffi:clines} is a special form that can only be used in lisp
compiled files as a toplevel form. Other uses will lead to an error
being signaled, either at the compilation time or when loading the
file.
@subsubheading Examples
@exindex @code{ffi:clines} adding c toplevel declarations
In this example the @code{FFI:CLINES} statement is required to get
In this example the @code{ffi:clines} statement is required to get
access to the C function @code{cos}:
@lisp
(ffi:clines "#include <math.h>")
......@@ -97,10 +97,10 @@ false, then the C template may be a more complicated block form, with
braces, conditionals, loops and spanning multiple lines. In this case
the output of the form can only be set using @verb{|@(return)|}.
Parameter @var{side-effects} set to true will indicate, that the
Parameter @var{side-effects} set to false will indicate, that the
functions causes no side-effects. This information is used by the
compiler to optimize the resulting code. If @var{side-effects} is set to
true, but the function may cause the side effects, then results are
false, but the function may cause the side effects, then results are
undefined.
Note that the conversion between lisp arguments and FFI types is
......
......@@ -197,7 +197,7 @@ Aggregate types are comprised of one or more primitive types.
@subsubheading Reference
@lspindex ffi:def-enum
@defmac ffi:def-enum name fields &key separator-key
@defmac ffi:def-enum name fields &key separator-string
Defines a C enumeration
......@@ -281,16 +281,16 @@ Retrieves a value from a slot of a structure
@item obj
A pointer to the foreign structure.
@item type
A name of the foreign structure.
The name of the foreign structure.
@item field
A name of the desired field in foreign structure.
The name of the desired field in the foreign structure.
@item returns
The value of the @code{field} in the structure @code{obj}.
@end table
@subsubheading Description
Accesses a slot value from a structure. This is generalized and can be
used with @code{SETF}-able.
used with @code{setf}.
@subsubheading Examples
@exindex @code{ffi:get-slot-value} manipulating a struct field
......@@ -311,16 +311,16 @@ Retrieves a pointer from a slot of a structure
@item obj
A pointer to the foreign structure.
@item type
A name of the foreign structure.
The name of the foreign structure.
@item field
A name of the desired field in foreign structure.
The name of the desired field in the foreign structure.
@item returns
The value of the pointer @var{field} in the structure @var{obj}.
@end table
@subsubheading Description
This is similar to get-slot-value. It is used when the value of a slot
is a pointer type.
This is similar to @code{get-slot-value}. It is used when the value of
a slot is a pointer type.
@subsubheading Examples
@exindex @code{ffi:get-slot-value} usage
......@@ -376,7 +376,7 @@ The value stored in the @var{position} of the @var{array}.
@subsubheading Description
Dereferences (retrieves) the value of the foreign array
element. @code{SETF}-able.
element. @code{setf}-able.
@subsubheading Examples
@exindex @code{ffi:deref-array} retrieving array element
......@@ -400,7 +400,7 @@ Defines a foreign union type
@item name
A name of the new union type.
@item fields
A list of fields of the union in form @code{(field-name fields-type)}.
A list of fields of the union in form @code{(field-name field-type)}.
@end table
@subsubheading Description
......@@ -569,11 +569,11 @@ The value of the object where the pointer points.
@end table
@subsubheading Description
Returns the object to which a pointer points. @code{SETF}-able.
Returns the object to which a pointer points. @code{setf}-able.
@subsubheading Notes
Casting of the pointer may be performed with @code{WITH-CAST-POINTER}
together with the @code{DEREF-POINTER}/@code{DEREF-ARRAY}.
Casting of the pointer may be performed with @code{with-cast-pointer}
together with the @code{deref-pointer}/@code{deref-array}.
@subsubheading Examples
@exindex @code{ffi:deref-pointer}
......@@ -601,7 +601,7 @@ A character.
@subsubheading Description
Ensures that an objects obtained by dereferencing @code{:char} and
@code{:unsigned-char} pointers are a lisp character.
@code{:unsigned-char} pointers is a lisp character.
@subsubheading Examples
@exindex @code{ffi:ensure-char-character}
......@@ -698,9 +698,9 @@ The value of the object where the pointer points.
@end table
@subsubheading Description
Executes @var{BODY} with @var{PTR} cast to be a pointer to type
@var{FTYPE}. @var{VAR} is will be bound to this value during the
execution of @var{BODY}.
Executes @var{body} with @var{ptr} cast to be a pointer to type
@var{ftype}. @var{var} will be bound to this value during the
execution of @var{body}.
@subsubheading Examples
@exindex @code{ffi:with-cast-pointer}
......@@ -727,16 +727,16 @@ Defines a symbol macro to access a variable in foreign code
@item name
A string or list specifying the symbol macro's name. If it is a
string, that names the foreign variable. A Lisp name is created by
translating @code{#\_} to @code{#\-} and by converting to upper-case in
case-insensitive Lisp implementations.
translating @code{#\_} to @code{#\-} and by converting to upper-case.
If it is a list, the first item is a string specifying the foreign
variable name and the second it is a symbol stating the Lisp name.
@item type
A foreign type of the foreign variable.
@item module
A string specifying the module (or library) the foreign variable resides
in.
Either a string specifying the module (or library) the foreign
variable resides in, @code{:default} if no module needs to be loaded
or @code{NIL} to use SFFI.
@end table
@subsubheading Description
......@@ -788,17 +788,16 @@ Lisp code defining C structure, function and a variable:
@cindex Foreign strings
@subsubheading Overview
@cindex @code{cstring} and @code{foreign string} differences
@cindex cstring and foreign string differences
UFFI has functions to two types of C-compatible strings:
@code{cstring} and foreign strings. @code{cstring}s are used only as
parameters to and from functions. In some implementations a
@code{cstring} is not a foreign type but rather the Lisp string
itself. On other platforms a cstring is a newly allocated foreign
vector for storing characters. The following is an example of using
@code{cstring}s to both send and return a value.
UFFI has functions to two types of C-compatible strings: cstrings and
foreign strings. cstrings are used only as parameters to and from
functions. In some implementations a cstring is not a foreign type but
rather the Lisp string itself. On other platforms a cstring is a newly
allocated foreign vector for storing characters. The following is an
example of using cstrings to both send and return a value.
@exindex @code{cstring} used to send and return a value
@exindex cstring used to send and return a value
@lisp
(ffi:def-function ("getenv" c-getenv)
((name :cstring))
......@@ -817,7 +816,7 @@ hold the return value of a string, you must use a foreign string and not
a cstring. The following is an example of using a foreign string for a
return value.
@exindex @code{foreign string} used to send and return a value
@exindex foreign string used to send and return a value
@lisp
(ffi:def-function ("gethostname" c-gethostname)
((name (* :unsigned-char))
......@@ -838,11 +837,11 @@ return value.
@end lisp
Foreign functions that return pointers to freshly allocated strings
should in general not return @code{cstring}s, but @code{foreign
strings}. (There is no portable way to release such @code{cstring}s from
Lisp.) The following is an example of handling such a function.
should in general not return cstrings, but foreign strings. (There is
no portable way to release such cstrings from Lisp.) The following is
an example of handling such a function.
@exindex Conversion between @code{foreign string} and @code{cstring}
@exindex Conversion between foreign string and cstring
@lisp
(ffi:def-function ("readline" c-readline)
((prompt :cstring))
......@@ -864,9 +863,9 @@ Lisp.) The following is an example of handling such a function.
Converts a @code{cstring} to a Lisp string
@table @var
@item object
@code{cstring}
A @code{cstring}
@item returns
Lisp string
A Lisp string
@end table
@subsubheading Description
......@@ -879,9 +878,9 @@ processing the results of a foreign function that returns a cstring.
Converts a Lisp string to a @code{cstring}
@table @var
@item object
Lisp string
A Lisp string
@item returns
@code{cstring}
A @code{cstring}
@end table
@subsubheading Description
......@@ -951,7 +950,7 @@ Result of evaluating the @var{body}.
@subsubheading Description
Binds a symbols to a @code{cstring}s created from conversion of a
@var{string}s. Automatically frees the @var{cstring}s. This macro works
similar to @code{LET*}. Based on @code{with-cstring}.
similar to @code{let*}. Based on @code{with-cstring}.
@end defmac
@lspindex ffi:convert-from-foreign-string
......@@ -975,7 +974,7 @@ binary strings.
@end defmac
@lspindex ffi:convert-to-foreign-string
@defmac ffi:convert-to-foreign-string
@defmac ffi:convert-to-foreign-string string
Converts a Lisp string to a foreign string
@table @var
@item string
......@@ -1040,7 +1039,7 @@ Result of evaluating the @var{body}.
@subsubheading Description
Binds a symbols to a @code{foreign-string}s created from conversion of a
@var{string}s. Automatically frees the @var{foreign-string}s. This macro
works similar to @code{LET*}. Based on @code{with-foreign-string}.
works similar to @code{let*}. Based on @code{with-foreign-string}.
@end defmac
@node Functions and Libraries
......@@ -1063,8 +1062,9 @@ symbol stating the Lisp name.
A list of argument declarations. If @code{NIL}, indicates that the function
does not take any arguments.
@item module
A string specifying which module (or library) that the foreign function
resides.
Either a string specifying which module (or library) that the foreign
function resides, @code{:default} if no module needs to be loaded or
@code{NIL} to use SFFI.
@item call
Function calling convention. May be one of @code{:default}, @code{:cdecl},
@code{:sysv}, @code{:stdcall}, @code{:win64} and
......@@ -1074,8 +1074,8 @@ This argument is used only when we're using the dynamic function
interface. If ECL is built without the DFFI support, then it uses SFFI
the @var{call} argument is ignored.
@item returning
A declaration specifying the result type of the foreign function. If
@code{:void} indicates module does not return any value.
A declaration specifying the result type of the foreign function.
@code{:void} indicates that the function does not return any value.
@end table
@subsubheading Description
Declares a foreign function.
......
......@@ -56,7 +56,7 @@ The customizable limits are listed in @ref{tab:mem-limits}, but they need a care
@item
@code{ext:binding-stack} controls the number of nested bindings for special variables. The current value is usually safe enough, unless you have deep recursive functions that bind special variables, which is not really a good idea.
@item
@code{ext:frame-stack} controls the number of nested blocks, tagbody and other control structures. It affects both interpreted and compiled code, but quite often compiled code optimizes away these stack frames, saving memory and not being affected by this limit.
@code{ext:frame-stack} controls the number of nested blocks, tagbodys and other control structures. It affects both interpreted and compiled code, but quite often compiled code optimizes away these stack frames, saving memory and not being affected by this limit.
@item
@code{ext:lisp-stack} controls the size of the interpreter stack. It only affects interpreted code.
@end itemize
......
......@@ -50,7 +50,7 @@ This condition is signaled when ECL exhausts the @code{ext:heap-size} limit from
@item
If the heap size had a finite limit, ECL offers the user the chance to resize it, issuing a restartable condition. The user may at this point use @code{(ext:set-limit 'ext:heap-size 0)} to remove the heap limit and avoid further messages, or use the @code{(continue)} restart to let ECL enlarge the heap by some amount.
@item
Independently of the heap size limit, if ECL finds that there is no space to free or to grow, ECL simply quits. There will be no chance to do some cleanup because there is no way to cons any additional data.
Independently of the heap size limit, if ECL finds that there is no space to free or to grow, ECL simply quits. There will be no chance to do some cleanup because there is no way to allocate any additional data.
@end itemize
@end deftp
......
......@@ -9,15 +9,15 @@
@subsection Introduction
The Meta-Object Protocol is an extension to Common Lisp which provides rules, functions and a type structure to handle the object system. It is a reflective system, where classes are also objects and can be created and manipulated using very well defined procedures.
The Meta-Object Protocol associated to Common Lisp's object system was introduced in a famous book, The Art of the Metaobject Protocol AMOP (@xref{Bibliography}), which was probably intended for the ANSI (@xref{Bibliography}) specification but was drop out because of its revolutionary and then not too well tested ideas.
The Meta-Object Protocol associated to Common Lisp's object system was introduced in a famous book, The Art of the Metaobject Protocol AMOP @bibcite{AMOP}, which was probably intended for the ANSI @bibcite{ANSI} specification but was dropped because of its revolutionary and then not too well tested ideas.
The AMOP is present, in one way or another, in most Common Lisp implementations, either using proprietary systems or because their implementation of CLOS descended from PCL (Portable CommonLoops). It has thus become a de facto standard and ECL should not be without it.
Unfortunately ECL's own implementation originally contained only a subset of the AMOP. This was a clever decision at the time, since the focus was on performance and on producing a stable and lean implementation of Common Lisp. Nowadays it is however not an option, specially given that most of the AMOP can be implemented with little cost for both the implementor and the user.
Unfortunately ECL's own implementation originally contained only a subset of the AMOP. This was a clever decision at the time, since the focus was on performance and on producing a stable and lean implementation of Common Lisp. Nowadays it is however not an option, especially given that most of the AMOP can be implemented with little cost for both the implementor and the user.
So ECL has an almost complete implementation of the AMOP. However, since it was written from scratch and progressed according to user's request and our own innovations, there might still be some missing functionality which we expect to correct in the near future. Please report any feature you miss as a bug through the appropriate channels.
When considering the Metaobject Protocol, the book itself should be the main reference. The following sections contain only further extensions or improvements over the paragraphs which were either conflicting or less specified.
@c When considering the Metaobject Protocol, the book itself should be the main reference. The following sections contain only further extensions or improvements over the paragraphs which were either conflicting or less specified.
@c @node MOP - Classes
@c @subsection Classes
......
......@@ -140,7 +140,7 @@ the result would be unpredictable.
(loop repeat 1000 do
(mp:atomic-update (test-struct-slot1 struct) #'1+)
(sleep 0.00001))))))
(slot-value object 'slot1))
(test-struct-slot1 struct))
=> 100000
@end lisp
@end defmac
......
......@@ -12,7 +12,7 @@ can't).
@cppindex ecl_make_lock
@deftypefun ecl_make_lock (cl_object name, bool recursive)
@deftypefun cl_object ecl_make_lock (cl_object name, bool recursive)
C/C++ equivalent of @code{mp:make-lock} without @code{key} arguments.
See @code{mp:make-lock}.
......@@ -121,8 +121,7 @@ Releases @code{lock}.
@defmac mp:with-lock (lock-form) &body body
Acquire lock for the dynamic scope of @code{body}, which is executed
with the lock held by current thread, and @code{with-lock} returns the
values of body.
with the lock held by current thread. Returns the values of body.
@c (lock-form &key wait-p timeout)
......
......@@ -16,7 +16,7 @@ Process is a primitive representing native thread.
Returns the list of processes associated to running tasks. The list is a
fresh new one and can be destructively modified. However, it may happen
that the output list is not up to date, because some of the tasks has
that the output list is not up to date, because some of the tasks have
expired before this copy is returned.
@end defun
......@@ -49,6 +49,16 @@ Interrupt a task. This @code{function} sends a signal to a running
@code{process}. When the task is free to process that signal, it will
stop whatever it is doing and execute the given function.
@strong{WARNING:} Use with care! Interrupts can happen anywhere,
except in code regions explicitely protected with
@code{mp:without-interrupts}. This can lead to dangerous situations
when interrupting functions which are not thread safe. In particular,
one has to consider:
@itemize
@item Reentrancy: Functions, which usually are not called recursively can be re-entered during execution of the interrupt.
@item Stack unwinding: Non-local jumps like @code{throw} or @code{return-from} in the interrupting code will handle @code{unwind-protect} forms like usual. However, the cleanup forms of an @code{unwind-protect} can still be interrupted. In that case the execution flow will jump to the next @code{unwind-protect}.
@end itemize
@exindex Process interruption
Example:
......@@ -75,10 +85,13 @@ Kill a task that is doing nothing (See @code{mp:process-kill}).
@defun mp:make-process &key name initial-bindings
Create a new thread. This function creates a separate task with a name
set to @code{name}, set of variable bindings @code{initial-bindings}
and no function to run. See also @code{mp:process-run-function}. Returns
newly created process.
set to @code{name} and no function to run. See also
@code{mp:process-run-function}. Returns newly created process.
If @code{initial-bindings} is false, the new process inherits local
bindings to special variables (i.e. binding a special variable with
@code{let} or @code{let*}) from the current thread, otherwise the new
thread possesses no local bindings.
@end defun
......@@ -336,7 +349,7 @@ effect during the dynamic scope of its body, unless there is an outer
@code{allow-with-interrupts}.
@code{with-local-interrupts} executes its body with interrupts enabled
provided that for there is an @code{allow-with-interrupts} for every
provided that there is an @code{allow-with-interrupts} for every
@code{without-interrupts} surrounding the current
one. @code{with-local-interrupts} is equivalent to:
......
......@@ -5,10 +5,13 @@
@cindex Readers-writer locks
@cindex Shared-exclusive locks
Readers-writer (or shared-exclusive ) lock allows concurrent access for
read-only operations and write operations require exclusive
Readers-writer (or shared-exclusive ) locks allow concurrent access
for read-only operations, while write operations require exclusive
access. @code{mp:rwlock} is non-recursive.
Readers-writers locks are an optional feature, which is available if
@code{*features*} includes @code{:ecl-read-write-lock}.
@node Readers-writer locks dictionary
@subsection Read-Write locks dictionary
......@@ -16,7 +19,7 @@ access. @code{mp:rwlock} is non-recursive.
@cppindex ecl_make_rwlock
@deftypefun ecl_make_rwlock (cl_object name)
@deftypefun cl_object ecl_make_rwlock (cl_object name)
C/C++ equivalent of @code{mp:make-rwlock} without @code{key} arguments.
See @code{mp:make-rwlock}.
......@@ -105,11 +108,11 @@ Release @code{lock}.
@lspindex mp:with-rwlock
@defmac mp:with-rwlock (lock op) &body body
@defmac mp:with-rwlock (lock operation) &body body
Acquire rwlock for the dynamic scope of @code{body} for operation
@code{op}, which is executed with the lock held by current thread, and
@code{with-rwlock} returns the values of body.
@code{operation}, which is executed with the lock held by current
thread. Returns the values of body.
Valid values of argument @code{op} are @code{:read} or @code{:write}
(for reader and writer access accordingly).
Valid values of argument @code{operation} are @code{:read} or
@code{:write} (for reader and writer access accordingly).
@end defmac
......@@ -76,7 +76,7 @@ A lisp form, not evaluated, where numbers from 0 to nargs will be
replaced by the corresponding option argument.
@end defvr
@defvr opt :STOP
@defvr opt :stop
If present, parsing of arguments stops after this option is found and
processed. The list of remaining arguments is passed to the
rule. ECL's top-level uses this option with the @code{--} command line
......@@ -84,10 +84,10 @@ option to set @code{ext:*unprocessed-ecl-command-args*} to the list of
remaining arguments.
@end defvr
@defvr opt :NOLOADRC
@defvrx opt :LOADRC
Determine whether the lisp initialization file
@code{(ext:*lisp-init-file-list*)} will be loaded before processing
@defvr opt :noloadrc
@defvrx opt :loadrc
Determine whether the lisp initialization files in
@code{ext:*lisp-init-file-list*} will be loaded before processing
all forms.
@end defvr
......@@ -104,7 +104,7 @@ constructs a lisp statement using the template.
After all arguments have been processed,
@code{ext:process-command-args}, and there were no occurrences of
@code{:noloadrc}, one of the files listed in
@code{:noloadrc}, the first existing file listed in
@code{ext:*lisp-init-file-list*} will be loaded. Finally, the list of
lisp statements will be evaluated.
@end defun
......
......@@ -20,18 +20,20 @@ has been specified. Different packages can use same local nickname for
different global names, or different local nickname for same global
name.
Symbol :package-local-nicknames in *features* denotes the support for
this feature.
The keyword @code{:package-local-nicknames} in @code{*features*}
indicates the support for this feature.
@subsection Package local nicknames dictionary
@defmac cl:defpackage name [[options]]*
Options are extended to include
@example
:local-nicknames (local-nickname actual-package-name)*
@end example
The package has the specified local nicknames for the
corresponding actual packages.
The package has the specified local nicknames for the
corresponding actual packages.
@exindex defpackage and package local nicknames
Example:
......@@ -43,41 +45,44 @@ Example:
(find-symbol "X" :foo) ; => FOO::X
(find-symbol "X" :bar) ; => BAR::X
(let ((*package* (find-package :quux)))
(find-symbol "X" :foo)) ; => BAR::X
(find-symbol "X" :foo)) ; => BAR::X
(let ((*package* (find-package :quux)))
(find-symbol "X" :bar)) ; => FOO::X
(find-symbol "X" :bar)) ; => FOO::X
@end lisp
@end defmac
@lspindex ext:package-local-nicknames
@cppindex si_package_local_nicknames
@deffn {ext} {package-local-nicknames} package-designator
@deffnx {C/C++} {si_package_local_nicknames} package-designator
@defun {ext:package-local-nicknames} package-designator
@end defun
@deftypefun cl_object si_package_local_nicknames (cl_object package_designator)
Returns an alist of @code{(local-nickname . actual-package)}
describing the nicknames local to the designated package.
When in the designated package, calls to @t{FIND-PACKAGE} with the any
When in the designated package, calls to @code{find-package} with any
of the local-nicknames will return the corresponding actual-package
instead. This also affects all implied calls to @t{FIND-PACKAGE},
instead. This also affects all implied calls to @code{find-package},
including those performed by the reader.
When printing a package prefix for a symbol with a package local nickname, the
local nickname is used instead of the real name in order to preserve
print-read consistency.
@end deffn
@end deftypefun
@lspindex ext:package-locally-nicknamed-by-list
@cppindex si_package_locally_nicknamed_by_list
@deffn {ext} {package-locally-nicknamed-by-list} package-designator
@deffnx {C/C++} si_package_local_nicknames package-designator
@defun {ext:package-locally-nicknamed-by-list} package-designator
@end defun
@deftypefun cl_object si_package_locally_nicknamed_by_list (cl_object package_designator)
Returns a list of packages which have a local nickname for the
designated package.
@end deffn
@end deftypefun
@lspindex ext:add-package-local-nickname
@cppindex si_add_package_local_nickname
@deffn {ext} {add-package-local-nickname} local-nickname actual-package &optional package-designator
@deffnx {C/C++} {si_add_package_local_nickname} local-nickname actual-package package-designator
@defun {ext:add-package-local-nickname} local-nickname actual-package &optional package-designator
@end defun
@deftypefun cl_object si_add_package_local_nickname (cl_object local_nickname, cl_object actual_package, cl_object package_designator)
Adds @var{local-nickname} for @var{actual-package} in the designated
package, defaulting to current package. @var{local-nickname} must be a
string designator, and @var{actual-package} must be a package
......@@ -88,24 +93,25 @@ Returns the designated package.
Signals a continuable error if @var{local-nickname} is already a
package local nickname for a different package.
When in the designated package, calls to @t{find-package} with the
When in the designated package, calls to @code{find-package} with the
@var{local-nickname} will return the package the designated
@var{actual-package} instead. This also affects all implied calls to
@t{find-package}, including those performed by the reader.
@code{find-package}, including those performed by the reader.
When printing a package prefix for a symbol with a package local
nickname, local nickname is used instead of the real name in order to
preserve print-read consistency.
@end deffn
nickname, the local nickname is used instead of the real name in order
to preserve print-read consistency.
@end deftypefun
@lspindex ext:remove-package-local-nickname
@cppindex si_remove_package_local_nickname
@deffn {ext} {remove-package-local-nickname} old-nickname &optional package-designator
@deffnx {C/C++} {si_remove_package_local_nickname} old-nickname package-designator
@defun {ext:remove-package-local-nickname} old-nickname &optional package-designator
@end defun
@deftypefun cl_object si_remove_package_local_nickname (cl_object old_nickname, cl_object package_designator)
If the designated package had @var{old-nickname} as a local nickname
for another package, it is removed. Returns true if the nickname
existed and was removed, and @t{NIL} otherwise.
@end deffn
existed and was removed, and @code{NIL} otherwise.
@end deftypefun
@node Package locks
@section Package locks
......@@ -117,9 +123,9 @@ existed and was removed, and @t{NIL} otherwise.
ECL borrows parts of the protocol and documentation from SBCL for
compatibility. Interface is the same except that the home package for
locking is ext and that ECL doesn't implement Implementation Packages
and a few constructs. To load the extension you need to require
@code{package-locks}:
locking is @code{ext} and that ECL doesn't implement Implementation
Packages and a few constructs. To load the extension you need to
require @code{package-locks}:
@lisp
(require '#:package-locks)
......
......@@ -54,7 +54,7 @@ In addition to the set of synchronous signals or "exceptions", we have a set of
@itemize
@item Request for program termination (@code{SIGKILL}, @code{SIGTERM}).
@item Indication that a child process has finished.
@item Request for program interruption (@code{SIGINT}), typically as a consequence of pressing a key combination, @kbd{Ctrl-C}.
@item Request for program interruption (@code{SIGINT}), typically as a consequence of pressing a key combination, e.g. @kbd{Ctrl-C}.
@end itemize
The important difference with synchronous signals is that we have no thread that causes the interrupt and thus there is no preferred way of handling them. Moreover, the operating system will typically dispatch these signals to an arbitrary thread, unless we set up mechanisms to prevent it. This can have nasty consequences if the incoming signal interrupt a system call, or leaves the interrupted thread in an inconsistent state.
......@@ -101,7 +101,7 @@ Systems that embed ECL and want to allow handling of synchronous signals should
@subsection Considerations when embedding ECL
There are several approaches when handling signals and interrupts in a program that uses ECL. One is to install your own signal handlers. This is perfectly fine, but you should respect the same restrictions as ECL. Namely, you may not execute arbitrary code from those signal handlers, and in particular it will not always be safe to execute Common Lisp code from there.
If you want to use your own signal handlers then you should set the appropriate options before invoking @code{cl_boot()}, as explained in @code{ecl_set_option}. Note that in this case ECL will not always be able to detect floating point exceptions, specially if your compiler does not support C99 and the corresponding floating point flags.
If you want to use your own signal handlers then you should set the appropriate options before invoking @code{cl_boot()}, as explained in @code{ecl_set_option}. Note that in this case ECL will not always be able to detect floating point exceptions.
The other option is to let ECL handle signals itself. This would be safer when the dominant part of the code is Common Lisp, but you may need to protect the code that embeds ECL from being interrupted using either the macros @code{ecl_disable_interrupts} and @code{ecl_enable_interrupts} or the POSIX functions @code{pthread_sigmaks}and @code{sigprocmask}.
......
......@@ -35,11 +35,11 @@ Follow the execution of functions
(trace @var{function-name*})
@table @var
@item function-name
@{@var{symbol} | (@var{symbol} [ @var{option} @var{form} ]*)@}
@{@var{symbol} | (@var{symbol} [@var{option} @var{form}]*)@}
@item symbol
A symbol which is bound to a function in the global environment. Not evaluated.
@item option
One of @code{:BREAK, :BREAK-AFTER, :COND-BEFORE, :COND-AFTER, :COND, :PRINT, :PRINT-AFTER, :STEP}
One of @code{:break}, @code{:break-after}, @code{:cond-before}, @code{:cond-after}, @code{:cond}, @code{:print}, @code{:print-after}, @code{:step}
@item form
A lisp form evaluated in an special environment.
@item returns
......@@ -56,14 +56,14 @@ trace returns a name list of those functions that were traced by the call to tra
Trace options cause the normal printout to be suppressed, or cause extra information to be printed. Each option is a pair of an option keyword and a value form. If an already traced function is traced again, any new options replace the old options and a warning might be printed. The lisp @emph{form} accompanying the option is evaluated in an environment where @var{sys::args} contains the list of arguments to the function.