From b5a771e7bcebe95f897a08313941b299ce9c16df Mon Sep 17 00:00:00 2001 From: William Harold Newman Date: Sat, 8 Nov 2003 01:32:02 +0000 Subject: [PATCH] 0.8.5.25: merged Miles Egan's general SGML cleanup manual patch (from sbcl-devel today) deleted "!ENTITY mdash" hack (since ME's patch reminded me that at some point I learned that DocBook itself seems to define mdash) --- doc/beyond-ansi.sgml | 28 +++++++++++++++++++++++++--- doc/compiler.sgml | 4 ++-- doc/ffi.sgml | 23 ++++++++++++++++++++--- doc/intro.sgml | 3 +-- doc/user-manual.sgml | 3 --- version.lisp-expr | 2 +- 6 files changed, 49 insertions(+), 14 deletions(-) diff --git a/doc/beyond-ansi.sgml b/doc/beyond-ansi.sgml index 388ebdf..c29fd52 100644 --- a/doc/beyond-ansi.sgml +++ b/doc/beyond-ansi.sgml @@ -155,13 +155,16 @@ system's concept of threads or lightweight processes. can be found in the sb-thread package. This is intended for public consumption, so look at the exported symbols and their documentation strings. + Dynamic bindings to symbols are per-thread. Signal handlers are per-thread. + sb-ext:quit exits the current thread, not necessarily the whole environment. The environment will be shut down when the last thread exits. + Threads arbitrate between themselves for the user's attention. A thread may be in one of three notional states: foreground, @@ -171,6 +174,7 @@ saying that it has stopped. The user at his leisure may switch to that thread to find out what it needs. If a background thread enters the debugger, selecting any restart will put it back into the background before it resumes. + If the user has multiple views onto the same Lisp image (for example, using multiple terminals, or a windowing system, or network @@ -178,21 +182,23 @@ access) they are typically set up as multiple `sessions' such that each view has its own collection of foreground/background/stopped threads. sb-thread:make-listener-thread can be used to start a new thread in its own `session'. + Mutexes and condition variables are available for managing access to shared data: see - (apropos "mutex" :sb-thread) + (apropos "condition" :sb-thread) + and the waitqueue structure - -and poke around in their documentation strings. +and poke around in their documentation strings. + Implementation (Linux x86) @@ -203,16 +209,19 @@ se, but there is plenty wrong (from our perspective) with LinuxThreads. &SBCL; threads are mapped 1:1 onto Linux tasks which share a VM but nothing else - each has its own process id and can be seen in e.g. ps output. + Per-thread local bindings for special variables is achieved using the %fs segment register to point to a per-thread storage area. This may cause interesting results if you link to foreign code that expects threading or creates new threads, and the thread library in question uses %fs in an incompatible way. + Threads waiting on queues (e.g. for locks or condition variables) are put to sleep using sigtimedwait() and woken with SIGCONT. + &SBCL; at present will alway have at least two tasks running as seen from Linux: when the first process has done startup @@ -220,6 +229,7 @@ initialization (mapping files in place, installing signal handlers etc) it creates a new thread to run the Lisp startup and initial listener. The original thread stays around to reap dead subthreads and deallocate their resources (e.g. stacks) when they exit. + Garbage collection is done with the existing Conservative Generational GC. Allocation is done in small (typically 8k) regions : @@ -231,11 +241,13 @@ interesting behaviour if they are interrupted in system calls. The streams interface is believed to handle the required system call restarting correctly, but this may be a consideration when making other blocking calls e.g. from foreign library code. + Large amounts of the &SBCL; library have not been inspected for thread-safety. Some of the obviously unsafe areas have large locks around them, so compilation and fasl loading, for example, cannot be parallelized. Work is ongoing in this area. + A new thread by default is created in the same POSIX process group and session as the thread it was created by. This has an impact @@ -245,12 +257,18 @@ process group, including Lisp threads that &SBCL; considers to be notionally `background'. This is undesirable, so background threads are set to ignore the SIGINT signal. Arbitration for the input stream is managed by locking on sb-thread::*session-lock* + A thread can be created in a new Lisp 'session' (new terminal or window) using sb-thread:make-listener-thread. These sessions map directly onto POSIX sessions, so that pressing Control-C in the wrong window will not interrupt them - this has been found to be embarrassing. + + + + + Support For Unix</> @@ -271,10 +289,14 @@ is also supported.</para> one argument is implementation-defined. In &SBCL; it calls functions on the user-settable list <varname>sb-ext:*module-provider-functions*</varname> - see the <function>require</function> documentation string for details. +</para> <para>The toplevel repl prompt may be customized, and the function that reads user input may be replaced completely. <!-- FIXME but I don't currently remember how --> +</para> + +</sect2> <sect2><title>Tools To Help Developers diff --git a/doc/compiler.sgml b/doc/compiler.sgml index 131508b..7ebc23f 100644 --- a/doc/compiler.sgml +++ b/doc/compiler.sgml @@ -1,7 +1,7 @@ The Compiler</> <para>This chapter will discuss most compiler issues other than -efficiency, including compiler error messages, the &SBCL compiler's +efficiency, including compiler error messages, the &SBCL; compiler's unusual approach to type safety in the presence of type declarations, the effects of various compiler optimization policies, and the way that inlining and open coding may cause optimized code to differ from @@ -344,7 +344,7 @@ _ --> <sect1><title>The Compiler's Handling of Types</> <para>The most unusual features of the &SBCL; compiler (which is -very similar to the original &CMUCL compiler, also known as +very similar to the original &CMUCL; compiler, also known as &Python;) is its unusually sophisticated understanding of the &CommonLisp; type system and its unusually conservative approach to the implementation of type declarations. These two features reward the diff --git a/doc/ffi.sgml b/doc/ffi.sgml index 5f11eab..b360261 100644 --- a/doc/ffi.sgml +++ b/doc/ffi.sgml @@ -41,6 +41,7 @@ are three common approaches to establishing communication: objects through the use of extensions to the Lisp language. </para></listitem> </itemizedlist> +</para> <para>&SBCL;, like &CMUCL; before it, relies primarily on the automatic conversion and direct manipulation approaches. The SB-ALIEN @@ -207,7 +208,7 @@ These are the basic foreign type specifiers: <varname>value</> is an integer. If <varname>value</> is not supplied, then it defaults to one greater than the value for the preceding spec (or to zero if it is the first spec.) - <para> + </para> </listitem> <listitem> <para> @@ -333,6 +334,10 @@ These are the basic foreign type specifiers: </itemizedlist> +</para> + +</sect2> + </sect1> <sect1><title>Operations On Foreign Values</> @@ -498,6 +503,8 @@ or C <function>malloc</>.</para> <para>See also the <function>sb-alien:with-alien</> macro, which allocates foreign values on the stack.</para> +</sect2> + </sect1> <sect1><title>Foreign Variables</> @@ -561,6 +568,7 @@ macros <function>extern-alien</>, <function>define-alien-variable</> and separately specified by using a list of the form <programlisting>(alien-string lisp-symbol)</></para></listitem> </itemizedlist> +</para> <synopsis>(sb-alien:define-alien-variable name type)</> @@ -612,6 +620,8 @@ and may be either a string or a symbol. <type>type</> is an unevaluated alien type specifier. </para> +</sect2> + </sect1> <sect1><title>Foreign Data Structure Examples</> @@ -765,6 +775,7 @@ known-type calls are efficiently compiled. Limitations: <listitem><para>Structure type return values are not implemented.</></> <listitem><para>Passing of structures by value is not implemented.</></> </itemizedlist> +</para> <para> Here is an example which allocates a <type>(struct foo)</>, calls a foreign @@ -888,6 +899,7 @@ This can be described by the following call to The Lisp function <function>cfoo</> will have two arguments (<varname>str</> and <varname>a</>) and two return values (<varname>a</> and <varname>i</>). +</para> </sect2> @@ -926,6 +938,8 @@ whole-world granularity). </para></listitem> macro or <function>gc-off</function> call.</para></listitem> </orderedlist> +</para> + <!-- FIXME: This is a "changebar" section from the CMU CL manual. I (WHN 2002-07-14) am not very familiar with this content, so I'm not immediately prepared to try to update it for SBCL, and @@ -1067,6 +1081,8 @@ LaTeX \code{dotprod} is made. LaTeX --> +</sect2> + </sect1> <sect1><title>Step-By-Step Example of the Foreign Function Interface</> @@ -1099,7 +1115,7 @@ struct c_struct *c_function (i, s, r, a) printf("s = %s\n", s); printf("r->x = %d\n", r->x); printf("r->s = %s\n", r->s); - for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]); + for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]); r2 = (struct c_struct *) malloc (sizeof(struct c_struct)); r2->x = i + 5; r2->s = "a C string"; @@ -1176,6 +1192,7 @@ Within Lisp, compile the Lisp file. (This step can be done separately. You don't have to recompile every time.) <userinput>(compile-file "test.lisp")</> +</para> <para> Within Lisp, load the foreign object file to define the necessary @@ -1183,7 +1200,7 @@ symbols: <userinput>(load-foreign "test.o")</>. This must be done before loading any code that refers to these symbols. -<para> +</para> <para> Now you can load the compiled Lisp ("fasl") file into Lisp: diff --git a/doc/intro.sgml b/doc/intro.sgml index 8cb110d..0c4c1ee 100644 --- a/doc/intro.sgml +++ b/doc/intro.sgml @@ -43,7 +43,6 @@ but need to learn about Lisp, three books stand out. you'll see in most OO systems, and there are a number of lesser differences as well. This book tends to help with the culture shock. </para></listitem> - <listitem><para></para></listitem> </itemizedlist> </para> @@ -82,7 +81,7 @@ other &SBCL;-specific information is available: at their command prompts. The extensions for functions which don't have their own command prompt (like <function>trace</> does) are described in their documentation strings, - unless your &SBCL was compiled with an option not + unless your &SBCL; was compiled with an option not to include documentation strings, in which case the doc strings are only readable in the source code.</para></listitem> <listitem><para>Some low-level information describing the diff --git a/doc/user-manual.sgml b/doc/user-manual.sgml index 1afac1c..c4eb954 100644 --- a/doc/user-manual.sgml +++ b/doc/user-manual.sgml @@ -16,9 +16,6 @@ <!ENTITY CommonLisp "Common Lisp"> <!ENTITY Lisp "Lisp"> - <!-- common expressions I haven't figured out how to express --> - <!ENTITY mdash "-"> - <!-- document components --> <!ENTITY ch-intro SYSTEM "intro.sgml"> <!ENTITY ch-compiler SYSTEM "compiler.sgml"> diff --git a/version.lisp-expr b/version.lisp-expr index ccda712..7aef09a 100644 --- a/version.lisp-expr +++ b/version.lisp-expr @@ -17,4 +17,4 @@ ;;; checkins which aren't released. (And occasionally for internal ;;; versions, especially for internal versions off the main CVS ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".) -"0.8.5.24" +"0.8.5.25" -- 1.7.10.4