From: William H. N. <wn...@us...> - 2002-07-29 20:21:32
|
Update of /cvsroot/sbcl/sbcl/doc In directory usw-pr-cvs1:/tmp/cvs-serv17522/doc Modified Files: beyond-ansi.sgml ffi.sgml sbcl.1 Log Message: 0.7.6.9: documentation tweaks Index: beyond-ansi.sgml =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/beyond-ansi.sgml,v retrieving revision 1.5 retrieving revision 1.6 diff -u -d -r1.5 -r1.6 --- beyond-ansi.sgml 15 Jan 2002 19:00:56 -0000 1.5 +++ beyond-ansi.sgml 29 Jul 2002 20:21:25 -0000 1.6 @@ -1,25 +1,31 @@ -<chapter id="beyond-ansi"><title>Beyond the &ANSI; Standard</> +<chapter id="beyond-ansi"><title>Beyond The &ANSI; Standard</> -<para>Besides &ANSI;, we have other stuff..</para> +<para>&SBCL; is mostly an implementation of the &ANSI; standard for +Common Lisp. However, there's some important behavior which extends +or clarifies the standard, and various behavior which outright +violates the standard. +</para> -<sect1 id="non-conformance"><title>Non-Conformance with the &ANSI; Standard</> +<sect1 id="non-conformance"><title>Non-Conformance With The &ANSI; Standard</> <para> -This section is essentially a placeholder. There is are -important areas of non-conformance, like the difference -between <function>sb-pcl:find-class</> and <function>cl:class</>, -but progress is made -and the list changes and I've tired of trying to keep -the information here up to date. For information on the -highlights, try the bugs sections of the Unix man page. -For more detailed information, try the BUGS file in the -system distribution. +Essentially every type of non-conformance is considered a bug. +(The exceptions involve internal inconsistencies in the standard.) +In &SBCL; 0.7.6, the master record of known bugs is in +the <filename>BUGS</> file in the distribution. +Some highlight information about bugs may also be found in the +manual page. The recommended way to report bugs is through the sbcl-help or +sbcl-devel mailings lists. </para> </sect1> <sect1 id="idiosyncrasies"><title>Idiosyncrasies</> +<para>The information in this section describes some of the ways +that &SBCL; deals with choices that the &ANSI; standard +leaves to the implementation.</para> + <para>Declarations are generally treated as assertions. This general principle, and its implications, and the bugs which still keep the compiler from quite satisfying this principle, are discussed in the @@ -33,8 +39,58 @@ <function>funcall</> on the resulting function object. This is explicitly allowed by the &ANSI; standard, but leads to some oddities, e.g. collapsing <function>functionp</> and -<function>compiled-function-p</> into the same predicate. -</para> +<function>compiled-function-p</> into the same predicate.</para> + +<para>&SBCL; is quite strict about ANSI's definition of +<function>defconstant</>. ANSI says that doing <function>defconstant</> +of the same symbol more than once is undefined unless the new value +is <function>eql</> to the old value. Conforming to this specification +is a nuisance when the "constant" value is only constant under some +weaker test like <function>string=</> or <function>equal</>. It's +especially annoying because <function>defconstant</> takes effect +not only at load time but also at compile time, so that just +compiling and loading reasonable code like +<programlisting>(defconstant +foobyte+ '(1 4))</> +runs into this undefined behavior. Many +implementations of Common Lisp try to help the programmer around +this annoyance by silently accepting the undefined code and +trying to do what the programmer probably meant. &SBCL; instead +treats the undefined behavior as an error. Often +such code can be rewritten +in portable &ANSI; Common Lisp which has the desired behavior. +E.g., the code above can be given an exactly defined meaning by replacing +<function>defconstant</> either with <function>defparameter</> or +with a customized macro which does the right thing, possibly along the +lines of the <function>defconstant-eqx</> macro used internally in the +implementation of SBCL itself.</para> + +<para>&SBCL; gives style warnings about various kinds of perfectly +legal code, e.g. +<itemizedlist> + <listitem><para><function>defmethod</> without + <function>defgeneric</></para></listitem> + <listitem><para>multiple <function>defun</>s of the same + symbol</para></listitem> + <listitem><para>special variables not named in the conventional + <varname>*foo*</> style, and lexical variables unconventionally named + in the <varname>*foo*</> style</para></listitem> +</itemizedlist> +This causes friction with people +who point out that other ways of organizing code (especially +avoiding the use of <function>defgeneric</>) +are just as aesthetically stylish. +However, these warnings should be read not +as "warning, bad aesthetics detected, you have no style" but +"warning, this style keeps the compiler from understanding +the code as well as you might like." That is, +unless the compiler warns about such conditions, there's no +way for the compiler to warn +about some programming errors which would otherwise be +easy to overlook. (related bug: The warning about +multiple <function>defun</>s is pointlessly annoying when you compile +and then load a function containing <function>defun</> wrapped +in <function>eval-when</>, and ideally should be suppressed in +that case, but still isn't as of &SBCL; 0.7.6.)</para> </sect1> @@ -44,7 +100,7 @@ to the &ANSI; standard. &SBCL; doesn't support as many extensions as &CMUCL;, but it still has quite a few.</para> -<sect2><title>Things Which Might Be in the Next &ANSI; Standard</> +<sect2><title>Things Which Might Be In The Next &ANSI; Standard</> <para>&SBCL; provides extensive support for calling external C code, described @@ -62,7 +118,7 @@ </sect2> -<sect2><title>Support for Unix</> +<sect2><title>Support For Unix</> <para>The UNIX command line can be read from the variable <varname>sb-ext:*posix-argv*</>. The UNIX environment can be queried with the @@ -75,7 +131,7 @@ </sect2> -<sect2><title>Tools to Help Developers</title> +<sect2><title>Tools To Help Developers</title> <para>&SBCL; provides a profiler and other extensions to the &ANSI; <function>trace</> facility. See the online function documentation for @@ -97,7 +153,7 @@ </sect2> -<sect2><title>Interface to Low-Level &SBCL; Implementation</title> +<sect2><title>Interface To Low-Level &SBCL; Implementation</title> <para>&SBCL; has the ability to save its state as a file for later execution. This functionality is important for its bootstrapping @@ -120,7 +176,7 @@ slightly broken due to a stupid decision to remove some support for infinities (because it wasn't in the &ANSI; spec and it didn't occur to me that it was in the &IEEE; spec). If you need this stuff, take a look -at the ecode and bring it up on the developers' mailing +at the code and bring it up on the developers' mailing list.</para></note> </sect2> @@ -129,16 +185,20 @@ <para>The <function>sb-ext:purify</function> function causes &SBCL; first to collect all garbage, then to mark all uncollected objects as -permanent, never again attempting to collect them as garbage. (This -can cause a large increase in efficiency when using a primitive -garbage collector, but is less important with modern generational -garbage collectors.)</para> +permanent, never again attempting to collect them as garbage. This can +cause a large increase in efficiency when using a primitive garbage +collector, or a more moderate increase in efficiency when using a more +sophisticated garbage collector which is well suited to the program's +memory usage pattern. It also allows permanent code to be frozen at +fixed addresses, a precondition for using copy-on-write to share code +between multiple Lisp processes. is less important with modern +generational garbage collectors. </para> <para>The <function>sb-ext:truly-the</> operator does what the <function>cl:the</> operator does in a more conventional implementation of &CommonLisp;, declaring the type of its argument -without any runtime checks. (Ordinarily in &SBCL;, any type declaration -is treated as an assertion and checked at runtime.)</para> +without any runtime checks. (Ordinarily in &SBCL;, any type +declaration is treated as an assertion and checked at runtime.)</para> <para>The <function>sb-ext:freeze-type</> declaration declares that a type will never change, which can make type testing @@ -146,9 +206,10 @@ <para>The <function>sb-ext:constant-function</> declaration specifies that a function will always return the same value for the same -arguments. This is appropriate for functions like <function>sqrt</>. -It is not appropriate for functions like <function>aref</>, which can -change their return values when the underlying data are +arguments, which may allow the compiler to optimize calls +to it. This is appropriate for functions like <function>sqrt</>, but +is <emphasis>not</> appropriate for functions like <function>aref</>, +which can change their return values when the underlying data are changed.</para> </sect2> Index: ffi.sgml =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/ffi.sgml,v retrieving revision 1.5 retrieving revision 1.6 diff -u -d -r1.5 -r1.6 --- ffi.sgml 15 Jul 2002 20:52:47 -0000 1.5 +++ ffi.sgml 29 Jul 2002 20:21:25 -0000 1.6 @@ -11,7 +11,7 @@ refers to direct manipulation of C data structures as well as functions. The traditional &CMUCL; terminology is Alien Interface, and while that older terminology is no longer used much in the system -documentation, it still reflected in internal names in the +documentation, it still reflected in names in the implementation, notably in the name of the <literal>SB-ALIEN</> package.</para></note> @@ -20,10 +20,10 @@ <para> Because of Lisp's emphasis on dynamic memory allocation and garbage -collection, Lisp implementations use unconventional memory representations -for objects. This representation mismatch creates problems when a Lisp -program must share objects with programs written in another language. There -are three different approaches to establishing communication: +collection, Lisp implementations use non-C-like memory representations +for objects. This representation mismatch creates friction when a Lisp +program must share objects with programs which expect C data. There +are three common approaches to establishing communication: <itemizedlist> <listitem><para>The burden can be placed on the foreign program (and programmer) by requiring the knowledge and use of the @@ -44,8 +44,8 @@ <para>&SBCL;, like &CMUCL; before it, relies primarily on the automatic conversion and direct manipulation -approaches. Aliens of simple scalar types are automatically converted, -complex types are directly manipulated in their foreign +approaches. Foreign values of simple scalar types are automatically +converted, complex types are directly manipulated in their foreign representation. Furthermore, Lisp strings are represented internally with null termination bytes so that they can be passed directly to C interfaces without allocating new zero-terminated copies.</para> @@ -58,10 +58,7 @@ <type>alien-value</> object.</para> <para>The type language and operations on foreign types are -intentionally similar to those of the C language. And as discussed -above, they are applicable not only to communication with native C -programs, but also to programs in other languages which provide -C-level interfaces. </para> +intentionally similar to those of the C language.</para> </sect1> @@ -70,14 +67,12 @@ <para>Alien types have a description language based on nested list structure. For example the C type -<programlisting> -struct foo { +<programlisting>struct foo { int a; struct foo *b[100]; };</programlisting> has the corresponding &SBCL; FFI type -<programlisting> -(struct foo +<programlisting>(struct foo (a int) (b (array (* (struct foo)) 100)))</programlisting> </para> @@ -103,7 +98,7 @@ <para> The foreign types form a subsystem of the &SBCL; type system. An <type>alien</> type specifier provides a way to use any foreign type as a -Lisp type specifier. For example +Lisp type specifier. For example, <programlisting>(typep foo '(alien (* int)))</programlisting> can be used to determine whether <varname>foo</> is a pointer to a foreign <type>int</>. <type>alien</> type specifiers can be used in the same ways @@ -279,7 +274,7 @@ describes a pointer which is represented in Lisp as a <type>system-area-pointer</> object. &SBCL; exports this type from <literal>sb-alien</> because &CMUCL; did, but tentatively (as of - the first draft of this section of the manual, 2002-07-04) it is + the first draft of this section of the manual, &SBCL; 0.7.6) it is deprecated, since it doesn't seem to be required by user code. </para> </listitem> @@ -397,7 +392,7 @@ <para>The <function>sb-alien:sap-alien</> function converts <varname>sap</> (a system area pointer) to a foreign value with the specified <varname>type</>. <varname>type</> is not evaluated. -As of 2002-07-04, it looks as though this and other SAP functionality +As of &SBCL; 0.7.6, it looks as though this and other SAP functionality may become deprecated, since it shouldn't be needed by user code. </para> @@ -408,7 +403,7 @@ <para>The <function>sb-alien:alien-sap</> function returns the SAP which points to <varname>alien-value</>'s data. -As of 2002-07-04, it looks as though this and other SAP functionality +As of &SBCL; 0.7.6, it looks as though this and other SAP functionality may become deprecated, since it shouldn't be needed by user code. </para> @@ -567,7 +562,7 @@ <para> Since in modern C libraries, the <varname>errno</> "variable" is typically -no longer a variable, but some some bizarre artificial construct +no longer a variable, but some bizarre artificial construct which behaves superficially like a variable within a given thread, it can no longer reliably be accessed through the ordinary <varname>define-alien-variable</> mechanism. Instead, &SBCL; provides @@ -579,7 +574,7 @@ <para> The <function>extern-alien</> macro returns an alien with the specified <type>type</> which -points to an externally defined value. <varname>name</> is not evaluated, +points to an externally defined value. <varname>name</> is not evaluated, and may be either a string or a symbol. <type>type</> is an unevaluated alien type specifier. </para> @@ -675,7 +670,7 @@ libraries, creating an absolute Unix object file which is then processed by <function>load-1-foreign</>.</para> -<para> Note that as of &SBCL; 0.7.5, all foreign code (code loaded +<note><para>As of &SBCL; 0.7.5, all foreign code (code loaded with <function>load-1-function</> or <function>load-function</>) is lost when a Lisp core is saved with <function>sb-ext:save-lisp-and-die</>, and no attempt is made to @@ -683,8 +678,9 @@ annoyance both for &SBCL; users and for &CMUCL; users. It's hard to solve this problem completely cleanly, but some generally-reliable partial solution might be useful. Once someone in -either camp gets sufficiently annoyed to create it, some mechanism for -automatically restoring foreign code is likely to be added.</para> +either camp gets sufficiently annoyed to create it, &SBCL; is +likely to adopt some mechanism for automatically restoring foreign +code when a saved core is loaded.</para></note> </sect1> Index: sbcl.1 =================================================================== RCS file: /cvsroot/sbcl/sbcl/doc/sbcl.1,v retrieving revision 1.20 retrieving revision 1.21 diff -u -d -r1.20 -r1.21 --- sbcl.1 22 Jul 2002 20:22:41 -0000 1.20 +++ sbcl.1 29 Jul 2002 20:21:25 -0000 1.21 @@ -489,8 +489,9 @@ sbcl-devel. You can find the complete mailing list addresses on the web pages, <http://sbcl.sourceforge.net/>. (You may also find fancy SourceForge bug-tracking machinery there, but don't be fooled. As of -2002-07-25 anyway, we don't actively monitor that machinery and just -haven't been able to figure out how to turn it off.) +2002-07-25 anyway, we don't actively monitor that machinery, and it +exists only because we haven't been able to figure out how to turn +it off.) As with any software bug report, it's most helpful if you can provide enough information to reproduce the symptoms reliably, and if you say |