From 3c3a02ea7dbd4e0341a2df23d4ef9ef3911d8975 Mon Sep 17 00:00:00 2001 From: Marius Gerbershagen Date: Wed, 2 Jan 2019 12:27:02 +0100 Subject: [PATCH] doc: improvements to extensions section Use consistent formatting, fix errors and typos. --- src/doc/new-doc/developer-guide/dpp.txi | 5 + src/doc/new-doc/extensions/building.txi | 28 +++--- src/doc/new-doc/extensions/ffi.txi | 6 +- src/doc/new-doc/extensions/ffi_sffi.txi | 10 +- src/doc/new-doc/extensions/ffi_uffi.txi | 92 +++++++++---------- src/doc/new-doc/extensions/memory.txi | 2 +- src/doc/new-doc/extensions/memory_ref.txi | 2 +- src/doc/new-doc/extensions/mop.txi | 6 +- src/doc/new-doc/extensions/mp_ref_atomic.txi | 2 +- src/doc/new-doc/extensions/mp_ref_mutex.txi | 5 +- src/doc/new-doc/extensions/mp_ref_process.txi | 23 ++++- src/doc/new-doc/extensions/mp_ref_rwlock.txi | 19 ++-- src/doc/new-doc/extensions/osi.txi | 12 +-- src/doc/new-doc/extensions/packages.txi | 62 +++++++------ src/doc/new-doc/extensions/signals.txi | 4 +- src/doc/new-doc/standards/environment.txi | 14 +-- src/doc/status.org | 4 +- 17 files changed, 162 insertions(+), 134 deletions(-) diff --git a/src/doc/new-doc/developer-guide/dpp.txi b/src/doc/new-doc/developer-guide/dpp.txi index 8aab99207..7585d96f9 100644 --- a/src/doc/new-doc/developer-guide/dpp.txi +++ b/src/doc/new-doc/developer-guide/dpp.txi @@ -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 diff --git a/src/doc/new-doc/extensions/building.txi b/src/doc/new-doc/extensions/building.txi index 187bb7811..124997887 100644 --- a/src/doc/new-doc/extensions/building.txi +++ b/src/doc/new-doc/extensions/building.txi @@ -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 +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); diff --git a/src/doc/new-doc/extensions/ffi.txi b/src/doc/new-doc/extensions/ffi.txi index ea6782e79..134118610 100644 --- a/src/doc/new-doc/extensions/ffi.txi +++ b/src/doc/new-doc/extensions/ffi.txi @@ -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 diff --git a/src/doc/new-doc/extensions/ffi_sffi.txi b/src/doc/new-doc/extensions/ffi_sffi.txi index f17d36b0c..9013e3fd2 100644 --- a/src/doc/new-doc/extensions/ffi_sffi.txi +++ b/src/doc/new-doc/extensions/ffi_sffi.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 ") @@ -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 diff --git a/src/doc/new-doc/extensions/ffi_uffi.txi b/src/doc/new-doc/extensions/ffi_uffi.txi index 4b9da731a..2d3c9da4c 100644 --- a/src/doc/new-doc/extensions/ffi_uffi.txi +++ b/src/doc/new-doc/extensions/ffi_uffi.txi @@ -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. diff --git a/src/doc/new-doc/extensions/memory.txi b/src/doc/new-doc/extensions/memory.txi index 228ae8f40..3c767d496 100644 --- a/src/doc/new-doc/extensions/memory.txi +++ b/src/doc/new-doc/extensions/memory.txi @@ -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 diff --git a/src/doc/new-doc/extensions/memory_ref.txi b/src/doc/new-doc/extensions/memory_ref.txi index ca0968c1a..8810f2d07 100644 --- a/src/doc/new-doc/extensions/memory_ref.txi +++ b/src/doc/new-doc/extensions/memory_ref.txi @@ -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 diff --git a/src/doc/new-doc/extensions/mop.txi b/src/doc/new-doc/extensions/mop.txi index d1a291817..a1b903e10 100644 --- a/src/doc/new-doc/extensions/mop.txi +++ b/src/doc/new-doc/extensions/mop.txi @@ -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 diff --git a/src/doc/new-doc/extensions/mp_ref_atomic.txi b/src/doc/new-doc/extensions/mp_ref_atomic.txi index 9e812011d..c99b34011 100644 --- a/src/doc/new-doc/extensions/mp_ref_atomic.txi +++ b/src/doc/new-doc/extensions/mp_ref_atomic.txi @@ -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 diff --git a/src/doc/new-doc/extensions/mp_ref_mutex.txi b/src/doc/new-doc/extensions/mp_ref_mutex.txi index caa324134..8fdcd813c 100644 --- a/src/doc/new-doc/extensions/mp_ref_mutex.txi +++ b/src/doc/new-doc/extensions/mp_ref_mutex.txi @@ -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) diff --git a/src/doc/new-doc/extensions/mp_ref_process.txi b/src/doc/new-doc/extensions/mp_ref_process.txi index 7b1f1437c..91fd97383 100644 --- a/src/doc/new-doc/extensions/mp_ref_process.txi +++ b/src/doc/new-doc/extensions/mp_ref_process.txi @@ -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: diff --git a/src/doc/new-doc/extensions/mp_ref_rwlock.txi b/src/doc/new-doc/extensions/mp_ref_rwlock.txi index 9461d0a9c..64d10fc9f 100644 --- a/src/doc/new-doc/extensions/mp_ref_rwlock.txi +++ b/src/doc/new-doc/extensions/mp_ref_rwlock.txi @@ -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 diff --git a/src/doc/new-doc/extensions/osi.txi b/src/doc/new-doc/extensions/osi.txi index f1e4631c9..a7e649cfa 100644 --- a/src/doc/new-doc/extensions/osi.txi +++ b/src/doc/new-doc/extensions/osi.txi @@ -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 diff --git a/src/doc/new-doc/extensions/packages.txi b/src/doc/new-doc/extensions/packages.txi index 53238a3e3..cc36c5059 100644 --- a/src/doc/new-doc/extensions/packages.txi +++ b/src/doc/new-doc/extensions/packages.txi @@ -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) diff --git a/src/doc/new-doc/extensions/signals.txi b/src/doc/new-doc/extensions/signals.txi index 41291bbc6..9c1844b72 100644 --- a/src/doc/new-doc/extensions/signals.txi +++ b/src/doc/new-doc/extensions/signals.txi @@ -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}. diff --git a/src/doc/new-doc/standards/environment.txi b/src/doc/new-doc/standards/environment.txi index b55b37c5e..85f6312e8 100644 --- a/src/doc/new-doc/standards/environment.txi +++ b/src/doc/new-doc/standards/environment.txi @@ -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. The following options are defined: -@table @code -@item :cond, :cond-before, :cond-after +@table @asis +@item @code{:cond}, @code{:cond-before}, @code{:cond-after} If @code{:cond-before} is specified, then @code{trace} does nothing unless @var{form} evaluates to true at the time of the call. @code{:cond-after} is similar, but suppresses the initial printout, and is tested when the function returns. @code{:cond} tries both before and after. -@item :step +@item @code{:step} If @var{form} evaluates to true, the stepper is entered. -@item :break, :break-after +@item @code{:break}, @code{:break-after} If specified, and @var{form} evaluates to true, then the debugger is invoked at the start of the function or at the end of the function according to the respective option. -@item :print, :print-after +@item @code{:print}, @code{:print-after} In addition to the usual printout, the result of evaluating @var{form} is printed at the start of the function or at the end of the function, depending on the option. Multiple print options cause multiple values to be output, in the order in which they were introduced. @end table @end defmac diff --git a/src/doc/status.org b/src/doc/status.org index 8596d0d69..420b2e222 100644 --- a/src/doc/status.org +++ b/src/doc/status.org @@ -22,7 +22,7 @@ - [ ] Embedding ECL * Developer's guide -- [ ] Source code structure +- [-] Source code structure - [ ] Contributing - Source documentation - [ ] Modules hierarchy @@ -75,4 +75,4 @@ Many nodes, moderate amount of content (deviations from the standard) #+END_SRC * Things to fix -- [ ] Add :long-double to the UFFI interface +- [X] Add :long-double to the UFFI interface