From 93d3feeaebd8c98896e602b79fee1343811ab193 Mon Sep 17 00:00:00 2001 From: "R. Matthew Emerson" Date: Tue, 18 Nov 2014 18:55:45 +0000 Subject: [PATCH] CCL documentation is now kept with CCL. --- ccl-documentation/about.ccldoc | 83 - ccl-documentation/build.ccldoc | 303 -- ccl-documentation/ccl-documentation.ccldoc | 57 - ccl-documentation/debugging.ccldoc | 745 ---- ccl-documentation/external-process.ccldoc | 181 - ccl-documentation/ffi.ccldoc | 2552 ------------- ccl-documentation/fs.ccldoc | 138 - ccl-documentation/gc.ccldoc | 332 -- ccl-documentation/glossary.ccldoc | 124 - ccl-documentation/hemlock.ccldoc | 3955 -------------------- ccl-documentation/ide.ccldoc | 369 -- ccl-documentation/implementation.ccldoc | 1386 ------- ccl-documentation/install.ccldoc | 169 - ccl-documentation/limits.ccldoc | 19 - ccl-documentation/modifying.ccldoc | 356 -- ccl-documentation/mop.ccldoc | 139 - ccl-documentation/objc-bridge.ccldoc | 847 ----- ccl-documentation/os.ccldoc | 44 - ccl-documentation/platform-notes.ccldoc | 497 --- ccl-documentation/profile.ccldoc | 280 -- ccl-documentation/q-and-a.ccldoc | 65 - ccl-documentation/sockets.ccldoc | 450 --- ccl-documentation/streams.ccldoc | 540 --- ccl-documentation/threads.ccldoc | 1566 -------- ccl-documentation/unicode.ccldoc | 362 -- ccl-documentation/using.ccldoc | 866 ----- ccl-documentation/ccl.css => ccl.css | 0 ccl-documentation/defun.tex => defun.tex | 0 source/ccldoc.asd | 1 + source/output-html.lisp | 3 +- source/output-latex.lisp | 9 +- 31 files changed, 9 insertions(+), 16429 deletions(-) delete mode 100644 ccl-documentation/about.ccldoc delete mode 100644 ccl-documentation/build.ccldoc delete mode 100644 ccl-documentation/ccl-documentation.ccldoc delete mode 100644 ccl-documentation/debugging.ccldoc delete mode 100644 ccl-documentation/external-process.ccldoc delete mode 100644 ccl-documentation/ffi.ccldoc delete mode 100644 ccl-documentation/fs.ccldoc delete mode 100644 ccl-documentation/gc.ccldoc delete mode 100644 ccl-documentation/glossary.ccldoc delete mode 100644 ccl-documentation/hemlock.ccldoc delete mode 100644 ccl-documentation/ide.ccldoc delete mode 100644 ccl-documentation/implementation.ccldoc delete mode 100644 ccl-documentation/install.ccldoc delete mode 100644 ccl-documentation/limits.ccldoc delete mode 100644 ccl-documentation/modifying.ccldoc delete mode 100644 ccl-documentation/mop.ccldoc delete mode 100644 ccl-documentation/objc-bridge.ccldoc delete mode 100644 ccl-documentation/os.ccldoc delete mode 100644 ccl-documentation/platform-notes.ccldoc delete mode 100644 ccl-documentation/profile.ccldoc delete mode 100644 ccl-documentation/q-and-a.ccldoc delete mode 100644 ccl-documentation/sockets.ccldoc delete mode 100644 ccl-documentation/streams.ccldoc delete mode 100644 ccl-documentation/threads.ccldoc delete mode 100644 ccl-documentation/unicode.ccldoc delete mode 100644 ccl-documentation/using.ccldoc rename ccl-documentation/ccl.css => ccl.css (100%) rename ccl-documentation/defun.tex => defun.tex (100%) diff --git a/ccl-documentation/about.ccldoc b/ccl-documentation/about.ccldoc deleted file mode 100644 index 6caa9cc..0000000 --- a/ccl-documentation/about.ccldoc +++ /dev/null @@ -1,83 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "About {CCL}" - (defsection "Introduction to {CCL}" - "{CCL} is a fast, mature, open source Common Lisp - implementation that runs on Linux, Mac OS X, FreeBSD, and Windows. - {CCL} was forked from Macintosh Common Lisp (MCL) in 1998 - and the development has been entirely separate since. - - - When it was forked from MCL in 1998, the new Lisp was named - OpenMCL. Subsequently, Clozure renamed its Lisp to {CCL}, partly - because its ancestor MCL has been released as open - source. Clozure thought it might be confusing for users if there - were two independent open-source projects with such similar - names. The new name also reflects {CCL}'s current status as the - flagship product of Clozure Associates. - - Furthermore, the new name refers to {CCL}'s ancestry: in its - early years, MCL was known as Coral Common Lisp, or “CCL”. For - years the package that contains most of {CCL}'s - implementation-specific symbols has been named “CCL”, an acronym - that once stood for the name of the Lisp product. It seems - fitting that “CCL” once again stands for the name of the - product. - - Some commands and source files may still refer to “OpenMCL” - instead of {CCL}. - - {CCL} compiles to native code and supports multithreading - using native OS threads. It includes a foreign-function interface, - and supports both Lisp code that calls external code, and external - code that calls Lisp code. {CCL} can create standalone executables - on all supported platforms. - - On Mac OS X, {CCL} supports building GUI applications that - use OS X's native Cocoa frameworks, and the OS X distributions - include an IDE written with Cocoa, and distributed with complete - sources. - - On all supported platforms, {CCL} can run as a command-line - process, or as an inferior Emacs process using either SLIME or - ILISP. - -Features of {CCL} include" - (listing :bullet - (item "Very fast compilation speed.") - (item "A fast, precise, compacting, generational - garbage collector written in hand-optimized C. The sizes of the - generations are fully configurable. Typically, a generation can - be collected in a millisecond on modern - systems.") - (item "Fast execution speed, competitive with other - Common Lisp implementations on most - benchmarks.") - (item "Robust and stable. Customers report that their - CPU-intensive, multi-threaded applications run for extended - periods on {CCL} without difficulty.") - (item "Full native OS threads on all platforms. Threads - are automatically distributed across multiple cores. The API - includes support for shared memory, locking, and blocking for OS - operations such as I/O.") - (item "Full Unicode support.") - (item "Full SLIME integration.") - (item "An IDE on Mac OS X, fully integrated with - the Macintosh window system and User Interface - standards.") - (item "Excellent debugging facilities. The names of all - local variables are available in a backtrace.") - (item "A complete, mature foreign function interface, - including a powerful bridge to Objective-C and Cocoa on Mac OS - X.") - (item "Many extensions including: files mapped to - Common Lisp vectors for fast file I/O; thread-local hash tables - and streams to eliminate locking overhead; cons hashing support; - and much more") - (item "Very efficient use of memory")) - (para "Although it's an open-source project, available free of - charge under a liberal license, {CCL} is also a fully-supported - product of Clozure Associates. Clozure continues to extend, - improve, and develop {CCL} in response to customer and user - needs, and offers full support and development services for - {CCL}."))) diff --git a/ccl-documentation/build.ccldoc b/ccl-documentation/build.ccldoc deleted file mode 100644 index 80f81a0..0000000 --- a/ccl-documentation/build.ccldoc +++ /dev/null @@ -1,303 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Building {CCL} from its Source Code" - (defsection "Building Definitions" - (para "The following terms are used in subsequent sections; it - may be helpful to refer to these definitions.") - (para "A {term fasl file} is the file produced - by {code compile-file}. These files store the - machine code associated with function definitions and the - external representation of other lisp objects in a compact, - machine-readable form. Short for - “{code FAS}t {code L}oading”. {CCL} uses different pathname - types (extensions) to name fasl files on different platforms; see " - (ref (table "Platform-specific filename conventions")) " for the details.") - (para "The {term lisp kernel} is a C program with a fair amount of - platform-specific assembly language code. The lisp kernel - provides runtime support for lisp code, such as garbage collection, - memory allocation, exception handling, and so forth. - When the lisp kernel starts, it maps the heap image into memory and - transfers control to compiled lisp code that the image contains.") - (para "A {term heap image} is a file that can be quickly mapped into a - process's address space. Conceptually, it's not too different - from an executable file or shared library in the OS's native - format (ELF or Mach-O/dyld format); for historical reasons, - {CCL}'s own heap images are in their own (fairly simple) - format. A full heap image contains all of the code and data that - comprise {CCL}. The default image file name - is the name of the lisp kernel with a {code .image} suffix. See " - (ref (table "Platform-specific filename conventions")) ".") - (para "A bootstrapping image (see {section Create a Bootstrapping Image}) - is a minimal - heap image used in the process of building {CCL} itself. The - bootstrapping image contains just enough code to load the rest - of {CCL} from fasl files. The function {function rebuild-ccl} - automatically creates a bootstrepping image as part of its work.") - (para "Each supported platform (and possibly a few - as-yet-unsupported ones) has a uniquely named subdirectory of - {code ccl/lisp-kernel/}; each such - kernel build directory - contains a Makefile and may contain some auxiliary files (linker - scripts, etc.) that are used to build the lisp kernel on a - particular platform. The platform-specific name of the kernel - build directory is described in " - (ref (table "Platform-specific filename conventions")) ".") - - (table "Platform-specific filename conventions" - (row - (item "Platform") - (item "kernel") - (item "fasl extension") - (item "kernel build directory")) - (row - (item "Linux (ppc)") - (item "ppccl") - (item ".pfsl") - (item "linuxppc")) - (row - (item "Linux (ppc64)") - (item "ppccl64") - (item ".p64fsl") - (item "linuxppc64")) - (row - (item "Linux (x8664)") - (item "lx86cl64") - (item ".lx64fsl") - (item "linuxx8664")) - (row - (item "Linux (x8632)") - (item "lx86cl") - (item ".lx32fsl") - (item "linuxx8632")) - (row - (item "Linux (arm32)") - (item "armcl") - (item ".lafsl") - (item "linuxarm")) - (row - (item "OS X (x8664)") - (item "dx86cl64") - (item ".dx64fsl") - (item "darwinx8664")) - (row - (item "OS X (x8632)") - (item "dx86cl") - (item ".dx32fsl") - (item "darwinx8632")) - (row - (item "FreeBSD (x8664)") - (item "fx86cl64") - (item ".fx64fsl") - (item "freebsdx8664")) - (row - (item "FreeBSD (x8632)") - (item "fx86cl") - (item ".fx32fsl") - (item "freebsdx8632")) - (row - (item "Solaris (x8664)") - (item "sx86cl64") - (item ".sx64fsl") - (item "solarisx64")) - (row - (item "Solaris (x8632)") - (item "sx86cl") - (item ".sx32fsl") - (item "solarisx86")) - (row - (item "Windows (x8664)") - (item "wx86cl64.exe") - (item ".wx64fsl") - (item "win64")) - (row - (item "Windows (x8632)") - (item "wx86cl.exe") - (item ".wx32fsl") - (item "win32")))) - - (defsection "Reasons for Building" - "At a given time, there are generally two versions of {CCL} that - you might want to use (and therefore might want to build from - source). - - The first of these is the current release branch. Fixes for - serious bugs are sometimes checked into the release branch, and - you might want to update from Subversion and rebuild in order to - pick up these fixes. - - You may also be interested in building the development version of {CCL}, which is - often called the trunk. The trunk may contain both interesting new features and - interesting new bugs. See {link http://trac.clozure.com/ccl/wiki} for information - about how to check out a copy of the trunk.") - - (defsection "Kernel Build Prerequisites" - "In order to build the lisp kernel, you must have installed a C compiler and its -associated tools (such as {system as} and {system ld}). Additionally, the lisp kernel -build process uses {system m4}; this program is often not installed by default, so -make sure you have it. The lisp kernel makefiles generally assume that you are using -GNU make. - - On a recent Mac OS X system, typing {system xcode-select --install} should download -and install everything needed to build {CCL}.") - - (defsection "Building Everything" - "With all the pre-requisites in place, building {CCL} is very simple." - (code-block "$ ccl -n -? (ccl:rebuild-ccl :full t)") - - "This peforms the following steps:" - (listing :bullet - (item "Deletes all fasl files and other object files in the - {code ccl} directory tree") - - (item "Does {code (compile-ccl t)} in the running lisp, to - generate fasl files from the lisp sources.") - (item "Does {code (xload-level-0 :force)} in the - running lisp. This compiles the lisp files in the - {code ccl:level-0;} directory and then creates a special - bootstrapping image from the compiled fasl files.") - (item "Runs an external process that runs - {system make} in the current platform's kernel - build directory to create a new kernel. - This step can only work if the C compiler and related - tools are installed; see {section Kernel Build Prerequisites}.") - (item "Runs another external process, which causes the newly - compiled lisp kernel to load the new bootstrapping image. - The bootstrapping image then loads the rest of - the fasl files and a new copy of the platform's - full heap image is then saved.")) - - "When all goes well, this all happen without user intervention and - with some simple progress messages. If anything goes wrong - during execution of either of the external processes, the - process output is displayed as part of a lisp error message. - - {code rebuild-ccl} is essentially just a short cut for running - all the individual steps involved in rebuilding the system. You - can also execute these steps individually, as described below.") - - (defsection "Building the Kernel" - "Rebuilding the lisp kernel is straightfoward. Consult the table " - (ref (table "Platform-specific filename conventions")) " to determine - the name of the lisp kernel build directory you want. Then, change to - that directory and say {system make}. Suppose you wanted to build the - lisp kernel for 64-bit FreeBSD/x86. We find that the name of the lisp - kernel build directory is {system freebsdx8664}, so we do the following: " - - (code-block "$ cd ccl/lisp-kernel/freebsdx8664 -$ make clean -$ make") - - "The most common reason that the build fails is because m4 is not installed. If you -see {system m4: command not found}, then you should install m4. - -On Mac OS X, make sure that you have installed the command-line developer tools -with {system xcode-select --install}. If you get an error message saying that -the file {system sys/signal.h} cannot be found, this is a sign that you need to do this. -You need to do this even if you have Xcode already installed.") - - (defsection "Building the Heap Image" - "Typically, {function rebuild-ccl} is used to rebuild all of {CCL}. - In special cases, you might want to exercise more control over how - the heap image is built. These cases typically arise only when - developing {CCL} itself. - - Creating a new {CCL} heap image consists of the following steps:" - (listing :number - (item "Using an existing lisp, recompile the updated lisp source code") - (item "Using an existing lisp, create a new bootstrapping image") - (item "Start up the lisp kernel and tell it to load the bootstrapping image - you just created")) - - (defsection "Compile Lisp Source Code" - (para " Calling:") - (code-block "? (ccl:compile-ccl)") - "at the lisp prompt compiles any fasl files that are - out-of-date with respect to the corresponding lisp sources; - {code (ccl:compile-ccl t)} forces recompilation. {code - ccl:compile-ccl} reloads newly-compiled versions of some - files; {code ccl:xcompile-ccl} is analogous, but skips this - reloading step. - - Unless there are bootstrapping considerations involved, it - usually doesn't matter whether these files are reloaded after - they're recompiled. - - Calling {code compile-ccl} or - {code xcompile-ccl} in an environment where fasl - files don't yet exist may produce warnings to that effect - whenever files are {code require}d during - compilation; those warnings can be safely ignored. Depending - on the maturity of the {CCL} release, calling - {code compile-ccl} or - {code xcompile-ccl} may also produce several - warnings about undefined functions, etc. They should be - cleaned up at some point.") - - (defsection "Create a Bootstrapping Image" - "The bootstrapping image isn't provided in {CCL} - distributions. It can be built from the source code provided - in distributions (using a lisp image and kernel provided in - those distributions) using the procedure described - below. - - The bootstrapping image is built by invoking a special utility - inside a running {CCL} heap image to load files contained in - the {code ccl/level-0} directory. The bootstrapping image - loads several dozen fasl files. After it's done so, it saves - a heap image via {code save-application}. This process is - called cross-dumping. - - Given a source distribution, a lisp kernel, and a heap image, - one can produce a bootstrapping image by first invoking {CCL} - from the shell:" - - (code-block "$ ccl -? (ccl:xload-level-0)") - - "This function compiles the lisp sources in the {code - ccl/level-0} directory as needed, and then loads the resulting - fasl files into a simulated lisp heap contained in data - structures inside the running lisp. It then writes this - data to disk as a bootstrapping image and displays the - pathname of the newly-written image on the terminal. - - {code xload-level-0} should be called whenever your existing - boot image is out-of-date with respect to the source files in - {code ccl:level-0;}.") - - (defsection "Building a full image from a bootstrapping image" - "To build a full image from a bootstrapping image, just invoke - the kernel and tell it to load the bootstrapping image (as - reported by {function xload-level-0}. For example, suppose you - are using 64-bit Mac OS X:" - - (code-block "$ cd ccl # wherever your ccl directory is -$ ./dx86cl64 --image-name x86-boot64.image --no-init") - - "Other platoforms use analogous steps: use the appropriate - platform-specific name for the lisp kernel, and use the name of - boot image as reported by {function xload-level-0}. - - This process will load a few dozen fasl files, printing a - message as each file is loaded. If all of these files - successfully load, the lisp will print a prompt. You should be - able to do essentially everything in that environment that you - can in the environment provided by a full heap image. If - everything went well, you can save that image using {function - save-application}:" - (code-block "? (ccl:save-application \"new.image\")") - "The name {sample new.image} can be whatever you want. You may - wish to use the default image name for your platform; see " - (ref (table "Platform-specific filename conventions")) "." - - (para "If things go wrong in the early stages of the loading - sequence, errors are often difficult to debug; until a fair - amount of code (CLOS, the CL condition system, streams, the - reader, the read-eval-print loop) is loaded, it's generally - not possible for the lisp to report an error. Errors that - occur during these early stages (“the cold load”) sometimes - cause the lisp kernel debugger to be invoked; it's - primitive, but can sometimes help one to get oriented."))) - -) ;chapter diff --git a/ccl-documentation/ccl-documentation.ccldoc b/ccl-documentation/ccl-documentation.ccldoc deleted file mode 100644 index 416d1e4..0000000 --- a/ccl-documentation/ccl-documentation.ccldoc +++ /dev/null @@ -1,57 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(ccldoc:def-expander CCL () "Clozure CL") - -(defun generate-ccl-symbols () - (let ((forms nil) - (rows nil)) - (do-external-symbols (sym :ccl) - (cond ((fboundp sym) - (push `(:function ,sym) forms)) - ((boundp sym) - (push `(:variable ,sym) forms)))) - (setq forms (sort forms 'string-greaterp :key 'second)) - (setq forms (stable-sort forms 'string-greaterp :key 'first)) - (loop - (let ((a (first forms)) - (b (second forms))) - (setq forms (nthcdr 2 forms)) - (when (null a) - (return)) - (push `(:row (:item ,a) (:item ,b)) rows))) - `(:table "Exported Symbols" ,@rows))) - -(document "{CCL} Documentation" - (include-file "about.ccldoc" :in-package :ccl) - (include-file "install.ccldoc" :in-package :ccl) - (include-file "build.ccldoc" :in-package :ccl) - (include-file "using.ccldoc" :in-package :ccl) - (include-file "debugging.ccldoc" :in-package :ccl) - (include-file "unicode.ccldoc" :in-package :ccl) - (include-file "fs.ccldoc" :in-package :ccl) - (include-file "os.ccldoc" :in-package :ccl) - (include-file "sockets.ccldoc" :in-package :ccl) - (include-file "threads.ccldoc" :in-package :ccl) - (include-file "ffi.ccldoc" :in-package :ccl) - (include-file "external-process.ccldoc" :in-package :ccl) - (include-file "streams.ccldoc" :in-package :ccl) - (include-file "platform-notes.ccldoc" :in-package :ccl) - (include-file "gc.ccldoc" :in-package :ccl) - - (include-file "limits.ccldoc" :in-package :ccl) - (include-file "implementation.ccldoc" :in-package :ccl) - (include-file "modifying.ccldoc" :in-package :ccl) - - (include-file "profile.ccldoc" :in-package :ccl) - - (include-file "mop.ccldoc" :in-package :ccl) - - (include-file "objc-bridge.ccldoc" :in-package :ccl) - (include-file "ide.ccldoc" :in-package :ccl) - (include-file "hemlock.ccldoc" :in-package :ccl) - - (include-file "q-and-a.ccldoc" :in-package :ccl) - (include-file "glossary.ccldoc" :in-package :ccl) - (index-section "Symbol Index") - (defsection "CCL Exported Symbols" - #.(generate-ccl-symbols))) diff --git a/ccl-documentation/debugging.ccldoc b/ccl-documentation/debugging.ccldoc deleted file mode 100644 index 333822b..0000000 --- a/ccl-documentation/debugging.ccldoc +++ /dev/null @@ -1,745 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Debugging" - (defsection "Trace" - (para "{CCL}'s tracing facility is invoked by an extended version - of the Common Lisp {code trace} macro. Extensions allow tracing - of methods, as well as finer control over tracing actions.") - (definition (:macro trace) - "TRACE {lbrace} keyword global-value {rbrace}* {lbrace} spec | ( spec {lbrace} keyword local-value {rbrace}*){rbrace}*" - nil - (defsection "Description" - "The {code trace} macro encapsulates the functions named by - {sample spec}s, causing trace actions to take place on entry - and exit from each function. The default actions print a - message on function entry and exit. {sample Keyword}/{sample - value} options can be used to specify changes in the default - behavior. - - Invoking {code (trace)} without arguments returns a list of - functions being traced. - - A {sample spec} is either a symbol that is the name of a - function, or an expression of the form {code (setf {sample - symbol})}, or a specific method of a generic function in the - form {code (:method {sample gf-name} {lbrace}{sample - qualifier}{rbrace}* ({lbrace}{sample specializer}{rbrace}*))}, - where a {sample specializer} can be the name of a class or an - {code EQL} specializer. - - A {sample spec} can also be a string naming a package, or - equivalently a list {code (:package {sample package-name})}, - in order to request that all functions in the package to be - traced. - - By default, whenever a traced function is entered or exited, a - short message is printed on {variable *trace-output*} showing - the arguments on entry and values on exit. Options specified - as key/value pairs can be used to modify this behavior. - Options preceding the function {sample spec}s apply to all the - functions being traced. Options specified along with a - {sample spec} apply to that spec only and override any global - options. The following options are supported:" - - (listing :definition - (item "{code :methods {lbrace}T | nil{rbrace}}" ccldoc::=> - "If true, and if applied to a {sample spec} naming a generic - function, arranges to trace all the methods of the generic - function in addition to the generic function itself.") - (item "{code :inside {sample outside-spec} | ({lbrace}{sample outside-spec}{rbrace}*)}" ccldoc::=> - "Inhibits all trace actions unless the current - invocation of the function being traced is inside one - of the {sample outside-spec}'s, i.e. unless a function - named by one of the {sample outside-spec}'s is - currently on the stack. {sample outside-spec} can - name a function, a method, or a package, as above.") - (item (clause "{code :if {sample form}}, {code :condition {sample form}}") ccldoc::=> - " Evaluates {sample form} whenever the function being traced - is about to be entered, and inhibits all trace actions - if {sample form} returns nil. The form may reference - the lexical variable {code ccl::args}, which is a list - of the arguments in this call. {code :condition} is - just a synonym for {code :if}, though if both are - specified, both must return non-nil. - ") - (item "{code :before-if {sample form}}" ccldoc::=> - " Evaluates {sample form} whenever the function being traced - is about to be entered, and inhibits the entry trace - actions if {sample form} returns nil. The form may - reference the lexical variable {code ccl::args}, which - is a list of the arguments in this call. If both - {code :if} and {code :before-if} are specified, both - must return non-nil in order for the before entry - actions to happen.") - (item "{code :after-if {sample form}}" ccldoc::=> - " Evaluates {sample form} whenever the function being traced - has just exited, and inhibits the exit trace actions - if {sample form} returns nil. The form may reference - the lexical variable {code ccl::vals}, which is a list - of values returned by this call. If both {code :if} - and {code :after-if} are specified, both must return - non-nil in order for the after exit actions to happen.") - (item "{code :print-before {sample form}}" ccldoc::=> - " Evaluates {sample form} whenever the function being traced - is about to be entered, and prints the result before - printing the standard entry message. The form may - reference the lexical variable {code ccl::args}, which - is a list of the arguments in this call. To see - multiple forms, use {code values}: - {code :print-before (values (one-thing) (another-thing))}.") - (item "{code :print-after {sample form}}" ccldoc::=> - " Evaluates {sample form} whenever the function being - traced has just exited, and prints the result after - printing the standard exit message. The form may - reference the lexical variable {code ccl::vals}, which - is a list of values returned by this call. To see - multiple forms, use {code values}: - {code :print-after (values (one-thing) (another-thing))}.") - (item "{code :print {sample form}}" ccldoc::=> - "Equivalent to {code :print-before {sample - form} :print-after {sample form}}.") - (item "{code :eval-before {sample form}}" ccldoc::=> - "Evaluates {sample form} whenever the function being - traced is about to be entered. The form may reference - the lexical variable {code ccl::args}, which is a list - of the arguments in this call.") - (item "{code :eval-after {sample form}}" ccldoc::=> - "Evaluates {sample form} whenever the function being - has just exited. The form may reference the lexical - variable {code ccl::vals}, which is a list of values - returned by this call. - ") - (item "{code :eval {sample form}}" ccldoc::=> - "Equivalent to {code :eval-before {sample form} :eval-after {sample form}}.") - (item "{code :break-before {sample form}}" ccldoc::=> - "Evaluates {sample form} whenever the function being - traced is about to be entered, and if the result is - non-nil, enters a debugger break loop. The form may - reference the lexical variable {code ccl::args}, which - is a list of the arguments in this call.") - (item "{code :break-after {sample form}}" ccldoc::=> - "Evaluates {sample form} whenever the function being - traced has just exited, and if the result is non-nil, - enters a debugger break loop. The form may reference - the lexical variable {code ccl::vals}, which is a list - of values returned by this call.") - (item "{code :break {sample form}}" ccldoc::=> - "Equivalent to {code :break-before {sample - form} :break-after {sample form}}.") - (item (clause "{code :backtrace-before {sample form}}, {code :backtrace {sample form}}") ccldoc::=> - (para "Evaluates {sample form} whenever the function being - traced is about to be entered. The form may reference - the lexical variable {code ccl::args}, which is a list - of the arguments in this call. The value returned by - {sample form} is intepreted as follows:") - (listing :definition - (item "{code nil}" ccldoc::=> "does nothing") - (item "{code :detailed}" ccldoc::=> "prints a - detailed backtrace to {variable - *trace-output*}.") - (item "{code (:detailed {sample integer})}" - ccldoc::=> "prints the top {sample integer} - frames of detailed backtrace to {variable - *trace-output*}.") - (item "{sample integer}" ccldoc::=> "prints top - {sample integer} frames of a terse backtrace to - {variable *trace-output*}.") - (item "anything else" ccldoc::=> "prints a terse - backtrace to {variable *trace-output*}.")) - (para "Note that unlike with the other options, - {code :backtrace} is equivalent to - {code :backtrace-before} only, not both before and - after, since it's usually not helpful to print the - same backtrace both before and after the function - call.")) - (item "{code :backtrace-after {sample form}}" ccldoc::=> - (para "Evaluates {sample form} whenever the function being - traced has just exited. The form may reference the - lexical variable {code ccl::vals}, which is a list of - values returned by this call. The value returned by - {sample form} is intepreted as follows:") - (listing :definition - (item "{code nil}" ccldoc::=> "does nothing") - (item "{code :detailed}" ccldoc::=> "prints a detailed - backtrace to {variable *trace-output*}.") - (item "{code (:detailed {sample integer})}" - ccldoc::=> "prints the top {sample integer} - frames of detailed backtrace to {variable - *trace-output*}.") - (item "{sample integer}" ccldoc::=> "prints top {sample - integer} frames of a terse backtrace to - {variable *trace-output*}.") - (item "anything else" ccldoc::=> "prints a terse backtrace - to {variable *trace-output*}."))) - (item "{code :before}{sample action}" ccldoc::=> - (para - "specifies the action to be taken just before the traced - function is entered. {sample action} is one of:") - (listing :definition - (item "{code :print}" ccldoc::=> - "The default, prints a short indented message showing the - function name and the invocation arguments") - (item "{code :break}" ccldoc::=> "Equivalent to - {code :before :print :break-before t}") - (item "{code :backtrace}" ccldoc::=> "Equivalent to - {code :before :print :backtrace-before t}") - (item "{sample function}" ccldoc::=> " Any other value is - interpreted as a function to call on entry instead - of printing the standard entry message. It is - called with its first argument being the name of the - function being traced, the remaining arguments being - all the arguments to the function being traced, and - {variable *trace-level*} bound to the current - nesting level of trace actions. "))) - (item "{code :after}{sample action}" ccldoc::=> - (para "specifies the action to be taken just after the - traced function exits. {sample action} is one of:") - (listing :definition - (item "{code :print}" ccldoc::=> - "The default, prints a short indented message showing the - function name and the returned values ") - (item "{code :break}" ccldoc::=> "Equivalent to - {code :after :print :break-after t}") - (item "{code :backtrace}" ccldoc::=> "Equivalent to - {code :after :print :backtrace-after t}") - (item "{sample function}" ccldoc::=> "Any other value is - interpreted as a function to call on exit - instead of printing the standard exit message. - It is called with its first argument being the - name of the function being traced, the remaining - arguments being all the values returned by the - function being traced, and ccl:*trace-level* - bound to the current nesting level of trace - actions.")))))) - - (definition (:variable *trace-level*) "CCL:*TRACE-LEVEL*" nil - (defsection "Description" - (para "Variable bound to the current nesting level during - execution of before and after trace actions. The default - printing actions use it to determine the amount of - indentation."))) - - (definition (:variable *trace-max-indent*) "CCL:*TRACE-MAX-INDENT*" nil - (defsection "Description" - (para - "The default before and after print actions will not indent by - more than the value of {variable *trace-max-indent*} - regardless of the current trace level."))) - - (definition (:function trace-function) "CCL:TRACE-FUNCTION spec {code &key} {lbrace} keyword value {rbrace}*" nil - (defsection "Description" - (para "This is a functional version of the TRACE macro. - {sample spec} and {sample keyword}s are as for TRACE, except - that all arguments are evaluated. "))) - (definition (:variable *trace-print-level*) "CCL:*TRACE-PRINT-LEVEL*" nil - (defsection "Description" - (para "The default print actions bind {variable *print-level*} - to this value while printing. Note that this rebinding is only - in effect during the default entry and exit messages. It does - not apply to printing of {code :print-before/:print-after} forms - or any explicit printing done by user code."))) - (definition (:variable *trace-print-length*) "CCL:*TRACE-PRINT-LENGTH*" nil - (defsection "Description" - (para "The default print actions bind {variable *print-length*} - to this value while printing. Note that this rebinding is only - in effect during the default entry and exit messages. It does - not apply to printing of {code :print-before/:print-after} forms - or any explicit printing done by user code."))) - (definition (:variable *trace-bar-frequency*) "CCL:*TRACE-BAR-FREQUENCY*" nil - (defsection "Description" - (para "By default, this is nil. If non-nil it should be a - integer, and the default entry and exit messages will print a | - instead of space every this many levels of indentation.")))) - -(defsection "Advising" - " - The {code advise} macro can be thought of as a more - general version of {code trace}. It allows code that - you specify to run before, after, or around a given function, for - the purpose of changing the behavior of the function. Each piece - of added code is called a piece of advice. Each piece of advice - has a unique name, so that you can have multiple pieces of advice - on the same function, including multiple - {code :before}, {code :after}, and - {code :around} pieces of advice. - - - - The {code :name} and {code :when} - keywords serve to identify the piece of advice. A later call to - {code advise} with the same values of - {code :name} and {code :when} will replace - the existing piece of advice; a call with different values will not. - " - (definition (:macro advise) "advise spec form {code &key} when name" - (clause " - Add a piece of advice to the function or method specified by - {param spec} according to - {param form}. - ") - (defsection "Arguments and Values" - (listing :definition - (item "{param spec}" ccldoc::=> " - A specification of the function on which to put the - advice. This is either a symbol that is the name of a - function or generic function, or an expression of the - form (setf {sample symbol}), or a - specific method of a generic function in the form - (:method symbol {lbrace}qualifiers{rbrace} (specializer {lbrace}specializer{rbrace})). - ") - (item "{param form}" ccldoc::=> " - A form to execute before, after, or around the advised - function. The form can refer to the variable arglist - that is bound to the arguments with which the advised - function was called. You can exit from form with - (return). - ") - (item "{param name}" ccldoc::=> " - A name that identifies the piece of advice. - ") - (item "{param when}" ccldoc::=> " - An argument that specifies when the piece of advice is - run. There are three allowable values. The default is - {code :before}, which specifies that form is - executed before the advised function is called. Other - possible values are {code :after}, which - specifies that form is executed after the advised - function is called, and {code :around}, - which specifies that form is executed around the call to - the advised function. Use {code (:do-it)} - within form to indicate invocation of the original - definition. - "))) - (defsection "Examples" - (para " - The function {code foo}, already defined, does - something with a list of numbers. The following code uses a - piece of advice to make foo return zero if any of its - arguments is not a number. Using :around advice, you can do - the following: - " - (code-block " -(advise foo (if (some #'(lambda (n) (not (numberp n))) arglist) - 0 - (:do-it)) - :when :around :name :zero-if-not-nums) - ")) - (para " - To do the same thing using a :before piece of advice: - " - (code-block " -(advise foo (if (some #'(lambda (n) (not (numberp n))) arglist) - (return 0)) - :when :before :name :zero-if-not-nums) - ")))) - (definition (:macro unadvise) "unadvise spec {code &key} when name" - (clause " - Remove the piece or pieces of advice matching {param spec}, - {param when}, and {param name}. - ") - (defsection "Description" - (para " - The unadvise macro removes the piece or pieces of advice - matching {code spec}, {code when}, - and {code name}. When the value of - {code spec} is t and the values of {code when} - and {code name} are nil, unadvise - removes every piece of advice; when {code spec} is - t, the argument {code when} is nil, and - {code name} is non-nil, unadvise removes all - pieces of advice with the given name. - ")) - (defsection "Arguments and Values" - (para " - The arguments have the same meaning as in - " - (ref (definition :macro advise)) ". - "))) - (definition (:macro advisedp) "advisedp spec {code &key} when name" - (clause " - Return a list of the pieces of advice matching {param spec}, - {param when}, and {param name}. - ") - (defsection "Description" - (para " - The advisedp macro returns a list of existing pieces of advice - that match {code spec}, {code when}, - and {code name}. When the value of - {code spec} is t and the values of - {code when} and {code name} are nil, - advisedp returns all existing pieces of advice. - ")) - (defsection "Arguments and Values" - (para " - The arguments have the same meaning as in - " - (ref (definition :macro advise)) ". -")))) - -(defsection "Watched Objects" - (para " - As of release 1.4, Clozure CL provides a way for lisp objects to - be watched so that a condition will be signaled when a thread - attempts to write to the watched object. For a certain class of - bugs (someone is changing this value, but I don't know who), this - can be extremely helpful. - ") - (definition (:function watch) "watch {code &optional} object" " - Monitor a lisp object for writes. - " - (defsection "Arguments and Values" - (listing :definition - (item "{param object}" ccldoc::=> " - Any memory-allocated lisp object. - "))) - (defsection "Description" - "The WATCH function arranges for the specified object to be - monitored for writes. This is accomplished by copying the - object to its own set of virtual memory pages, which are then - write-protected. This protection is enforced by the computer's - memory-management hardware; the write-protection does not slow - down reads at all. - - - - When any write to the object is attempted, a - WRITE-TO-WATCHED-OBJECT condition will be signaled. - - - - When called with no arguments, WATCH returns a freshly-consed - list of the objects currently being watched. - - - - WATCH returns NIL if the object cannot be watched (typically - because the object is in a static or pure memory area). - ") - (defsection "DWIM" - (para " - WATCH operates at a fairly low level; it is not possible to - avoid the details of the internal representation of objects. - Nevertheless, as a convenience, WATCHing a standard-instance, - a hash-table, or a multi-dimensional or non-simple CL array - will watch the underlying slot-vector, hash-table-vector, or - data-vector, respectively. - ")) - (defsection "Discussion" - " - WATCH can monitor any memory-allocated lisp object. - - - - In Clozure CL, a memory-allocated object is either a cons cell - or a uvector. - - - - WATCH operates on cons cells, not lists. In order to watch a - chain of cons cells, each cons cell must be watched - individually. Because each watched cons cell takes up its own - own virtual memory page (4 Kbytes), it's only feasible to watch - relatively short lists. - - - - If a memory-allocated object isn't a cons cell, then it is a - vector-like object called a uvector. A uvector is a - memory-allocated lisp object whose first word is a header that - describes the object's type and the number of elements that it - contains. - - - - So, a hash table is a uvector, as is a string, a standard - instance, a double-float, a CL array or vector, and so forth. - - - - Some CL objects, like strings and other simple vectors, map in a - straightforward way onto the uvector representation. It is easy - to understand what happens in such cases. The uvector index - corresponds directly to the vector index: - " - (code-block #:| -? (defvar *s* "xxxxx") -*S* -? (watch *s*) -"xxxxx" -? (setf (char *s* 3) #\\o) -> Error: Write to watched uvector "xxxxx" at index 3 -> Faulting instruction: (movl (% eax) (@ -5 (% r15) (% rcx))) -> While executing: SET-CHAR, in process listener(1). -> Type :POP to abort, :R for a list of available restarts. -> Type :? for other options. -|) - #:| - In the case of more complicated objects (e.g., a hash-table, a - standard-instance, a package, etc.), the elements of the uvector - are like slots in a structure. It's necessary to know which one - of those "slots" contains the data that will be changed when the - object is written to. - - - - As mentioned above, watch knows about arrays, hash-tables, and - standard-instances, and will automatically watch the appropriate - data-containing element. - - - - An example might make this clearer. - | - (code-block " -? (defclass foo () - (slot-a slot-b slot-c)) -# -? (defvar *a-foo* (make-instance 'foo)) -*A-FOO* -? (watch *a-foo*) -# -;;; Note that WATCH has watched the internal slot-vector object -? (setf (slot-value *a-foo* 'slot-a) 'foo) -> Error: Write to watched uvector # at index 1 -> Faulting instruction: (movq (% rsi) (@ -5 (% r8) (% rdi))) -> While executing: %MAYBE-STD-SETF-SLOT-VALUE-USING-CLASS, in process listener(1). -> Type :POP to abort, :R for a list of available restarts. -> Type :? for other options. -") - " - Looking at a backtrace would presumably show what object and - slot name were written. - - - - Note that even though the write was to slot-a, the uvector index - was 1 (not 0). This is because the first element of a - slot-vector is a pointer to the instance that owns the slots. We - can retrieve that to look at the object that was modified: - " - (code-block " -1 > (uvref (write-to-watched-object-object *break-condition*) 0) -# -1 > (describe *) -# -Class: # -Wrapper: # -Instance slots -SLOT-A: # -SLOT-B: # -SLOT-C: # -1 > -"))) - - (definition (:function unwatch) "unwatch object" " - Stop monitoring a lisp object for writes. - " - (defsection "Description" - (para "The UNWATCH function ensures that the specified - object is in normal, non-monitored memory. If the object is not - currently being watched, UNWATCH does nothing and returns - NIL. Otherwise, the newly unwatched object is returned. - "))) - - (definition (:condition ccl::write-to-watched-object) "WRITE-TO-WATCHED-OBJECT" " - Condition signaled when a write to a watched object is attempted. - " - (defsection "Discussion" - (para " - This condition is signaled when a watched object is written - to. There are three slots of interest: - ") - (listing :definition - (item "object" ccldoc::=> " - The actual object that was the destination of the write. - ") - (item "offset" ccldoc::=> " - The byte offset from the tagged object pointer to the - address of the write. - ") - (item "instruction" ccldoc::=> " - The disassembled machine instruction that attempted the write. - "))) - (defsection "Restarts" - " - A few restarts are provided: one will skip over the faulting - write instruction and proceed; another offers to unwatch the - object and continue. - - - - There is also an emulate restart. In some common cases, the - faulting write instruction can be emulated, enabling the write - to be performed without having to unwatch the object (and - therefore let other threads potentially write to it). If the - faulting instruction isn't recognized, the emulate restart will - not be offered. - ")) - - (defsection "Notes" - " - Although some care has been taken to minimize potential problems - arising from watching and unwatching objects from multiple - threads, there may well be subtle race conditions present that - could cause bad behavior. - - - - For example, suppose that a thread attempts to write to a watched - object. This causes the operating system to generate an - exception. The lisp kernel figures out what the exception is, and - calls back into lisp to signal the write-to-watched-object - condition and perhaps handle the error. - - - - Now, as soon lisp code starts running again (for the callback), - it's possible that some other thread could unwatch the very - watched object that caused the exception, perhaps before we even - have a chance to signal the condition, much less respond to it. - - - - Having the object unwatched out from underneath a handler may at - least confuse it, if not cause deeper trouble. Use caution with - unwatch. -") - (defsection "Examples" - (para " - Here are a couple more examples in addition to the above examples - of watching a string and a standard-instance. -") - (defsection "Fancy arrays" - (code-block " -? (defvar *f* (make-array '(2 3) :element-type 'double-float)) -*F* -? (watch *f*) -#(0.0D0 0.0D0 0.0D0 0.0D0 0.0D0 0.0D0) -;;; Note that the above vector is the underlying data-vector for the array -? (setf (aref *f* 1 2) pi) -> Error: Write to watched uvector # at index 5 -> Faulting instruction: (movq (% rax) (@ -5 (% r8) (% rdi))) -> While executing: ASET, in process listener(1). -> Type :POP to abort, :R for a list of available restarts. -> Type :? for other options. -1 > - ") - (para " - In this case, uvector index in the report is the row-major index - of the element that was written to. - ")) - (defsection "Hash tables" - " - Hash tables are surprisingly complicated. The representation of a - hash table includes an element called a hash-table-vector. The - keys and values of the elements are stored pairwise in this - vector. - - - - One problem with trying to monitor hash tables for writes is that - the underlying hash-table-vector is replaced with an entirely new - one when the hash table is rehashed. A previously-watched - hash-table-vector will not be the used by the hash table after - rehashing, and writes to the new vector will not be caught. - " - (code-block " -? (defvar *h* (make-hash-table)) -*H* -? (setf (gethash 'noise *h*) 'feep) -FEEP -? (watch *h*) -# -;;; underlying hash-table-vector -? (setf (gethash 'noise *h*) 'ding) -> Error: Write to watched uvector # at index 35 -> Faulting instruction: (lock) -> (cmpxchgq (% rsi) (@ (% r8) (% rdx))) -> While executing: %STORE-NODE-CONDITIONAL, in process listener(1). -> Type :POP to abort, :R for a list of available restarts. -> Type :? for other options. -;;; see what value is being replaced... -1 > (uvref (write-to-watched-object-object *break-condition*) 35) -FEEP -;;; backtrace shows useful context -1 > :b -*(1A109F8) : 0 (%STORE-NODE-CONDITIONAL ???) NIL - (1A10A50) : 1 (LOCK-FREE-PUTHASH NOISE # DING) 653 - (1A10AC8) : 2 (CALL-CHECK-REGS PUTHASH NOISE # DING) 229 - (1A10B00) : 3 (TOPLEVEL-EVAL (SETF (GETHASH # *H*) 'DING) NIL) 709 - ... - ")) - (defsection "Lists" - (para " - As previously mentioned, WATCH only watches individual cons cells. - ") - (code-block " -? (defun watch-list (list) - (maplist #'watch list)) -WATCH-LIST -? (defvar *l* (list 1 2 3)) -*L* -? (watch-list *l*) -((1 2 3) (2 3) (3)) -? (setf (nth 2 *l*) 'foo) -> Error: Write to the CAR of watched cons cell (3) -> Faulting instruction: (movq (% rsi) (@ 5 (% rdi))) -> While executing: %SETNTH, in process listener(1). -> Type :POP to abort, :R for a list of available restarts. -> Type :? for other options. -")))) - -(defsection "Memory" - (definition (:function heap-utilization) "heap-utilization &key (stream *debug-io*) (gc-first t) area unit (sort :size) classes start threshold)" nil - - "This function walks the lisp heap, collects information about the -objects stored on the heap, and prints a report of the results to the -stream speficied by the keyword argument {code :stream}. It shows the -number of objects of each type, the sum of their logical sizes (the -size of the data part of the object) and the sum of their physical -sizes (the total size as computed by {function object-direct-size}). - -If {code :gc-first} is true (the default), {function heap-utilization} -does a full gc before scanning the heap. - -If {code :classes} is true, objects are classified by class rather -than just basic type. - -The keyword argument {code :area} can be used to restrict the walk to -one memory area or a list of areas. Some possible values -are {code :dynamic}, {code :static}, {code :managed-static}, and -{code :readonly}. By default, all areas (including stacks) are examined. - -The keword argument {code :sort} can be one of {code :count}, -{code :logical-size}, or {code :physical-size} to sort output by count -or size. - -By default, sizes are shown in bytes. The keyword argument -{code :unit} can be {code :kb}, {code :mb}, or {code :gb} -to show sizes in those units. - -If {code :start} is non-nil, it should be an object returned by -{function get-allocation-sentinel}; only objects at higher address are -scanned (roughly, only objects allocated after it). - -If threshold is non-nil, it should be a number between 0 and 1. All -types whose share of the heap is less than threshold will be lumped -together in an “All Others” line rather than being listed -individually.") - -(definition (:function object-direct-size) "object-direct-size thing" nil - "This function returns the size of {param thing} in bytes, including -any headers and alignment overhead. It does not descend into an object's -components.")) - -(definition (:variable *disassemble-verbose*) "*disassemble-verbose*" nil - "When true, the output of {code disassemble} may include - platform-dependent additional information. For instance, on the x86 - ports, the output will include the x86 opcode bytes. - - The default value is {code nil}.") - -) ;end chapter - - - diff --git a/ccl-documentation/external-process.ccldoc b/ccl-documentation/external-process.ccldoc deleted file mode 100644 index 2ad094e..0000000 --- a/ccl-documentation/external-process.ccldoc +++ /dev/null @@ -1,181 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Running Other Programs as Subprocesses" - (defsection "Overview" - "{CCL} provides primitives to run external Unix programs, - to select and connect Lisp streams to their input and output - sources, to (optionally) wait for their completion and to check - their execution and exit status. - - All of the global symbols described below are exported - from the CCL package. - - This implementation is modeled on - and uses some code - from - similar facilities in CMUCL.") - (defsection "Examples" - (code-block #:| -;;; Capture the output of the "uname" program in a lisp string-stream -;;; and return the generated string (which will contain a trailing -;;; newline.) -? (with-output-to-string (stream) - (run-program "uname" '("-r") :output stream)) -;;; Write a string to *STANDARD-OUTPUT*, the hard way. -? (run-program "cat" () :input (make-string-input-stream "hello") :output t) -;;; Find out that "ls" doesn't expand wildcards. -? (run-program "ls" '("*.lisp") :output t) -;;; Let the shell expand wildcards. -? (run-program "sh" '("-c" "ls *.lisp") :output t) -|) - (para "These last examples will only produce output if {CCL}'s - current directory contains .lisp files, of course.")) - (defsection "Limitations and known bugs" - (listing :bullet - (item "{CCL} and the external process may get - confused about who owns which streams when input, output, or - error are specified as T and wait is specified as - NIL.") - (item "External processes that need to talk to a - terminal device may not work properly; the environment (SLIME, - ILISP) under which {CCL} is run can affect - this."))) - (defsection "External-Program Dictionary" - (definition (:function run-program) - "run-program program args &key (wait t) pty sharing input if-input-does-not-exist output (if-output-exists :error) (error :output) (if-error-exists :error) status-hook external-format env (silently-ignore-catastrophic-failures *silently-ignore-catastrophic-failure-in-run-program*)" - "Invokes an external program as an OS subprocess - of lisp." - (defsection "Arguments and Values" - (listing :definition - (item "{param program}" ccldoc::=> "A string or pathname which denotes an executable file. - The PATH environment variable is used to find programs whose - name doesn't contain a directory component.") - (item "{param args}" ccldoc::=> "A list of simple-strings") - (item "{param wait}" ccldoc::=> "Indicates whether or not run-program should wait for - the EXTERNAL-PROCESS to complete or should return - immediately.") - (item "{param pty}" ccldoc::=> "This option is accepted but currently ignored; - it's intended to make it easier to run external programs - that need to interact with a terminal device.") - (item "{param sharing}" ccldoc::=> "Sets a specific sharing mode - (see {section Additional keywords for OPEN and MAKE-SOCKET}) for any streams created - within RUN-PROGRAM when INPUT, OUTPUT or ERROR are requested - to be a :STREAM.") - (item "{param input}" ccldoc::=> - (para "Selects the input source used by the EXTERNAL-PROCESS. - May be any of the following:") - (listing :bullet - (item "NIL Specifies that a null input stream (e.g., - /dev/null) should be used.") - (item "T Specifies that the EXTERNAL-PROCESS should use - the input source with which {CCL} was invoked.") - (item "A string or pathname. Specifies that the - EXTERNAL-PROCESS should receive its input from the named - existing file.") - (item ":STREAM Creates a Lisp stream opened for character - output. Any data written to this stream (accessible as - the EXTERNAL-PROCESS-INPUT-STREAM of the - EXTERNAL-PROCESS object) appears as input to the - external process.") - (item "A stream. Specifies that the lisp stream should - provide input to the EXTERNAL-PROCESS."))) - (item "{param if-input-does-not-exist}" ccldoc::=> "If the input argument specifies the name of an - existing file, this argument is used as the - if-does-not-exist argument to OPEN when that file is opened.") - (item "{param output}" ccldoc::=> "Specifies where standard output from the external - process should be sent. Analogous to input above.") - (item "{param if-output-exists}" ccldoc::=> "If output is specified as a string or pathname, this - argument is used as the if-exists argument to OPEN when that - file is opened.") - (item "{param error}" ccldoc::=> "Specifies where error output from the external process - should be sent. In addition to the values allowed for - output, the keyword :OUTPUT can be used to indicate that - error output should be sent where standard output goes.") - (item "{param if-error-exists}" ccldoc::=> "Analogous to if-output-exists.") - (item "{param status-hook}" ccldoc::=> "A user-defined function of one argument (the - EXTERNAL-PROCESS structure.) This function is called - whenever {CCL} detects a change in the status of the - EXTERNAL-PROCESS.") - (item "{param external-format}" ccldoc::=> " - The external format (see {section External Formats}) for all of the - streams (input, output, and error) used to - communicate with the external process. - ") - (item "{param env}" ccldoc::=> " - New OS environment variable bindings for the - external process. By default the external process - inherits the environment of the running Lisp - process. Env is an association list with elements - ( . ). Name and - value are case sensitive strings. See " - (ref (definition :function setenv)) ". - ") - (item "{param silently-ignore-catastrophic-failures}" ccldoc::=> " - If NIL, signal an error if run-program is unable - to start the program. If non-NIL, treat failure to - start the same as failure from the program itself, - by setting the status and exit-code - fields. Default is - {variable ccl::*silently-ignore-catastrophic-failure-in-run-program*}. - "))) - (defsection "Description" - "Runs the specified program in an external (Unix) process, - returning an object of type EXTERNAL-PROCESS if successful. - - The implementation involves a lisp process/thread which - monitors the status of this external process and arranges for - the standard I/O descriptors for the external process to be - connected to the specified lisp streams. Since this may require - the monitoring thread to do I/O on lisp streams in some cases, - streams provided as the values of the {code :INPUT}, - {code :OUTPUT}, and {code :ERROR} arguments - should not be private to some other lisp thread.")) - - (definition (:function signal-external-process) - "signal-external-process proc sig &key (error-if-exited t)" nil - "Sends signal number {param sig} to the external process {param - proc} (which would have been returned by {function run-program}. - Typically, it would only be useful to call this function if the - {param proc} was created with {code :wait nil}. - - If successful, the function returns {code t}; otherwise, an error is - signaled. - - However, if {param error-if-exited} is {code nil}, and the attempt to - signal the external process fails because the external process - has already exited, the function will return nil rather than - signaling an error.") - - (definition (:function external-process-id) "external-process-id proc" nil - "Returns the operating system process ID assigned to the - external-process object {param proc}.") - - (definition (:function external-process-input-stream) - "external-process-input-stream proc" nil - "Returns the lisp stream which is used to write input to the - external-process object {param proc}, if it has one. This will - be the stream created when the {code :input} argument to - {function run-program} is specified as {code :stream}.") - - (definition (:function external-process-output-stream) - "external-process-output-stream proc" nil - "Returns the lisp stream which is used to read output from the - external-process object {param proc}, if there is one. This is - the stream created when the {code :output} argument to {function - run-program} is specified as {code :stream}.") - - (definition (:function external-process-error-stream) - "external-process-error-stream proc" nil - "Returns the stream which is used to read - error output from a given OS subprocess, if there is one. - This is the stream created when the {code :error} argument - to {function run-program} is specified as {code :stream}.") - - (definition (:function external-process-status) - "external-process-status proc" nil - "Returns, as multiple values, a keyword denoting the status of - the external process {param proc} (one of {code :running}, - {code :stopped}, {:code signaled}, or {:code exited}), and the - exit code or terminating signal if the first value is other - than {code :running}.")) - -) ;chapter diff --git a/ccl-documentation/ffi.ccldoc b/ccl-documentation/ffi.ccldoc deleted file mode 100644 index 88b207e..0000000 --- a/ccl-documentation/ffi.ccldoc +++ /dev/null @@ -1,2552 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "The Foreign-Function Interface" - (defsection "Specifying And Using Foreign Types" - "{CCL} provides a fairly rich language for defining and specifying - foreign data types (this language is derived from CMUCL's “alien - type” system.) - - In practice, most foreign type definitions are introduced into - {CCL} via its interface database, though it is also possible to - define foreign types interactively and/or programmatically. - - {CCL}'s foreign type system is “evolving” (a polite word for - not-quite-complete): there are some inconsistencies involving - package usage, for instance. Symbols used in foreign type - specifiers {emphasis should} be keywords, but this convention - isn't always enforced. - - Foreign type, record, and field names are case-sensitive; {CCL} - uses some escaping conventions to allow keywords to be used to - denote these names." - - (defsection "Type Annotations" - "As of version 1.2, {CCL} supports annotating the types of - foreign pointers on Mac OS X. Forms that create pointers to - foreign memory-that is, {code MACPTR}s-store - with the {code MACPTR} object a type annotation that - identifies the foreign type of the object pointed - to. Calling {code PRINT-OBJECT} on a {code MACPTR} - attempts to print information about the identified foreign - type, including whether it was allocated on the heap or the - stack, and whether it's scheduled for automatic reclamation by - the garbage collector. - - Support for type annotation is not yet complete. In - particular, some uses of {code PREF} - and {code SLOT-VALUE} do ot yet take type annotations into - account, and neither do {code DESCRIBE} - and {code INSPECT}.") - - (defsection "Foreign Types as Classes" - "Some types of foreign pointers take advantage of the - support for type annotations, and pointers of these types - can be treated as instances of known classes. Specifically, - a pointer to an {code :ect} is recognized - as an instance of the built-in - class {code NS:NS-RECT}, a pointer to - an {code ize} is treated as an instance - of {code NS:NS-SIZE}, a pointer to - an {code oint} is recognized as an - instance of {code NS:NS-POINT}, and a pointer to - an {code ange} is recognized as an - instance of {code NS:NS-RANGE}. - - A few more obscure structure types also support this - mechanism, and it's possible that a future version will - support user definition of similar type mappings. - - This support for foreign types as classes provides the - following conveniences for each supported type:" - (listing :bullet - (item "a {code PRINT-OBJECT} method is defined") - (item "a foreign type name is created and treated as an alias - for the corresponding type. As an example, the - name {code :NS-RECT} is a name for the type that - corresponds to {code NS:NS-RECT}, and you can - use {code :NS-RECT} as a type designator - in " - (ref (definition :macro rlet)) " forms to - specify a structure of type {code NS-RECT}.") - (item "the class is integrated into the type system so that - {code (TYPEP R 'NS:NS-RECT)} is implemented with - fair efficiency.") - (item "inlined accessor and {code SETF} inverses are - defined for the structure type's fields. In the case of - an {code "The argument/return value is of type (UNSIGNED-BYTE 8)") - (item "{code :SIGNED-BYTE}" ccldoc::=> "The argument/return value is of type (SIGNED-BYTE 8)") - (item "{code :UNSIGNED-HALFWORD}" ccldoc::=> "The argument/return value is of type (UNSIGNED-BYTE 16)") - (item "{code :SIGNED-HALFWORD}" ccldoc::=> "The argument/return value is of type (SIGNED-BYTE 16)") - (item "{code :UNSIGNED-FULLWORD}" ccldoc::=> "The argument/return value is of type (UNSIGNED-BYTE 32)") - (item "{code :SIGNED-FULLWORD}" ccldoc::=> "The argument/return value is of type (SIGNED-BYTE 32)") - (item "{code :UNSIGNED-DOUBLEWORD}" ccldoc::=> "The argument/return value is of type (UNSIGNED-BYTE 64)") - (item "{code :SIGNED-DOUBLEWORD}" ccldoc::=> "The argument/return value is of type (SIGNED-BYTE 64)") - (item "{code :SINGLE-FLOAT}" ccldoc::=> "The argument/return value is of type SINGLE-FLOAT") - (item "{code :DOUBLE-FLOAT}" ccldoc::=> "The argument/return value is of type DOUBLE-FLOAT") - (item "{code :ADDRESS}" ccldoc::=> "The argument/return values - is " - (ref (section "Referencing and Using Foreign Memory Addresses") "a MACPTR") ".") - (item "{code :VOID}" ccldoc::=> "or NIL Not valid as an argument type specifier; specifies - that there is no meaningful return value")) - (para "On some platforms, a small positive integer - {emphasis N} can also be used as an argument - specifier; it indicates that the corresponding argument is a - pointer to an {emphasis N}-word structure or union - which should be passed by value to the foreign - function. Exactly which foreign structures are passed - by value and how is very dependent on the Application - Binary Interface (ABI) of the platform; unless you're - very familiar with ABI details (some of which are quite - baroque), it's often easier to let higher-level constructs - deal with these details.")) - - (defsection "External Entrypoints and Named External Entrypoints" - "PowerPC machine instructions are always aligned on - 32-bit boundaries, so the two least significant bits of the - first instruction (the entrypoint) of a foreign function are - always 0. {CCL} often represents an entrypoint address as - a fixnum that's binary-equivalent to the entrypoint address: - if{emphasis E} is an entrypoint address expressed - as a signed 32-bit integer, then (ash {emphasis E} - -2) is an equivalent fixnum representation of that - address. An entrypoint address can also be encapsulated in a - MACPTR, but that's somewhat less efficient. - - Although it's possible to use fixnums or macptrs to - represent entrypoint addresses, it's somewhat cumbersome to - do so. {CCL} can cache the addresses of named external - functions in structure-like objects of type - CCL:EXTERNAL-ENTRY-POINT (sometimes abbreviated as EEP). - Through the use of LOAD-TIME-VALUE, compiled lisp functions - are able to reference EEPs as constants; the use of an - indirection allows {CCL} runtime system to ensure that the - EEP's address is current and correct.")) - - (defsection "Return Conventions for C Structures" - "On some platforms, C functions that are defined to - return structures do so by reference: they actually - accept a first parameter of type “pointer to returned - struct/union” - which must be allocated by the caller - and - don't return a meaningful value. - - {emphasis Exactly} how a C function that's - defined to return a foreign structure does so is dependent on - the ABI (and on the size and composition of the structure/union - in many cases.)")) - - (defsection "Referencing and Using Foreign Memory Addresses" - (defsection "Overview" - (defsection "Basics" - "For a variety of technical reasons, it isn't generally - possible to directly reference arbitrary absolute addresses - (such as those returned by the C library function malloc(), - for instance) in {CCL}. In {CCL} (and in MCL), such - addresses need to be {emphasis encapsulated} in - objects of type CCL:MACPTR; one can think of a MACPTR as - being a specialized type of structure whose sole purpose is - to provide a way of referring to an underlying raw - address. - - It's sometimes convenient to blur the distinction - between a MACPTR and the address it represents; it's - sometimes necessary to maintain that distinction. It's - important to remember that a MACPTR is (generally) a - first-class Lisp object in the same sense that a CONS cell - is: it'll get GCed when it's no longer possible to reference - it. The lifetime of a MACPTR doesn't generally have - anything to do with the lifetime of the block of memory its - address points to. - - It might be tempting to ask “How does one obtain the - address encapsulated by a macptr?”. The answer to that - question is that one doesn't do that (and there's no way to - do that): addresses aren't first-class objects, and there's - no way to refer to one. - - Two MACPTRs that encapsulate the same address are EQL - to each other. - - There are a small number of ways to directly create a - MACPTR (and there's a fair amount of syntactic sugar built - on top of of those primitives.) These primitives will be - discussed in greater detail below, but they include:" - (listing :bullet - (item "Creating a MACPTR with a specified address, usually - via the function CCL:%INT-TO-PTR.") - (item "Referencing the return value of a foreign function - call (see )that's specified to return an address.") - (item "Referencing a memory location that's specified to - contain an address.")) - "All of these primitive MACPTR-creating operations are - usually open-coded by the compiler; it has a fairly good - notion of what low-level operations produce MACPTRs and - which operations consume the addresses that the - encapsulate, and will usually optimize out the introduction - of intermediate MACPTRs in a simple expression. - - One consequence of the use of MACPTR objects to - encapsulate foreign addresses is that (naively) - {emphasis every reference to a foreign address causes a - MACPTR to be allocated.} - -Consider a code fragment like the following:" - (code-block "(defun get-next-event () - \"get the next event from a hypothetical window system\" - (loop - (let* ((event (#_get_next_window_system_event))) ; via an FF-CALL - (unless (null-event-p event) - (handle-event event))))) -") - - (para "As this is written, each call to the (hypothetical) - foreign function #_get_next_window_system_event will return - a new MACPTR object. Ignoring for the sake of argument the - question of whether this code fragment exhibits a good way - to poll for external events (it doesn't), it's not hard to - imagine that this loop could execute several million times - per second (producing several million MACPTRs per second.) - Clearly, the naive approach is impractical in many - cases.")) - - (defsection "Stack allocation of-and destructive operations on-MACPTRs." - (para "If certain conditions held in the environment in which - GET-NEXT-EVENT ran-namely, if it was guaranteed that - neither NULL-EVENT-P nor HANDLE-EVENT cached or otherwise - retained their arguments (the “event” pointer)-there'd be - a few alternatives to the naive approach. One of those - approaches would be to use the primitive function - %SETF-MACPTR (described in greater detail below) to - destructively modify a MACPTR (to change the value of the - address it encapsulates.) The GET-NEXT-EVENT example could - be re-written as:") - (code-block "(defun get-next-event () - (let* ((event (%int-to-ptr 0))) ; create a MACPTR with address 0 - (loop - (%setf-macptr event (#_get_next_window_system_event)) ; re-use it - (unless (null-event-p event) - (handle-event event))))) - ") - "That version's a bit more realistic: it allocates a - single MACPTR outside if the loop, then changes its address - to point to the current address of the hypothetical event - structure on each loop iteration. If there are a million - loop iterations per call to GET-NEXT-EVENT, we're allocating - a million times fewer MACPTRs per call; that sounds like a - Good Thing. - - An Even Better Thing would be to advise the compiler - that the initial value (the null macptr) bound to the - variable event has dynamic extent (that value won't be - referenced once control leaves the extent of the binding of - that variable.) Common Lisp allows us to make such an - assertion via a dynamic-extent declaration; {CCL}'s - compiler can recognize the primitive macptr-creating - operation involved and can replace it with an equivalent - operation that stack-allocates the macptr object. If we're - not worried about the cost of allocating that macptr on - every iteration (the cost is small and there's no hidden GC - cost), we could move the binding back inside the - loop:" - (code-block "(defun get-next-event () - (loop - (let* ((event (%null-ptr))) ; (%NULL-PTR) is shorthand for (%INT-TO-PTR 0) - (declare (dynamic-extent event)) - (%setf-macptr event (#_get_next_window_system_event)) - (unless (null-event-p event) - (handle-event event))))) - ") - (para "The idiom of binding one or more variables to - stack-allocated MACPTRs, then destructively modifying those - MACPTRs before executing a body of code is common enough - that {CCL} provides a macro (WITH-MACPTRS) that handles - all of the gory details. The following version of - GET-NEXT-EVENT is semantically equivalent to the previous - version, but hopefully a bit more concise:") - (code-block "(defun get-next-event () - (loop - (with-macptrs ((event (#_get_next_window_system_event))) - (unless (null-event-p event) - (handle-event event))))) - ")) - (defsection "Stack-allocated memory (and stack-allocated pointers to it.)" - (para "Fairly often, the blocks of foreign memory (obtained - by malloc or something similar) have well-defined lifetimes - (they can safely be freed at some point when it's known that - they're no longer needed and it's known that they're no - longer referenced.) A common idiom might be:") - (code-block "(with-macptrs (p (#_allocate_foreign_memory size)) - (unwind-protect - (use-foreign-memory p) - (#_deallocate_foreign_memory p))) - ") - "That's not unreasonable code, but it's fairly - expensive for a number of reasons: foreign functions calls - are themselves fairly expensive (as is UNWIND-PROTECT), and - most library routines for allocating and deallocating - foreign memory (things like malloc and free) can be fairly - expensive in their own right. - - In the idiomatic code above, both the MACPTR P and the - block of memory that's being allocated and freed have - dynamic extent and are therefore good candidates for stack - allocation. {CCL} provides the %STACK-BLOCK macro, which - executes a body of code with one or more variables bound to - stack-allocated MACPTRs which encapsulate the addresses of - stack-allocated blocks of foreign memory. Using - %STACK-BLOCK, the idiomatic code is:" - (code-block "(%stack-block ((p size)) - (use-foreign-memory p)) - ") - "which is a bit more efficient and a bit more concise - than the version presented earlier. - - %STACK-BLOCK is used as the basis for slightly - higher-level things like RLET. (See FIXTHIS for more information - about RLET.)") - (defsection "Caveats" - (para "Reading from, writing to, allocating, and freeing - foreign memory are all potentially dangerous operations; - this is no less true when these operations are performed in - {CCL} than when they're done in C or some other - lower-level language. In addition, destructive operations on - Lisp objects be dangerous, as can stack allocation if it's - abused (if DYNAMIC-EXTENT declarations are violated.) - Correct use of the constructs and primitives described here - is reliable and safe; even slightly incorrect use of these - constructs and primitives can crash {CCL}."))) - - (defsection "Foreign-Memory-Addresses Dictionary" - (para "Unless otherwise noted, all of the symbols mentioned - below are exported from the CCL package.") - (defsection "Scalar memory reference" - (definition (:function %get-unsigned-byte) - "%get-unsigned-byte ptr &optional (offset 0)" "" - "References and returns the unsigned 8-bit byte at the effective byte - address formed by adding {param offset} to the address encapsulated by - {param ptr}.") - (definition (:function %get-signed-byte) - "%get-signed-byte ptr &optional (offset 0)" "" - "Like {function %get-unsigned-byte} above, but returns - the signed 8-bit byte at the computed address.") - (definition (:function %get-unsigned-word) - "%get-unsigned-word ptr &optional (offset 0)" "" - "References and returns the unsigned 16-bit word at the effective byte - address formed by adding {param offset} to the address encapsulated by - {param ptr}.") - (definition (:function %get-signed-word) - "%get-signed-word ptr &optional (offset 0)" "" - "Like {function %get-unsigned-word} above, but returns - the signed 16-bit word at the computed address.") - (definition (:function %get-unsigned-long) - "%get-unsigned-long ptr &optional (offset 0)" "" - "References and returns the unsigned 32-bit long word at the effective byte - address formed by adding {param offset} to the address encapsulated by - {param ptr}.") - (definition (:function %get-signed-long) - "%get-signed-long ptr &optional (offset 0)" "" - "Like {function %get-unsigned-long} above, but returns - the signed 32-bit long word at the computed address.") - (definition (:function %%get-unsigned-longlong) - "%%get-unsigned-longlong ptr &optional (offset 0)" "" - "References and returns the unsigned 64-bit long long word at the effective byte - address formed by adding {param offset} to the address encapsulated by - {param ptr}.") - (definition (:function %%get-signed-longlong) - "%%get-signed-longlong ptr &optional (offset 0)" "" - "Like {function %%get-unsigned-longlong} above, but returns - the signed 64-bit long long word at the computed address.") - (definition (:function %get-ptr) - "%get-ptr ptr &optional (offset 0)" nil - "Returns a macptr encapsulating the address found at the effective byte address - formed by adding {param offset} to the address represented by {param ptr}.") - (definition (:function %get-single-float) - "%get-single-float ptr &optional (offset 0)" nil - "Returns the {code single-float} found at the effective byte address - formed by adding {param offset} to the address represented by {param ptr}.") - (definition (:function %get-double-float) - "%get-double-float ptr &optional (offset 0)" nil - "Returns the {code double-float} found at the effective byte address - formed by adding {param offset} to the address represented by {param ptr}.") - - "All of the memory reference primitives described above can be used with - {code setf}.") - - (definition (:function "%get-bit") "%get-bit ptr bit-offset" nil - "References and returns the {param bit-offset}th bit at the address - encapsulated by {param ptr}. (Bit 0 at a given address is the most - significant bit of the byte at that address.) Can be used with - SETF.") - - (definition (:function "%get-bitfield") "%get-bitfield ptr bit-offset width" nil - "References and returns an unsigned integer composed from the - {param width} bits found {param bit-offset} bits from the address encapsulated by - {param ptr}. The least significant bit of the result is the value of - {code (%get-bit ptr (1- (+ bit-offset width)))}. Can be used with {code setf}.") - - (definition (:function "%int-to-ptr") "%int-to-ptr int" nil - "Creates and returns a macptr whose address is {param int}.") - - (definition (:function "%inc-ptr") "%inc-ptr ptr &optional (delta 1)" nil - "Creates and returns a macptr whose address is the address of - {param ptr} plus {param delta}. The idiom {code (%inc-ptr ptr 0)} - is sometimes used to copy a macptr, that is, to create a new macptr - encapsulating the same address as {param ptr}.") - - (definition (:function "%ptr-to-int") "%ptr-to-int ptr" nil - "Returns the address encapsulated by {param ptr} as an integer.") - - (definition (:macro "%null-ptr") "%null-ptr" nil - "Equivalent to {code (%int-to-ptr 0)}.") - - (definition (:function "%null-ptr-p") "%null-ptr-p ptr" nil - "This function returns true if {param ptr} is a macptr that encapsulates the - address 0. It returns {code nil} if {param ptr} encapsulates some other address.") - - (definition (:function %setf-macptr) "%setf-macptr dest-ptr src-ptr" nil - "Causes {param dest-ptr} to encapsulate the same address that - {param src-ptr} does, then returns the updated {param - dest-ptr}.") - - (definition (:macro %incf-ptr) "%incf-ptr ptr &optional (delta 1)" nil - "Destructively modifies {param ptr} by adding {param delta} to - the address it encapsulates. Returns {param ptr}.") - - (definition (:macro with-macptrs) "with-macptrs (var expr)* &body body" nil - "Executes {param body} in an environment in which each {param - var} is bound to a stack-allocated macptr which encapsulates - the foreign address yielded by the corresponding {param - expr}. Returns whatever values body returns.") - - (definition (:macro %stack-block) "%stack-block (var expr)* &body body" nil - "Executes {param body} in an environment in which each {param - var} is bound to a stack-allocated macptr which encapsulates - the address of a stack-allocated region of size {param expr} - bytes. Returns whatever value(s) body returns.") - - (definition (:function make-cstring) "make-cstring string" nil - "Allocates a block of foreign memory (via {code malloc}) of -length {code (1+ (length {param string}))}. It then copies {param -string} to this block and appends a trailing nul byte. Returns a -macptr to the block.") - - (definition (:macro with-encoded-cstrs) "with-encoded-cstrs encoding-name (var string)* &body body" nil - "Executes body in an environment in which each {param var} is bound - to a macptr which encapsulates the %address of a - stack-allocated region of into which each {param string} (and a - trailing NUL character) has been copied. Returns whatever - value(s) body returns. - - The {param encoding-name} should be a keyword that names a - character encoding. Each foreign string is encoded according - to the named encoding. Each foreign string has dynamic - extent. - - Note that {macro with-encoded-cstrs} does not automatically - prepend byte-order marks to the encoded strings; - additionally, the size of the terminating {code #\\NUL} - character depends on the number of octets per code unit in - the encoding. - - The expression " - (code-block "(ccl:with-cstrs ((x \"x\")) (#_puts x))") - "is functionally equivalent to " - (code-block "(ccl:with-encoded-cstrs :iso-8859-1 ((x \"x\")) (#_puts x))")) - - (definition (:macro with-cstrs) "with-cstrs (var string)* &body body" nil - "Executes {param body} in an environment in which each {param var} - is bound to a macptr which encapsulates the address of a - stack-allocated region of memory into which each {param string} (and - a trailing NUL character) has been copied. Returns whatever - values body returns. - - This macro is hard-coded to use the {code :iso-8859-1} encoding. The macro - {macro with-encoded-cstrs} allows you to specify the encoding.") - - - (definition (:function %get-cstring) "%get-cstring ptr" nil - "This function interprets {param ptr} as a pointer to a (null-terminated) C string, - and returns an equivalent lisp string.") - - (definition (:function %str-from-ptr) "%str-from-ptr ptr length" nil - "Returns a lisp string of length {param length}, - whose contents are initialized from the bytes at {param ptr.}") - - (definition (:function get-encoded-string) "get-encoded-string encoding-name ptr len" nil - "Creates and returns a lisp string from {param len} octets pointed to by {param ptr} - decoded according to {param encoding-name}."))) - - (defsection "The Interface Database" - (defsection "Overview" - "{CCL} uses a set of database files which contain - foreign type, record, constant, and function definitions - derived from the operating system's header files, be that - Linux or Darwin. An archive containing these database files - (and the shell scripts which were used in their creation) is - available; see the Distributions page for information about - obtaining current interface database files. - -Not surprisingly, different platforms use different database files. - -{CCL} defines reader macros that consult these databases:" - (listing :bullet - (item "#$foo looks up the value of the constant definition of foo") - (item "#_foo looks up the foreign function definition for foo")) - "In both cases, the symbol foo is interned in the {code OS} - package. The #$ reader macro has the side-effect of defining - foo as a constant (as if via DEFCONSTANT); the #_ reader macro - has the side effect of defining foo as a macro which will - expand into an (EXTERNAL-CALL form.) - - It's important to remember that the side-effect happens - when the form containing the reader macro is - read. Macroexpansion functions that expand into forms which - contain instances of those reader macros don't do what one - might think that they do, unless the macros are expanded in - the same lisp session as the reader macro was read in. - - In addition, references to foreign type, - structure/union, and field names (when used in the RREF/PREF - and RLET macros) will cause these database files to be - consulted. - - Since the {CCL} sources contain instances of these - reader macros (and references to foreign record types and - fields), compiling {CCL} from those sources depends on the - ability to find and use (see {section Building the Heap Image}).") - - (defsection "Other issues:" - (listing :bullet - (item "{CCL} now preserves the case of external symbols in - its database - files. See {section Case-sensitivity of foreign names in {CCL}} for information about - case in foreign symbol names.") - (item "The Linux databases are derived from a somewhat - arbitrary set of Linux header files. Linux is enough of a - moving target that it may be difficult to define a standard, - reference set of interfaces from which to derive a standard, - reference set of database files.This seems to be less of - an issue with Darwin and FreeBSD.")) - (para "For information about building the database files, - see {section The Interface Translator}."))) - (defsection "Using Interface Directories" - (defsection "Overview" - (para "As distributed, the {code ccl:headers;} (for LinuxPPC) - directory is organized like:") - (code-block " - headers/ - headers/gl/ - headers/gl/C/ - headers/gl/C/populate.sh - headers/gl/constants.cdb - headers/gl/functions.cdb - headers/gl/records.cdb - headers/gl/objc-classes.cdb - headers/gl/objc-methods.cdb - headers/gl/types.cdb - headers/gnome/ - headers/gnome/C/ - headers/gnome/C/populate.sh - headers/gnome/constants.cdb - headers/gnome/functions.cdb - headers/gnome/records.cdb - headers/gnome/objc-classes.cdb - headers/gnome/objc-methods.cdb - headers/gnome/types.cdb - headers/gtk/ - headers/gtk/C/ - headers/gtk/C/populate.sh - headers/gtk/constants.cdb - headers/gtk/functions.cdb - headers/gtk/records.cdb - headers/gtk/objc-classes.cdb - headers/gtk/objc-methods.cdb - headers/gtk/types.cdb - headers/libc/ - headers/libc/C/ - headers/libc/C/populate.sh - headers/libc/constants.cdb - headers/libc/functions.cdb - headers/libc/records.cdb - headers/libc/objc-classes.cdb - headers/libc/objc-methods.cdb - headers/libc/types.cdb - ") - "e.g, as a set of parallel subdirectories, each with a - lowercase name and each of which contains a set of 6 database - files and a {code C} subdirectory which contains a shell script - used in the database creation process. - - As one might assume, the database files in each of these - subdirectories contain foreign type, constant, and function - definitions - as well as Objective-C class and method info -that - correspond (roughly) to the information contained in the - header files associated with a “-dev” package in a Linux - distribution. {code libc} corresponds pretty closely to the - interfaces associated with glibc/libc6 header files, {code gl} - corresponds to an openGL+GLUT development package, {code gtk} - and {code gnome} contain interface information from the GTK+1.2 and - GNOME libraries, respectively. - - For Darwin, the {code ccl:darwin-headers;} directory contains - a {code libc} subdirectory, whose contents roughly correspond to - those of {code /usr/include} under Darwin, as well as - subdirectories corresponding to the MacOSX Carbon and Cocoa - frameworks. - - To see the precise set of .h files used to generate the - database files in a given interface directory, consult the - corresponding {code populate.sh} shell script (in the interface - directory's {code C} subdirectory.) - - The intent is that this initial set can be augmented to - meet local needs, and that this can be done in a fairly - incremental fashion: one needn't have unrelated header files - installed in order to generate interface databases for a - package of interest. - - Hopefully, this scheme will also make it easier to - distribute patches and bug fixes. - - {CCL} maintains a list of directories; when looking - for a foreign type, constant, function, or record definition, - it'll consult the database files in each directory on that - list. Initially, the list contains an entry for the {code libc} - interface directory. {CCL} needs to be explicitly told to - look in other interface directories should it need to do - so.") - - (defsection "Creating new interface directories" - #:|This example refers to "ccl:headers;", which is - appropriate for LinuxPPC. The procedure's analogous under - Darwin, where the "ccl:darwin-headers;" directory would be - used instead. - - To create a new interface directory, "foo", and a set of - database files in that directory:| - (listing :number - (item #:|Create a subdirectory of "ccl:headers;" named - "foo".|) - (item #:|Create a subdirectory of "ccl:headers;foo;" named - "C".|) - (item #:|Create a file in "ccl:headers;foo;C;" named - "populate.sh". - -One way of accomplishing the above steps is:| - (code-block #:| - ? (close (open "ccl:headers;foo;C;populate.sh" :direction :output : - if-does-not-exist :create :if-exists :overwrite)) - |)) - (item #:|Edit the file created above, using the "populate.sh" - files in the distribution as guidelines. - -The file might wind up looking something like:| - (code-block "#/bin/sh - h-to-ffi.sh `foo-config -cflags` /usr/include/foo/foo.h"))) - (para "Refer to {section The Interface Translator} for - information about running the interface translator and .ffi - parser.") - (para #:|Assuming that all went well, there should now be .cdb - files in "ccl:headers;foo;". You can then do - | - (code-block " - ? (use-interface-dir :foo) - ") - " - whenever you need to - access the foreign type information in those database - files."))) - (defsection "Using Shared Libraries" - (defsection "Overview" - (para "{CCL} provides facilities to open and close shared - libraries.") - (para #:|"Opening" a shared library, which is done with | (ref (definition :function open-shared-library)) - ", maps the library's code and - data into {CCL}'s address space and makes its exported - symbols accessible to {CCL}.") - (para #:|"Closing" a shared library, which is done with | (ref (definition :function close-shared-library)) - ", unmaps the library's code - and and removes the library's symbols from the global - namespace.") - #:|A small number of shared libraries (including libc, - libm, libdl under Linux, and the "system" library under - Darwin) are opened by the lisp kernel and can't be - closed. - - {CCL} uses data structures of type - EXTERNAL-ENTRY-POINT to map a foreign function name (string) - to that foreign function's {emphasis current} - address. (A function's address may vary from session to - session as different versions of shared libraries may load at - different addresses; it may vary within a session for similar - reasons.) - - An EXTERNAL-ENTRY-POINT whose address is known is said - to be {emphasis resolved}. When an external entry - point is resolved, the shared library which defines that entry - point is noted; when a shared library is closed, the entry - points that it defines are made unresolved. An - EXTERNAL-ENTRY-POINT must be in the resolved state in order to - be FF-CALLed; calling an unresolved entry point causes a "last - chance" attempt to resolve it. Attempting to resolve an - entrypoint that was defined in a closed library will cause an - attempt to reopen that library. - - {CCL} keeps track of all libraries that have been - opened in a lisp session. When a saved application is first - started, an attempt is made to reopen all libraries that were - open when the image was saved, and an attempt is made to - resolve all entry points that had been referenced when the - image was saved. Either of these attempts can fail "quietly", - leaving some entry points in an unresolved state. - - Linux shared libraries can be referred to either by a - string which describes their full pathname or by their - {emphasis soname}, a shorter string that can be - defined when the library is created. The dynamic linker - mechanisms used in Linux make it possible (through a series of - filesystem links and other means) to refer to a library via - several names; the library's soname is often the most - appropriate identifier. - - so names are often less version-specific than other names - for libraries; a program that refers to a library by the name - "libc.so.6" is more portable than one which refers to - "libc-2.1.3.so" or to "libc-2.2.3.so", even though the latter - two names might each be platform-specific aliases of the - first. - - All of the global symbols described below are exported - from the CCL package.|) - (defsection "Limitations and known bugs" - (listing :bullet - (item "Don't get me started.") - (item "The underlying functionality has a poor notion of - dependency;it's not always possible to open libraries that - depend on unopened libraries, but it's possible to close - libraries on which other libraries depend. It - {emphasis may} be possible to generate - more explicit dependency information by parsing the output - of the Linux ldd and ldconfig programs."))) - (defsection ">Darwin Notes" - (para "Darwin shared libraries come in two (basic) flavors:") - (listing :bullet - (item #:|"dylibs" (which often have the extension".dylib") are - primarily intended to be linked against at compile/link - time. They can be loaded dynamically,{emphasis but can't - be unloaded}. Accordingly,OPEN-SHARED-LIBRARY - can be used to open a .dylib-style library;calling - CLOSE-SHARED-LIBRARY on the result of such a call produces - a warning, and has no other effect. It appears that (due - to an OS bug) attempts to open .dylib shared-libraries - that are already open can cause memory corruption unless - the full pathname of the .dylib file is specified on the - first and all subsequent calls.|) - (item #:|"bundles" are intended to serve as application - extensions; they can be opened multiple times (creating - multiple instances of the library!) and closed - properly.|)) - (para "Thanks to Michael Klingbeil for getting both kinds of - Darwin shared libraries working in {CCL}."))) - (defsection "The Interface Translator" - (defsection "Overview" - #:|{CCL} uses an interface translation system based on the FFIGEN - system, which is described at - {link http://www.ccs.neu.edu/home/lth/ffigen/ this page} - The interface translator makes - the constant, type, structure, and function definitions in a set of - C-language header files available to lisp code. - - The basic idea of the FFIGEN scheme is to use the C - compiler's frontend and parser to translate .h files into - semantically equivalent .ffi files, which represent the - definitions from the headers using a syntax based on - S-expressions. Lisp code can then concentrate on the .ffi - representation, without having to concern itself with the - semantics of header file inclusion or the arcana of C - parsing. - - The original FFIGEN system used a modified version of - the LCC C compiler to produce .ffi files. Since many OS - header files contain GCC-specific constructs, {CCL}'s - translation system uses a modified version of GCC (called, - somewhat confusingly, ffigen.) - - See {link http://trac.clozure.com/openmcl/wiki/BuildFFIGEN - here} for information on building and installing ffigen. - - - A component shell script called h-to-ffi.sh reads a - specified .h file (and optional preprocessor arguments) and writes - a (hopefully) equivalent .ffi file to standard output, calling - the ffigen program with appropriate arguments. - - For each interface directory (see FIXTHIS) - {emphasis subdir} distributed with {CCL}, a shell - script (distributed with {CCL} as - "ccl:headers;{emphasis subdir};C;populate.sh" - (or some other platform-specific headers directory) - calls h-to-ffi.sh on a large number of the header - files in /usr/include (or some other {emphasis system header - path}) and creates a parallel directory tree in - "ccl:headers;{emphasis subdir};C;{emphasis system};{emphasis header};{emphasis path};" - (or - "ccl:darwin-headers;{emphasis subdir};C;{emphasis system};{emphasis header};{emphasis path};", etc.), - populating that directory with .ffi files. - - A lisp function defined in "ccl:library;parse-ffi.lisp" - reads the .ffi files in a specified interface directory - {emphasis subdir} and generates new versions of the - databases (files with the extension .cdb). - - The CDB databases are used by the #$ and #_ reader - macros and are used in the expansion of RREF, RLET, and - related macros.|) - (defsection "Details: rebuilding the CDB databases, step by step" - (listing :number - (item #:|Ensure that the FFIGEN program is installed. See - the"README" file generated during the FFIGEN build process for - specific installation instructions.This example assumes - LinuxPPC; for other platforms, substitute the appropriate - headers directory. |) - (item #:|Edit the - "ccl:headers;{emphasis subdir};C;populate.sh"shell - script. When you're confident that the files - and preprocessor options match your environment, cd to - the"ccl:headers;{emphasis subdir};C;" directory - and invoke ./populate.sh. Repeat this step until you're - able to cleanly translate all files referenced in the shell - script.|) - (item - (para "Run {CCL}: - " - (code-block #:| - ? (require "PARSE-FFI") - PARSE-FFI - - ? (ccl::parse-standard-ffi-files :SUBDIR) - ;;; lots of output ... after a while, shiny new .cdb files should - ;;; appear in "ccl:headers;subdir;" - |)) - (para "It may be necessary to call CCL::PARSE-STANDARD-FFI-FILES - twice, to ensure that forward-references are resolved "))))) - (defsection "Case-sensitivity of foreign names in {CCL}" - (defsection "Overview" - "As of release 0.11, {CCL} addresses the fact that - foreign type, constant, record, field, and function nams are - case-sensitive and provides mechanisms to refer to these names - via lisp symbols. - - Previous versions of {CCL} have tried to ignore that - fact, under the belief that case conflicts were rare and that - many users (and implementors) would prefer not to deal with - case-related issues. The fact that some information in the - interface databases was incomplete or inaccessible because of - this policy made it clearer that the policy was untenable. I - can't claim that the approach described here is aesthetically - pleasing, but I can honestly say that it's less unpleasant - than other approaches that I'd thought of. I'd be interested - to hear alternate proposals. - - The issues described here have to do with how lisp - symbols are used to denote foreign functions, constants, - types, records, and fields. It doesn't affect how other lisp - objects are sometimes used to denote foreign objects. For - instance, the first argument to the EXTERNAL-CALL macros is - now and has always been a case-sensitive string.") - (defsection "Foreign constant and function names" - #:|The primary way of referring to foreign constant and - function names in {CCL} is via the #$ and #_ reader - macros. These reader macro functions each read a symbol into - the "OS" package, look up its constant or function definition - in the interface database, and assign the value of the - constant to the symbol or install a macroexpansion function on - the symbol. - - In order to observe case-sensitivity, the reader-macros - now read the symbol with (READTABLE-CASE :PRESERVE) in - effect. - - This means that it's necessary to type the foreign - constant or function name in correct case, but it isn't - necessary to use any special escaping constructs when writing - the variable name. For instance:| - (code-block #:| - (#_read fd buf n) ; refers to foreign symbol "read" - (#_READ fd buf n) ; refers to foreign symbol "READ", which may - ; not exist ... - #$o_rdonly ; Probably doesn't exist - #$O_RDONLY ; Exists on most platforms - |)) - (defsection "Foreign type, record, and field names" - #:|Constructs like RLET expect a foreign type or record - name to be denoted by a symbol (typically a keyword); RREF - (and PREF) expect an "accessor" form, typically a keyword - formed by concatenating a foreign type or record name with a - sequence of one or more foreign field names, separated by - dots. These names are interned by the reader as other lisp - symbols are, with an arbitrary value of READTABLE-CASE in - effect (typically :UPCASE.) It seems like it would be very - tedious to force users to manually escape (via vertical bar or - backslash syntax) all lowercase characters in symbols used to - specify foreign type, record, and field names (especially - given that many traditional POSIX structure, type, and field - names are entirely lowercase.) - - The approach taken by {CCL} is to allow the symbols - (keywords) used to denote foreign type, record, and field - names to contain angle brackets ({code <} and - {code >}). Such symbols are translated to - foreign names via the following set of conventions:| - (listing :bullet - (item "All instances of < and > in the symbol's pname - are balanced and don't nest.") - (item "Any alphabetic characters in the symbol's pname - that aren't enclosed in angle brackets are treated as - lower-case,regardless of the value of READTABLE-CASE and - regardless of the case in which they were written.") - (item "Alphabetic characters that appear within angle - brackets are mapped to upper-case, again regardless of how - they were written or interned.")) - #:|There may be many ways of "escaping" (with angle - brackets) sequences of upper-case and non-lower-case - characters in a symbol used to denote a foreign name. When - translating in the other direction, {CCL} always escapes the - longest sequence that starts with an upper-case character and - doesn't contain a lower-case character. - - It's often preferable to use this canonical form of a - foreign type name. - - The accessor forms used by PREF/RREF should be viewed as - a series of foreign type/record and field names; upper-case - sequences in the component names should be escaped with angle - brackets, but those sequences shouldn't span components. (More - simply, the separating dots shouldn't be enclosed, even if - both surrounding characters need to be.) - - Older POSIX code tends to use lower-case exclusively for - type, record, and field names; there are only a few cases in - the {CCL} sources where mixed-case names need to be - escaped.|) - (defsection "Examples" - (code-block #:| - ;;; Allocate a record of type "window". - (rlet ((w :window)) ...) - ;;; Allocate a record of type "Window", which is probably a - ;;; different type - (rlet ((w :indow)) ...) - ;;; This is equivalent to the last example - (rlet ((w :INDOW))) - |))) - (defsection "Reading Foreign Names" - "{CCL} - provides several reader macros to make it more convenient to - handle foreign type, function, variable, and constant - names. Each of these reader macros reads symbols preserving the - case of the source text, and selects an appropriate package in - which to intern the resulting symbol. These reader macros are - especially useful when your Lisp code interacts extensively with - a foreign library-for example, when using Mac OS X's Cocoa - frameworks. - - These reader macros include {code #_} to read foreign function - names, {code #&} to read foreign variable names, {code #$} - to read foreign constant names, {code #/} to - read the names of foreign Objective-C methods, and {code #>} to read - keywords that can be used as the names of types, records, and - accessors. - - All of these reader macros preserve the case of the text - that they read; beyond that similarity, each performs some - additional work, unique to each reader macro, to create symbols - suitable for a particular use. For example, the function, - variable, and constant reader macros intern the resulting symbol - in the {code os} package of the running platform, but the reader - macro for Objective-C method names interns symbols in the - {code nextstep-functions} package. - - You are likely to see these reader macros used extensively - in Lisp code that works with foreign libraries; for example, - {CCL} IDE code, which defines numerous Objective-C classes - and methods, uses these reader macros extensively. - - For more detailed descriptions of each of these reader - macros, see the Foreign-Function-Interface Dictionary - section.") - - (defsection "Tutorial: Using Basic Calls and Types" - "This tutorial is meant to cover the basics of {CCL} for - calling external C functions and passing data back and forth. - These basics will provide the foundation for more advanced - techniques which will allow access to the various external - libraries and toolkits. - - The first step is to start with a simple C dynamic library - in order to actually observe what is actually passing between - {CCL} and C. So, some C code is in order: - - Create the file typetest.c, and put the following code - into it:" - (code-block #:| -#include - -void -void_void_test(void) -{lbrace} - printf("Entered %s:\\n", __FUNCTION__); - printf("Exited %s:\\n", __FUNCTION__); - fflush(stdout); -{rbrace} - -signed char -sc_sc_test(signed char data) -{lbrace} - printf("Entered %s:\\n", __FUNCTION__); - printf("Data In: %d\\n", (signed int)data); - printf("Exited %s:\\n", __FUNCTION__); - fflush(stdout); - return data; -{rbrace} - -unsigned char -uc_uc_test(unsigned char data) -{lbrace} - printf("Entered %s:\\n", __FUNCTION__); - printf("Data In: %d\\n", (signed int)data); - printf("Exited %s:\\n", __FUNCTION__); - fflush(stdout); - return data; -{rbrace} - |) - "This defines three functions. If you're familiar with C, - notice that there's no {code main()}, because we're - just building a library, not an executable. - - The function {code void_void_test()} doesn't - take any parameters, and doesn't return anything, but it prints - two lines to let us know it was called. - {code sc_sc_test()} takes a signed char as a - parameter, prints it, and returns it. - {code uc_uc_test()} does the same thing, but with an - unsigned char. Their purpose is just to prove to us that we - really can call C functions, pass them values, and get values - back from them. - - This code is compiled into a dynamic library on OS X - 10.3.4 with the command:" - (code-block " - - gcc -dynamiclib -Wall -o libtypetest.dylib typetest.c \\ - -install_name ./libtypetest.dylib - ") - (block "Tip" - (para #:|Users of 64-bit platforms may need to pass options such - as "-m64" to gcc, may need to give the output library a different - extension (such as ".so"), and may need to user slightly different - values for other options in order to create an equivalent test - library.|)) - #:|The -dynamiclib tells gcc that we will be compiling this - into a dynamic library and not an executable binary program. - The output filename is "libtypetest.dylib". Notice that we - chose a name which follows the normal OS X convention, being in - the form "libXXXXX.dylib", so that other programs can link to - the library. {CCL} doesn't need it to be this way, but it is - a good idea to adhere to existing conventions. - - The -install_name flag is primarily used when building OS - X "bundles". In this case, we are not using it, so we put a - placeholder into it, "./libtypetest.dylib". If we wanted to use - typetest in a bundle, the -install_name argument would be a - relative path from some "current" directory. - - After creating this library, the first step is to tell - {CCL} to open the dynamic library. This is done by calling - .| - (code-block #:| - - Welcome to {CCL} Version (Beta: Darwin) 0.14.2-040506! - - ? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib") - # - |) - #:|You should use an absolute path here; using a relative - one, such as just "libtypetest.dylib", would appear to work, but - there are subtle problems which occur after reloading it. See - the Darwin notes on for details. It would be a bad idea anyway, - because software should never rely on its starting directory - being anything in particular. - - This command returns a reference to the opened shared library, and - {CCL} also adds one to the global variable - {code ccl::*shared-libraries*}:| - (code-block " - - ? ccl::*shared-libraries* - (# - #) - ") - (para "Before we call anything, let's check that the individual - functions can actually be found by the system. We don't have to - do this, but it helps to know how to find out whether this is - the problem, when something goes wrong. We use " - (ref (definition :macro external-call)) ":") - (code-block #:| - - ? (external "_void_void_test") - # - - ? (external "_sc_sc_test") - # - - ? (external "_uc_uc_test") - # - |) - #:|Notice that the actual function names have been "mangled" - by the C linker. The first function was named "void_void_test" - in typetest.c, but in libtypetest.dylib, it has an underscore (a - "_" symbol) before it: "_void_void_test". So, this is the name - which you have to use. The mangling - the way the name is - changed - may be different for other operating systems or other - versions, so you need to "just know" how it's done... - - Also, pay particular attention to the fact that a - hexadecimal value appears in the EXTERNAL-ENTRY-POINT. - (#x000CFDF8, for example - but what it is doesn't matter.) - These hex numbers mean that the function can be dereferenced. - Functions which aren't found will not have a hex number. For - example:| - (code-block #:| - - ? (external "functiondoesnotexist") - # - |) - #:|The "unresolved" tells us that {CCL} wasn't able to find this - function, which means you would get an error, "Can't resolve foreign - symbol," if you tried to call it. - - These external function references also are stored in a - hash table which is accessible through a global variable, - {code ccl::*eeps*}. - - At this point, we are ready to try our first external - function call:| - (code-block #:| - - ? (external-call "_void_void_test" :void) - Entered void_void_test: - Exited void_void_test: - NIL - |) - #:|We used , which is is the normal mechanism for accessing - externally linked code. The "_void_void_test" is the mangled - name of the external function. The :void refers to the return - type of the function. - - The next step is to try passing a value to C, and getting one - back:| - (code-block #:| - - ? (external-call "_sc_sc_test" :signed-byte -128 :signed-byte) - Entered sc_sc_test: - Data In: -128 - Exited sc_sc_test: - -128 - |) - "The first :signed-byte gives the type of the first - argument, and then -128 gives the value to pass for it. The - second :signed-byte gives the return type. The return type is - always given by the last argument to . - - Everything looks good. Now, let's try a number outside - the range which fits in one byte:" - (code-block #:| - - ? (external-call "_sc_sc_test" :signed-byte -567 :signed-byte) - Entered sc_sc_test: - Data In: -55 - Exited sc_sc_test: - -55 - |) - (para "Hmmmm. A little odd. Let's look at the unsigned stuff to - see how it reacts:") - (code-block #:| - - ? (external-call "_uc_uc_test" :unsigned-byte 255 :unsigned-byte) - Entered uc_uc_test: - Data In: 255 - Exited uc_uc_test: - 255 - |) - (para "That looks okay. Now, let's go outside the valid range again:") - (code-block #:| - - ? (external-call "_uc_uc_test" :unsigned-byte 567 :unsigned-byte) - Entered uc_uc_test: - Data In: 55 - Exited uc_uc_test: - 55 - - ? (external-call "_uc_uc_test" :unsigned-byte -567 :unsigned-byte) - Entered uc_uc_test: - Data In: 201 - Exited uc_uc_test: - 201 - |) - #:|Since a signed byte can only hold values from -128 through 127, and - an unsigned one can only hold values from 0 through 255, any number - outside that range gets "clipped": only the low eight bits of it - are used. - - What is important to remember is that {emphasis external - function calls have - very few safety checks.} - Data outside the valid range for its type will silently do - very strange things; pointers outside the valid range can very well - crash the system. - - That's it for our first example library. If you're still - following along, let's add some more C code to look at the rest - of the primitive types. Then we'll need to recompile the - dynamic library, load it again, and then we can see what - happens. - -Add the following code to typetest.c:| - (code-block #:| -int -si_si_test(int data) -{lbrace} - printf("Entered %s:\\n", __FUNCTION__); - printf("Data In: %d\\n", data); - printf("Exited %s:\\n", __FUNCTION__); - fflush(stdout); - return data; -{rbrace} - -long -sl_sl_test(long data) -{lbrace} - printf("Entered %s:\\n", __FUNCTION__); - printf("Data In: %ld\\n", data); - printf("Exited %s:\\n", __FUNCTION__); - fflush(stdout); - return data; -{rbrace} - -long long -sll_sll_test(long long data) -{lbrace} - printf("Entered %s:\\n", __FUNCTION__); - printf("Data In: %lld\\n", data); - printf("Exited %s:\\n", __FUNCTION__); - fflush(stdout); - return data; -{rbrace} - -float -f_f_test(float data) -{lbrace} - printf("Entered %s:\\n", __FUNCTION__); - printf("Data In: %e\\n", data); - printf("Exited %s:\\n", __FUNCTION__); - fflush(stdout); - return data; -{rbrace} - -double -d_d_test(double data) -{lbrace} - printf("Entered %s:\\n", __FUNCTION__); - printf("Data In: %e\\n", data); - printf("Exited %s:\\n", __FUNCTION__); - fflush(stdout); - return data; -{rbrace} - |) - (para "The command line to compile the dynamic library is the same as before:") - (code-block " - - gcc -dynamiclib -Wall -o libtypetest.dylib typetest.c \\ - -install_name ./libtypetest.dylib - ") - "Now, restart {CCL}. This step is required because - {CCL} cannot close and reload a dynamic library on OS - X. - -Have you restarted? Okay, try out the new code:" - (code-block #:| - - Welcome to {CCL} Version (Beta: Darwin) 0.14.2-040506! - - ? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib") - # - - ? (external-call "_si_si_test" :signed-fullword -178965 :signed-fullword) - Entered si_si_test: - Data In: -178965 - Exited si_si_test: - -178965 - - ? ;; long is the same size as int on 32-bit machines. - (external-call "_sl_sl_test" :signed-fullword -178965 :signed-fullword) - Entered sl_sl_test: - Data In: -178965 - Exited sl_sl_test: - -178965 - - ? (external-call "_sll_sll_test" - :signed-doubleword -973891578912 :signed-doubleword) - Entered sll_sll_test: - Data In: -973891578912 - Exited sll_sll_test: - -973891578912 - |) - (para "Okay, everything seems to be acting as expected. However, - just to remind you that most of this stuff has no safety net, - here's what happens if somebody mistakes - {code sl_sl_test()} for - {code sll_sll_test()}, thinking that a long is - actually a doubleword:") - (code-block #:| - - ? (external-call "_sl_sl_test" - :signed-doubleword -973891578912 :signed-doubleword) - Entered sl_sl_test: - Data In: -227 - Exited sl_sl_test: - -974957576192 - |) - "Ouch. The C function changes the value with no warning - that something is wrong. Even worse, it manages to pass the - original value back to {CCL}, which hides the fact that - something is wrong. - - Finally, let's take a look at doing this with - floating-point numbers." - (code-block #:| - - Welcome to {CCL} Version (Beta: Darwin) 0.14.2-040506! - - ? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib") - # - - ? (external-call "_f_f_test" :single-float -1.256791e+11 :single-float) - Entered f_f_test: - Data In: -1.256791e+11 - Exited f_f_test: - -1.256791E+11 - - ? (external-call "_d_d_test" :double-float -1.256791d+290 :double-float) - Entered d_d_test: - Data In: -1.256791e+290 - Exited d_d_test: - -1.256791D+290 - |) - #:|Notice that the number ends with "...e+11" for the single-float, - and "...d+290" for the - double-float. Lisp has both of these float types itself, and the - d instead of the e is how you specify which to create. If - you tried to pass :double-float 1.0e2 to external-call, Lisp would - be nice enough to notice and give you a type error. Don't get the - :double-float wrong, though, because then there's no protection. - - Congratulations! You now know how to call external C functions from - within {CCL}, and pass numbers back and forth. Now that the basic - mechanics of calling and passing work, the next step is to examine how - to pass more complex data structures around.| - (defsection "Acknowledgement" - (para "This chapter was generously contributed by Andrew - P. Lentvorski Jr."))) - (defsection "Tutorial: Allocating Foreign Data on the Lisp Heap " - #:|Not every foreign function is so marvelously easy to use - as the ones we saw in the last section. Some functions require - you to allocate a C struct, fill it with your own - information, and pass in a pointer to that struct. Some of them - require you to allocate an empty struct that they will fill in - so that you can read the information out of it. - - There are generally two ways to allocate foreign data. The - first way is to allocate it on the stack; the RLET macro is one way to do this. - This is analogous to using automatic variables in C. In the - jargon of Common Lisp, data allocated this way is said to have - dynamic extent. - - The other way to heap-allocate the foreign data. This is - analogous to calling malloc in C. Again in the jargon of Common - Lisp, heap-allocated data is said to have indefinite extent. If a - function heap-allocates some data, that data remains valid even - after the function itself exits. This is useful for data which - may need to be passed between multiple C calls or multiple - threads. Also, some data may be too large to copy multiple times - or may be too large to allocate on the stack. - - The big disadvantage to allocating data on the heap is - that it must be explicitly deallocated-you need to "free" it - when you're done with it. Normal Lisp objects, even those with indefinite - extent, are deallocated by the garbage collector when it can prove - that they're no longer referenced. Foreign data, though, is outside the - GC's ken: it has no way to know whether a blob of foreign data is still - referenced by foreign code or not. It is thus up to the programmer - to manage it manually, just as one - does in C with malloc and free. - - - What that means is that, if you allocate something and - then lose track of the pointer to it, there's no way to ever - free that memory. That's what's called a memory leak, and if - your program leaks enough memory it will eventually use up all - of it! So, you need to be careful to not lose your - pointers. - - That disadvantage, though, is also an advantage for using - foreign functions. Since the garbage collector doesn't know - about this memory, it will never move it around. External C - code needs this, because it doesn't know how to follow it to - where it moved, the way that Lisp code does. If you allocate - data manually, you can pass it to foreign code and know that no - matter what that code needs to do with it, it will be able to, - until you deallocate it. Of course, you'd better be sure it's - done before you do. Otherwise, your program will be unstable - and might crash sometime in the future, and you'll have trouble - figuring out what caused the trouble, because there won't be - anything pointing back and saying "you deallocated this too - soon." - -And, so, on to the code... - - As in the last tutorial, our first step - is to create a local dynamic library in order to help show - what is actually going on between {CCL} and C. So, create the file - ptrtest.c, with the following code:| - (code-block " -#include - -void reverse_int_array(int * data, unsigned int dataobjs) -{lbrace} - int i, t; - - for(i=0; i - - ? a - #(1396 2578 97862649) - - ? ap - # - ") - "It's important to realize that the contents of the - {code ivector} we've just created haven't been - initialized, so their values are unpredictable, and you should - be sure not to read from them before you set them, to avoid - confusing results. - - At this point, {code a} references an object - which works just like a normal array. You can refer to any item - of it with the standard {code aref} function, and - set them by combining that with {code setf}. As - noted above, the {code ivector}'s contents haven't - been initialized, so that's the next order of business:" - (code-block " - ? a - #(1396 2578 97862649) - - ? (aref a 2) - 97862649 - - ? (setf (aref a 0) 3) - 3 - - ? (setf (aref a 1) 4) - 4 - - ? (setf (aref a 2) 5) - 5 - - ? a - #(3 4 5) - ") - (para "In addition, the {code macptr} allows direct - access to the same memory:") - (code-block " - ? (setq *byte-length-of-long* 4) - 4 - - ? (%get-signed-long ap (* 2 *byte-length-of-long*)) - 5 - - ? (%get-signed-long ap (* 0 *byte-length-of-long*)) - 3 - - ? (setf (%get-signed-long ap (* 0 *byte-length-of-long*)) 6) - 6 - - ? (setf (%get-signed-long ap (* 2 *byte-length-of-long*)) 7) - 7 - - ? ;; Show that a actually got changed through ap - a - #(6 4 7) - ") - (para "So far, there is nothing about this object that could not - be done much better with standard Lisp. However, the - {code macptr} can be used to pass this chunk of - memory off to a C function. Let's use the C code to reverse the - elements in the array:") - (code-block #:| - ? ;; Insert the full path to your copy of libptrtest.dylib - (open-shared-library "/Users/andrewl/openmcl/openmcl/gtk/libptrtest.dylib") - # - - ? a - #(6 4 7) - - ? ap - # - - ? (external-call "_reverse_int_array" :address ap :unsigned-int (length a) :address) - # - - ? a - #(7 4 6) - - ? ap - # - |) - "The array gets passed correctly to the C function, - {code reverse_int_array}. The C function reverses - the contents of the array in-place; that is, it doesn't make a - new array, just keeps the same one and reverses what's in it. - Finally, the C function passes control back to {CCL}. Since - the allocated array memory has been directly modified, {CCL} - reflects those changes directly in the array as well. - - There is one final bit of housekeeping to deal with. - Before moving on, the memory needs to be deallocated:" - (code-block " - ? (dispose-heap-ivector a ap) - NIL - ") - #:|The {code dispose-heap-ivector} macro actually - deallocates the ivector, releasing its memory into the heap for - something else to use. Both {code a} and {code ap} - now have undefined values. - - - When do you call {code dispose-heap-ivector}? - Anytime after you know the ivector will never be used again, but - no sooner. If you have a lot of ivectors, say, in a hash table, - you need to make sure that when whatever you were doing with the - hash table is done, those ivectors all get freed. Unless - there's still something somewhere else which refers to them, of - course! Exactly what strategy to take depends on the situation, - so just try to keep things simple unless you know better. - - The simplest situation is when you have things set up so - that a Lisp object "encapsulates" a pointer to foreign data, - taking care of all the details of using it. In this case, you - don't want those two things to have different lifetimes: You - want to make sure your Lisp object exists as long as the foreign - data does, and no longer; and you want to make sure the foreign - data doesn't get deallocated while your Lisp object still refers - to it. - - If you're willing to accept a few limitations, you can - make this easy. First, you can't let foreign code keep a - permanent pointer to the memory; it has to always finish what - it's doing, then return, and not refer to that memory again. - Second, you can't let any Lisp code that isn't part of your - encapsulating "wrapper" refer to the pointer directly. Third, - nothing, either foreign code or Lisp code, should explicitly - deallocate the memory. - - If you can make sure all of these are true, you can at - least ensure that the foreign pointer is deallocated when the - encapsulating object is about to become garbage, by using - {CCL}'s nonstandard "termination" mechanism, which is - essentially the same as what Java and other languages call - "finalization". - - Termination is a way of asking the garbage collector to - let you know when it's about to destroy an object which isn't - used anymore. Before destroying the object, it calls a function - which you write, called a terminator. - - So, you can use termination to find out when a particular - {code macptr} is about to become garbage. That's - not quite as helpful as it might seem: It's not exactly the same - thing as knowing that the block of memory it points to is - unreferenced. For example, there could be another - {code macptr} somewhere to the same block; or, if - it's a struct, there could be a {code macptr} to one - of its fields. Most problematically, if the address of that - memory has been passed to foreign code, it's sometimes hard to - know whether that code has kept the pointer. Most foreign - functions don't, but it's not hard to think of - exceptions. - -You can use code such as this to make all this happen:| - (code-block " - (defclass wrapper (whatever) - ((element-type :initarg :element-type) - (element-count :initarg :element-count) - (ivector) - (macptr))) - - (defmethod initialize-instance ((wrapper wrapper) {code &rest} initargs) - (declare (ignore initargs)) - (call-next-method) - (ccl:terminate-when-unreachable wrapper) - (with-slots (ivector macptr element-type element-count) wrapper - (multiple-value-bind (new-ivector new-macptr) - (make-heap-ivector element-count element-type) - (setq ivector new-ivector - macptr new-macptr)))) - - (defmethod ccl:terminate ((wrapper wrapper)) - (with-slots (ivector macptr) wrapper - (when ivector - (dispose-heap-ivector ivector macptr) - (setq ivector nil - macptr nil)))) - ") - "The {code ccl:terminate} method will be called - on some arbitrary thread sometime (hopefully soon) after the GC - has decided that there are no strong references to an object - which has been the argument of a - {code ccl:terminate-when-unreachable} call. - - If it makes sense to say that the foreign object should - live as long as there's Lisp code that references it (through - the encapsulating object) and no longer, this is one way of doing - that. - - Now we've covered passing basic types back and forth with - C, and we've done the same with pointers. You may think this is - all... but we've only done pointers to basic types. Join us - next time for pointers... to pointers." - (defsection "Acknowledgement" - (para "Much of this chapter was generously contributed by - Andrew P. Lentvorski Jr."))) - - (defsection "The Foreign-Function-Interface Dictionary" - (definition (:reader-macro "#_") "#_" nil - (defsection "Description" - (para #:|Reads a symbol from the current input stream, with *PACKAGE* - bound to the "OS" package and with readtable-case preserved.|) - (para "Does a lookup on that symbol in " (ref (section "The Interface Database") "the {CCL} interface database") - ", signalling an error if no foreign function - information can be found for the symbol in any active " - (ref (section "Using Interface Directories") "interface directory") ".") - #:|Notes the foreign function information, including the foreign - function's return type, the number and type of the foreign - function's required arguments, and an indication of whether or - not the function accepts additional arguments (via e.g., the - "varargs" mechanism in C). - - Defines a macroexpansion function on the symbol, which expand - macro calls involving the symbol into EXTERNAL-CALL forms where - foreign argument type specifiers for required arguments and the - return value specifer are provided from the information in the - database. - -Returns the symbol. - - The effect of these steps is that it's possible to call - foreign functions that take fixed numbers of arguments by simply - providing argument values, as in:| - (code-block "(#_isatty fd) - (#_read fd buf n)") - (para "and to call foreign functions that take variable numbers of - arguments by specifying the types of non-required args, as in:") - (code-block #:|(with-cstrs ((format-string "the answer is: %d")) - (#_printf format-string :int answer))|) - (para "You can query whether a given name is defined in the - interface databases by appending the '?' character to the reader - macro; for example:") - (code-block " - CL-USER> #_?printf - T - CL-USER> #_?foo - NIL - "))) - (definition (:reader-macro "#&") "#&" nil - (defsection "Description" - #:|In {CCL} 1.2 and later, the #& reader macro can be used to - access foreign variables; this functionality depends on the presence of - "vars.cdb" files in the interface database. The current behavior - of the #& reader macro is to: - - Read a symbol from the current input stream, with *PACKAGE* - bound to the "OS" package and with readtable-case preserved. - - Use that symbol's pname to access the {CCL} interface - database, signalling an error if no appropriate foreign variable - information can be found with that name in any active interface - directory. - - Use type information recorded in the database to construct a - form which can be used to access the foreign variable, and return - that form. - - Please note that the set of foreign variables declared in header files - may or may not match the set of foreign variables exported from - libraries (we're generally talking about C and Unix here ...). When - they do match, the form constructed by the #& reader macro manages the - details of resolving and tracking changes to the foreign variable's - address. - - Future extensions (via prefix arguments to the reader macro) may - offer additional behavior; it might be convenient (for instance) to be - able to access the address of a foreign variable without dereferencing - that address. - - Foreign variables in C code tend to be platform- and - package-specific (the canonical example - "errno" - is typically - not a variable when threads are involved. ) - -In LinuxPPC, | - (code-block "? #&stderr") - #:|returns a pointer to the stdio error stream ("stderr" is a - macro under OSX/Darwin). - -On both LinuxPPC and DarwinPPC, | - (code-block "? #&sys_errlist") - "returns a pointer to a C array of C error message strings. - - You can query whether a given name is defined in the - interface databases by appending the '?' character to the reader - macro; for example:" - (code-block " - CL-USER> #&?sys_errlist - T - CL-USER> #&?foo - NIL - "))) - (definition (:reader-macro "#$") "#$" nil - (defsection "Description" - #:|In {CCL} 0.14.2 and later, the #? reader macro can be used - to access foreign constants; this functionality depends on the - presence of "constants.cdb" files in the interface - database. The current behavior of the #$ reader macro is - to: - - Read a symbol from the current input stream, with - *PACKAGE* bound to the "OS" package and with - readtable-case preserved. - - Use that symbol's pname to access the {CCL} interface - database, signalling an error if no appropriate foreign constant - information can be found with that name in any active interface - directory. - - Use type information recorded in the database to construct a - form which can be used to access the foreign constant, and return - that form. - - Please note that the set of foreign constants declared in - header files may or may not match the set of foreign constants - exported from libraries. When they do match, the form - constructed by the #$ reader macro manages the details of - resolving and tracking changes to the foreign constant's - address. - - You can query whether a given name is defined in the - interface databases by appending the '?' character to the reader - macro; for example:| - (code-block " - CL-USER> #$?SO_KEEPALIVE - T - CL-USER> #$?foo - NIL - "))) - (definition (:reader-macro "#/") "#/" nil - (defsection "Description" - #:|In {CCL} 1.2 and later, the #/ reader macro can be used to - access foreign functions on the Darwin platform. The current - behavior of the #/ reader macro is to: - - Read a symbol from the current input stream, with - *PACKAGE* bound to the "NEXTSTEP-FUNCTIONS" package, with - readtable-case preserved, and with any colons included. - - Do limited sanity-checking on the resulting symbol; for - example, any name that contains at least one colon is required - also to end with a colon, to conform to Objective-C - method-naming conventions. - - Export the resulting symbol from the "NEXTSTEP-FUNCTIONS" - package and return it. - - For example, reading "#/alloc" interns and returns - NEXTSTEP-FUNCTIONS:\|alloc\|. Reading "#/initWithFrame:" interns - and returns NEXTSTEP-FUNCTIONS:\|initWithFrame:\|. - - A symbol read using this macro can be used as an operand - in most places where an Objective-C message name can be used, such as - in the (OBJ:@SELECTOR ...) construct. - - Please note: the reader macro is not rigorous about - enforcing Objective-C method-naming conventions. Despite the - simple checking done by the reader macro, it may still be - possible to use it to construct invalid names. - - The act of interning a new symbol in the - NEXTSTEP-FUNCTIONS package triggers an interface database lookup - of Objective-C methods with the corresponding message name. If any - such information is found, a special type of dispatching - function is created and initialized and the new symbol is given - the newly-created dispatching function as its function - definition. - - The dispatching knows how to call declared Objective-C methods - defined on the message. In many cases, all methods have the same - foreign type signature, and the dispatching function merely - passes any arguments that it receives to a function that does an - Objective-C message send with the indicated foreign argument and return - types. In other cases, where different Objective-C messages have - different type signatures, the dispatching function tries to - choose a function that handles the right type signature based on - the class of the dispatching function's first argument. - - If new information about Objective-C methods is introduced - (e.g., by using additional interface files or as Objective-C - methods are defined from lisp), the dispatch function is - reinitialized to recognize newly-introduced foreign type - signatures. - - The argument and result coercion that the bridge has - traditionally supported is supported by the new mechanism (e.g., - : arguments can be specified as lisp booleans and : - results are returned as lisp boolean values, and an argument - value of NIL is coerced to a null pointer if the corresponding - argument type is :ID. - - Some Objective-C methods accept variable numbers of - arguments; the foreign types of non-required arguments are - determined by the lisp types of those arguments (e.g., integers - are passed as integers, floats as floats, pointers as pointers, - record types by reference.) - -Examples:| - (code-block #:| - ;;; #/alloc is a known message. - ? #'#/alloc - # - ;;; Sadly, #/foo is not ... - ? #'#/foo - > Error: Undefined function: NEXTSTEP-FUNCTIONS:\|foo\| - - ;;; We can send an "init" message to a newly-allocated instance of - ;;; "NSObject" by: - - (send (send ns:ns-object 'alloc) 'init) - - ;;; or by - - (#/init (#/alloc ns:ns-object)) - |) - (para #:|Objective-C methods that "return" structures return them - as garbage-collectable pointers when called via dispatch - functions. For example, if "my-window" is an NS:NS-WINDOW - instance, then|) - (code-block " - (#/frame my-window) - ") - (para "returns a garbage-collectable pointer to a structure that - describes that window's frame rectangle. This convention means - that there's no need to use SLET or special structure-returning - message send syntax; keep in mind, though, that #_malloc, - #_free, and the GC are all involved in the creation and eventual - destruction of structure-typed return values. In some programs - these operations may have an impact on performance."))) - - (definition (:reader-macro "#>") "#>" nil - (defsection "Description" - (para "In {CCL} 1.2 and later, the #> reader macro reads - the following text as a keyword, preserving the case of the - text. For example:") - (code-block " - CL-USER> #>FooBar - :OOAR - ") - (para "The resulting keyword can be used as the name of foreign - types, records, and accessors."))) - (definition (:function close-shared-library) "close-shared-library library {code &key} completely" - "Stops using a shared library, informing the operating - system that it can be unloaded if appropriate." - (defsection "Values" - (listing :definition - (item "{param library}" ccldoc::=> "either an object of type SHLIB, or a string which - designates one by its so-name.") - (item "{param completely}" ccldoc::=> "a boolean. The default is T."))) - (defsection "Description" - (para "If {param completely} is T, sets the - reference count of {param library} to 0. Otherwise, - decrements it by 1. In either case, if the reference count - becomes 0, {function close-shared-library} - frees all memory resources consumed {param library} - and - causes any EXTERNAL-ENTRY-POINTs known to be defined by it to - become unresolved."))) - - (definition (:macro defcallback) - "defcallback name ({lbrace}arg-type-specifier var{rbrace}* {code &optional} result-type-specifier) {code &body} body" - nil - (para "Proclaims {param name} - to be a special variable; sets its value to a - MACPTR which, when called by foreign code, calls a lisp function - which expects foreign arguments of the specified types and which - returns a foreign value of the specified result type. Any argument - variables which correspond to foreign arguments of type :ADDRESS - are bound to stack-allocated MACPTRs. - - If {param name} - is already a callback function pointer, its value is - not changed; instead, it's arranged - that an - updated version of the lisp callback function will be called. - This feature allows for callback functions to be redefined - incrementally, just like Lisp functions are. - - {function defcallback} - returns the callback pointer, e.g., the - value of {param name}.") - (defsection "Values" - (listing :definition - (item "{param name}" ccldoc::=> "A symbol which can be made into a special variable") - (item "{param arg-type-specifer}" ccldoc::=> "One of the foreign argument-type keywords, - described above, or an equivalent " - (ref (section "Specifying And Using Foreign Types") "foreign type specifier") ". In addition, if the keyword - :WITHOUT-INTERRUPTS is specified, the callback will be - executed with lisp interrupts disabled if the - corresponding var is non-NIL. If :WITHOUT-INTERRUPTS - is specified more than once, the rightmost instance - wins.") - (item "{param var}" ccldoc::=> "A symbol (lisp variable), which will be bound to a - value of the specified type.") - (item "{param body}" ccldoc::=> "A sequence of lisp forms, which should return a value - which can be coerced to the specified result-type.")))) - - (definition (:macro def-foreign-type) "def-foreign-type name foreign-type-spec" nil - "If name is non-{code nil}, defines {param name} to be an alias - for the foreign type specified by {param foreign-type-spec}. If - {param foreign-type-spec} is a named structure or union type, - additionally defines that structure or union type. - - If name is {code nil}, {param foreign-type-spec} must be a - named foreign struct or union definition, in which case the - foreign structure or union definition is put in effect. - - Note that there are two separate namespaces for foreign type - names: one for the names of ordinary types and one for the - names of structs and unions. Which one {param name} refers to - depends on {param foreign-type-spec} in the obvious manner." - (defsection "Values" - (listing :definition - (item "{param name}" ccldoc::=> "NIL or a keyword; the keyword may contain - " - (ref (section "Case-sensitivity of foreign names in {CCL}") "escaping constructs") ".") - (item "{param foreign-type-spec}" ccldoc::=> "A foreign type specifier, whose syntax is (loosely) - defined above.")))) - - (definition (:macro external) "external name" "Resolves a reference to an external symbol which - is defined in a shared library." - (defsection "Values" - (listing :definition - (item "{param name}" ccldoc::=> " - a simple-string which names an external symbol. - Case-sensitive. - ") - (item "{param entry}" ccldoc::=> " - an object of type EXTERNAL-ENTRY-POINT which maintains - the address of the foreign symbol named by - {param name}. - "))) - (defsection "Description" - #:|If there is already an EXTERNAL-ENTRY-POINT for - the symbol named by {param name}, finds it and - returns it. If not, creates one and returns it. - - Tries to resolve the entry point to a memory address, - and identify the containing library. - - Be aware that under Darwin, external functions which - are callable from C have underscores prepended to their names, - as in "_fopen".|)) - - (definition (:macro external-call) - "external-call name {lbrace}arg-type-specifier arg{rbrace}* {code &optional} result-type-specifier" nil - (para "Calls the foreign function at the address obtained by - resolving the external-entry-point associated with name, passing - the values of each arg as a foreign argument of type indicated by - the corresponding arg-type-specifier. Returns the foreign function - result (coerced to a Lisp object of type indicated by - result-type-specifier), or NIL if result-type-specifer is :VOID or - NIL") - (defsection "Values" - (listing :definition - (item "{param name}" ccldoc::=> "A lisp string. See external, above.") - (item "{param arg-type-specifer}" ccldoc::=> "One of the foreign argument-type keywords, described - above, or an equivalent " - (ref (section "Specifying And Using Foreign Types") "foreign type specifier") ".") - (item "{param arg}" ccldoc::=> "A lisp value of type indicated by the corresponding - arg-type-specifier") - (item "{param result-type-specifier}" ccldoc::=> "One of the foreign argument-type keywords, described - above, or an equivalent " - (ref (section "Specifying And Using Foreign Types") "foreign type specifier") ".")))) - - (definition (:function %ff-call) - "%ff-call entrypoint {lbrace}arg-type-keyword arg{rbrace}* {code &optional} result-type-keyword" nil - (para "Calls the foreign function at address entrypoint passing the - values of each arg as a foreign argument of type indicated by the - corresponding arg-type-keyword. Returns the foreign function - result (coerced to a Lisp object of type indicated by - result-type-keyword), or NIL if result-type-keyword is :VOID or - NIL") - (defsection "Values" - (listing :definition - (item "{param entrypoint}" ccldoc::=> "A fixnum or MACPTR") - (item "{param arg-type-keyword}" ccldoc::=> "One of the foreign argument-type keywords, described - above") - (item "{param arg}" ccldoc::=> "A lisp value of type indicated by the corresponding - arg-type-keyword") - (item "{param result-type-keyword}" ccldoc::=> "One of the foreign argument-type keywords, described - above")))) - - (definition (:macro ff-call) - "ff-call entrypoint {lbrace}arg-type-specifier arg{rbrace}* {code &optional} result-type-specifier" nil - (para "Calls the foreign function at address entrypoint passing the - values of each arg as a foreign argument of type indicated by the - corresponding arg-type-specifier. Returns the foreign function - result (coerced to a Lisp object of type indicated by - result-type-specifier), or NIL if result-type-specifer is :VOID or - NIL") - (defsection "Values" - (listing :definition - (item "{param entrypoint}" ccldoc::=> "A fixnum or MACPTR") - (item "{param arg-type-specifer}" ccldoc::=> "One of the foreign argument-type keywords, described - above, or an equivalent " - (ref (section "Specifying And Using Foreign Types") "foreign type specifier") ".") - (item "{param arg}" ccldoc::=> "A lisp value of type indicated by the corresponding - arg-type-specifier") - (item "{param result-type-specifier}" ccldoc::=> "One of the foreign argument-type keywords, described - above, or an equivalent " - (ref (section "Specifying And Using Foreign Types") "foreign type specifier") ".")))) - - (definition (:function foreign-symbol-address) "foreign-symbol-address name" nil - (para "This function tries to resolve the address of the foreign - symbol {param name} (a lisp string). If successful, it - returns that address encapsulated in a macptr; otherwise, - it returns {code nil}.")) - - (definition (:function foreign-symbol-entry) "foreign-symbol-entry name" - nil - (para "This function rries to resolve the address of the foreign - symbol {param name} (a lisp string). If successful, it - returns a fixnum representation of that address. - Otherwise, it returns {code nil}.")) - - (definition (:function free) "free ptr" nil - "Free the foreign memory pointed to by {param ptr} by invoking -the standard C function {code free()}. If {param ptr} is a gcable -pointer (such as an object returned from {function -make-gcable-record}), then {function free} first informs the garbage -collector that the foreign memory has been deallocted before actually -calling {code free()}.") - - (definition (:function make-heap-ivector) "make-heap-ivector element-count element-type" nil - "An ivector is a one-dimensional array that's specialized to - a numeric or character element type. - - {function make-heap-ivector} allocates an ivector in - foreign memory. The GC will never move this vector, and - will in fact not pay any attention to it at all. The - returned pointer to it can therefore be passed safely to - foreign code. - - The vector must be explicitly deallocated with - {function dispose-heap-ivector}." - (defsection "Values" - (listing :definition - (item "{param element-count}" ccldoc::=> "A positive integer.") - (item "{param element-type}" ccldoc::=> "A type specifier. - - ") - (item "{param vector}" ccldoc::=> "A lisp vector. The initial contents are - undefined.") - (item "{param mactpr}" ccldoc::=> "A pointer to the first byte of data stored - in the vector. - ") - (item "{param size}" ccldoc::=> "The size of the returned vector in octets. - ")))) - - (definition (:macro ccl::make-gcable-record) "make-gcable-record typespec &rest initforms" nil - (para "Allocates a block of foreign memory suitable to hold the foreign - type described by {param typespec}, in the same manner - as " (ref (definition :macro make-record)) ". In - addition, {macro make-gcable-record} marks the - returned object gcable: in other words, it informs the garbage - collector that it may reclaim the object when it becomes - unreachable.") - (para "In all other respects, {macro make-gcable-record} works - the same way as " (ref (definition :macro make-record)) ".") - - " When using gcable pointers, it's important to remember the - distinction between a {code macptr} object (which is a - lisp object, more or less like any other) and the block of - foreign memory that the {code macptr} object points to. - If a gcable {code macptr} object is the only thing in the - world (lisp world or foreign world) that references the - underlying block of foreign memory, then freeing the foreign - memory when it becomes impossible to reference it is convenient - and sane. If other lisp {code macptr}s reference the - underlying block of foreign memory or if the address of that - foreign memory is passed to and retained by foreign code, having - the GC free the memory may have unpleasant consequences if those - other references are used. - - Take care, therefore, not to create a gcable record unless - you are sure that the returned {code macptr} will be the - only reference to the allocated memory that will ever be - used." - (defsection "Values" - (listing :definition - (item "{param typespec}" ccldoc::=> "A foreign type specifier, or a keyword which is used - as the name of a foreign struct or union.") - (item "{param initforms}" ccldoc::=> "If the type denoted by {param typespec} - is scalar, a single value appropriate for that type; - otherwise, a list of alternating field names and - values appropriate for the types of those fields.") - (item "{param result}" ccldoc::=> " - A {type macptr} which encapsulates the address of a - newly-allocated record on the foreign heap. The foreign - object returned by {function ccl::make-gcable-record} - is freed when the garbage collector determines that - the {code MACPTR} object that describes it is - unreachable.")))) - - (definition (:macro make-record) "make-record typespec {code &rest} initforms" nil - "Expands into code which allocates and initializes an instance - of the type denoted by {param typespec}, on the foreign heap. - The record is allocated using the C function {function - malloc}, and the user of {function make-record} must - explicitly call the function {function free} to deallocate the - record, when it is no longer needed. - - If {param initforms} is provided, its value or values are used - in the initialization. When the type is a scalar, {param - initforms} is either a single value which can be coerced to - that type, or no value, in which case binary 0 is used. When - the type is a {code struct}, {param initforms} is a list, - giving field names and the values for each. Each field is - treated in the same way as a scalar is: If a value for it is - given, it must be coerceable to the field's type; if not, - binary 0 is used. - - When the type is an array, {param initforms} may not be - provided, because {function make-record} cannot initialize its - values. {function make-record} is also unable to initialize - fields of a {code struct} which are themselves {code struct}s. - The user of {function make-record} should set these values by - another means. - - A possibly-significant limitation is that it must be possible - to find the foreign type at the time the macro is expanded; - {function make-record} signals an error if this is not the - case." - - (defsection "Values" - (listing :definition - (item "{param typespec}" ccldoc::=> "A foreign type specifier, or a keyword which is used - as the name of a foreign struct or union.") - (item "{param initforms}" ccldoc::=> "If the type denoted by {param typespec} - is scalar, a single value appropriate for that type; - otherwise, a list of alternating field names and - values appropriate for the types of those fields.") - (item "{param result}" ccldoc::=> " - A {type macptr} which encapsulates the address of a - newly-allocated record on the foreign heap. - "))) - (defsection "Notes" - " - It is inconvenient that {function make-record} is a - macro, because this means that {param typespec} - cannot be a variable; it must be an immediate value. - - If it weren't for this requirement, - {function make-record} could be a function. However, - that would mean that any stand-alone application using it would - have to include a copy of the interface database - (see {section The Interface Database}), which is undesirable - because it's large.")) - - (definition (:function open-shared-library) "open-shared-library name" - "Asks the operating system to load a shared library for {CCL} to use." - (defsection "Values" - (listing :definition - (item "{param name}" ccldoc::=> "A SIMPLE-STRING which is presumed to be the so-name of - or a filesystem path to the library.") - (item "{param library}" ccldoc::=> "An object of type SHLIB which describes the - library denoted by {param name}."))) - (defsection "Description" - (para "If the library denoted by {param name} can - be loaded by the - operating system, returns an object of type SHLIB that describes - the library; if the library is already open, increments a - reference count. If the library can't be loaded, signals a - SIMPLE-ERROR which contains an often-cryptic message from the - operating system.")) - (defsection "Examples" - (code-block #:|;;; Try to do something simple. - ? (open-shared-library "libgtk.so") - > Error: Error opening shared library "libgtk.so": /usr/lib/libgtk.so: undefined symbol: gdk_threads_mutex - > While executing: OPEN-SHARED-LIBRARY - - ;;; Grovel around, curse, and try to find out where "gdk_threads_mutex" - ;;; might be defined. Then try again: - - ? (open-shared-library "libgdk.so") - # - - ? (open-shared-library "libgtk.so") - # - - ;;; Reference an external symbol defined in one of those libraries. - - ? (external "gtk_main") - # - - ;;; Close those libraries. - - ? (close-shared-library "libgtk.so") - T - - ? (close-shared-library "libgdk.so") - T - - ;;; Reference the external symbol again. - - ? (external "gtk_main") - #|)) - (defsection "Notes" - "It would be helpful to describe what an soname is and give - examples of one. - - Does the SHLIB still get returned if the library is - already open?")) - - (definition (:macro pref) "pref ptr accessor-form" nil - "References an instance of a foreign type (or a component of a - foreign type) accessible via {param ptr}. - - Expands into code which references the indicated scalar type - or component, or returns a pointer to a composite type. - - PREF can be used with SETF." - - (defsection "Values" - (listing :definition - (item "{param ptr}" ccldoc::=> (ref (section "Referencing and Using Foreign Memory Addresses") "a MACPTR") - ".") - (item "{param accessor-form}" ccldoc::=> "a keyword which names a foreign type or record, as - described in {section Foreign type, record, and field names}. - ")))) - - (definition (:function %reference-external-entry-point) "%reference-external-entry-point eep" nil - (para "Tries to resolve the address of the external-entry-point - {param eep} and returns a fixnum representation of that address if - successful; else signals an error.") - (defsection "Values" - (listing :definition - (item "{param eep}" ccldoc::=> "An EXTERNAL-ENTRY-POINT, as obtained by the EXTERNAL - macro.")))) - - (definition (:macro rlet) "rlet (var typespec {code &rest} initforms)* &body body" nil - (para "Executes {param body} in an environment in which each - var is bound to a macptr encapsulating the - address of a stack-allocated foreign memory block, allocated and - initialized from {param typespec} and {param initforms} as per" - (ref (definition :macro make-record)) ". Returns - whatever values {param body} returns.") - (para "Record fields that aren't explicitly initialized have - unspecified contents.") - (defsection "Values" - (listing :definition - (item "{param var}" ccldoc::=> "A symbol (a lisp variable)") - (item "{param typespec}" ccldoc::=> "A foreign type specifier or foreign record name.") - (item "{param initforms}" ccldoc::=> "As described above, for - " - (ref (definition :macro make-record)))))) - - (definition (:macro rletz) "rletz (var typespec {code &rest} initforms)* {code &body} body" nil - "This macro is just like {macro rlet}, except that the stack-allocated - foreign memory is zeroed.") - - (definition (:function terminate-when-unreachable) "terminate-when-unreachable object" nil - "The termination mechanism is a way to have the garbage - collector run a function right before an object is about to - become garbage. It is very similar to the finalization - mechanism which Java has. It is not standard Common Lisp, - although other Lisp implementations have similar features. It - is useful when there is some sort of special cleanup, - deallocation, or releasing of resources which needs to happen - when a certain object is no longer being used. - - When the garbage collector discovers that an object is no - longer referred to anywhere in the program, it deallocates that - object, freeing its memory. However, if {function - terminate-when-unreachable} has been called on the object at - any time, the garbage collector first invokes the generic - function {function terminate}, passing it the object as a - parameter. - - Therefore, to make termination do something useful, you need to - define a method on {function terminate}. - - Because calling {function terminate-when-unreachable} only - affects a single object, rather than all objects of its class, - you may wish to put a call to it in the {function - initialize-instance} method of a class. Of course, this is - only appropriate if you do in fact want to use termination for - all objects of a given class." - (defsection "Values" - (listing :definition - (item "{param object}" ccldoc::=> "A CLOS object of a class for which there exists a method of the generic function {function terminate}."))) - (defsection "Example" - (code-block " - (defclass resource-wrapper () - ((resource :accessor resource))) - - (defmethod initialize-instance :after ((x resource-wrapper) &rest initargs) - (ccl:terminate-when-unreachable x)) - - (defmethod ccl:terminate ((x resource-wrapper)) - (when (resource x) - (deallocate (resource x))))")) - (defsection "See Also" (clause "{section Tutorial: Allocating Foreign Data on the Lisp Heap }"))) - - (definition (:function unuse-interface-dir) "unuse-interface-dir dir-id" nil - (para "Tells {CCL} to remove the interface directory denoted by - {param dir-id} from the list of interface directories which are - consulted for foreign type and function - information. Returns T if the directory was on the - search list, NIL otherwise.") - (defsection "Values" - (listing :definition - (item "{param dir-id}" ccldoc::=> #:|A keyword whose pname, mapped to lower case, names a subdirectory of "ccl:headers;" (or "ccl:darwin-headers;")|)))) - - (definition (:function use-interface-dir) "use-interface-dir dir-id" nil - (para "Tells {CCL} to add the interface directory denoted by - dir-id to the list of interface directories which it consults for - foreign type and function information. Arranges that that - directory is searched before any others.") - (para "Note that {function use-interface-dir} - merely adds an entry - to a search list. - If the named directory doesn't exist in the file system - or doesn't - contain a set of database files, a runtime error may occur - when {CCL} - tries to open some database file in that directory, and it - will try to - open such a database file whenever it needs to find any - foreign type or - function information. " - (ref (definition :function unuse-interface-dir)) " - may come in - handy in that case.") - (defsection "Values" - (listing :definition - (item "{param dir-id}" ccldoc::=> #:|A keyword whose pname, mapped to lower case, names a - subdirectory of "ccl:headers;" (or - "ccl:darwin-headers;")|))) - (defsection "Examples" - (para "One typically wants interface information to be - available at compile-time (or, in many cases, at read-time). - A typical idiom would be:") - (code-block "(eval-when (:compile-toplevel :execute) - (use-interface-dir :GTK))") - (para "Using the :GTK interface directory makes available - information on - foreign types, functions, and constants. It's generally - necessary to - load foreign libraries before actually calling the - foreign code, which for GTK can be done like this:") - (code-block "(load-gtk-libraries)") - (para "It should now be possible to do things like:") - (code-block "(#_gtk_widget_destroy w)"))))) diff --git a/ccl-documentation/fs.ccldoc b/ccl-documentation/fs.ccldoc deleted file mode 100644 index da95df8..0000000 --- a/ccl-documentation/fs.ccldoc +++ /dev/null @@ -1,138 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "File System Interface" - (defsection "Pathnames" - (defsection "Pathname Expansion" - "Leading tilde (~) characters in physical pathname namestrings - are expanded in the way that most shells do: “{code - ~user/...}” can be used to refer to an absolute pathname - rooted at the home directory of the user named “user”, and - “{code ~/...}” can be used to refer to an absolute pathname - rooted at the home directory of the current user.") - - (defsection "Predefined Logical Hosts" - "{CCL} sets up logical pathname translations for two logical - hosts: {code ccl} and {code home}. - - The {code ccl} logical host is meant to refer to the {system - ccl} directory. It is used for a variety of purposes by {CCL} - including: locating {CCL} source code, {code require} and {code - provide}, accessing foreign function information, and the {CCL} - build process. It is set to the value of the environment - variable {system CCL_DEFAULT_DIRECTORY}, if that variable - exists. Otherwise, it is set to the directory containing the - heap image file. - - The {code home} logical host refers to the user's home directory.") - - (defsection "Pathname Namestrings" - "The syntax of namestrings is implementation-defined in Common Lisp. - Portable programs cannot assume much of anything about - them. (See section 19.1.1 of the Common Lisp standard for - more information.) - - When translating a namestring into a pathname object, most - implementations seem to follow the convention that a dot - character in the namestring separates the {code pathname-name} - and the {code pathname-type}. When there is more than one dot - in involved, or when dots appear at the beginning or end of - the namestrings, what to do is less clear: does “{code - .emacs}” describe a pathname whose name is {code nil} and - whose type is {code emacs} or something else? Similarly, - given “{code a.b.c}”, the question is which parts are parsed - as the pathname name, and which are parsed as the pathname - type? - - When generating a namestring from a pathname object (as - happens, for example, when printing a pathname), {CCL} tries - to avoid some potential ambiguity by escaping characters that - might otherwise be used to separate pathname components. The - character used to quote or escape the separators is a backlash - on Unix systems, and a {code #\\>} character on Windows. So, - for example, “{code a\\\\.b.c}” has name “a.b” and type “c”, - whereas “a.b\\\\.c” has name “a” and type “b.c”. - - To get a native namestring suitable for passing to an - operating system command, use the function {function - native-translated-namestring}." - - (definition (:function native-translated-namestring) "native-translated-namestring pathname-designator" nil - "This function returns a namestring that represents a - pathname using the native conventions of the operating - system. Any quoting or escaping of special characters will - be removed. - - For example, suppose that {param p} is a pathname made - by {code (make-pathname :name \"a.b\" :type \"c\")}. - Then, {code (native-translated-namestring p)} evaluates - to \"a.b.c\". By contrast, {code (namestring p)} evaluates - to \"a\\\\.b.c\".") - - "Lisp strings are not interchangable with C strings. {CCL} -provides a reasonably straightforward way to translate a lisp native -namestring into a C-style string suitable for passing to a foreign -function." - - (definition (:macro with-filename-cstrs) - "with-filename-cstrs ( {lbrace}(var value){rbrace}* ) {lbrace}form{rbrace}*" "Suitably encode strings to be used as filenames for foreign code." - "Executes {param forms} in an environemt in which each - {param var} is bound to a stack-allocated foreign - pointer which refers to a C-style string suitable for passing - to foreign code which expects a filename argument. - - For example, one might use this macro in the following way:" - - (code-block "(with-filename-cstrs ((s (native-translated-namestring pathname))) - (#_unlink s))") - - "Various operating systems have different conventions - for how they expect native pathname strings to be encoded. - Darwin expects then to be decomposed UTF-8. The Unicode - variants to Windows file-handling functions expect UTF-16. - Other systems just treat them as opaque byte sequences. - This macro ensures that the correct encoding is used, - whatever the host operating system.") - - "On non-Darwin and non-Windows systems, {macro with-filename-cstrs} -calls {function pathname-encoding-name} to determine the encoding to use." - - (definition (:function pathname-encoding-name) "pathname-encoding-name" - nil - "Returns the name of the encoding to be used in -{macro with-filename-cstrs}. The default is {code nil}, which means -to use :iso-8859-1. It may be changed with {code setf}."))) - - - (definition (:function directory) "directory pathspec &key (directories t) (files t) (all t) (directory-pathnames t) (include-emacs-lockfiles nil) test (follow-links t)" nil - - "{CCL} extends the standard function {function directory} with a number of -keyword arguments:" - (listing :definition - (item "{code :files}" :=> "If true, includes - regular (non-directory) files in the - output. Defaults to {code t}.") - (item "{code :directories}" :=> "If true, includes directories - in the output. Defaults to - {code t}.") - (item "{code :all}" :=> "If true, includes files and directories - whose names start with a dot character in the output. (But - note that entries named “{code .}” or “{code ..}” are never - included.) Defaults to {code t}.") - (item "{code :follow-links}" :=> "If true, includes the - truenames of symbolic or hard links in the output; if false, - includes the link filenames without attempting to resolve - them. Defaults to {code t}. - - Note that legacy HFS alias files are treated as plain files.") - (item "{code :test}" :=> "A function of one argument (a - pathname) which should return true if the pathname should be - included in the output.") - (item "{code :include-emacs-lockfiles}" :=> "If true, include - emacs-style lockfiles (symbolic links of the form {system - .#something}) in the output. Defaults to {code nil}."))) - - - ) ;chapter - - - diff --git a/ccl-documentation/gc.ccldoc b/ccl-documentation/gc.ccldoc deleted file mode 100644 index 067fb73..0000000 --- a/ccl-documentation/gc.ccldoc +++ /dev/null @@ -1,332 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Understanding and Configuring the Garbage Collector" - (defsection "Heap space allocation" - #:|Release 0.10 or later of {CCL} uses a different memory - management scheme than previous versions did. Those earlier - versions would allocate a block of memory (of specified size) at - startup and would allocate lisp objects within that block. When - that block filled with live (non-GCed) objects, the lisp would - signal a "heap full" condition. The heap size imposed a limit on - the size of the largest object that could be allocated. - - The new strategy involves reserving a very large (2GB on - DarwinPPC32, 1GB on LinuxPPC, "very large" on 64-bit - implementations) block at startup and consuming (and - relinquishing) its contents as the size of the live lisp heap - data grows and shrinks. After the initial heap image loads and - after each full GC, the lisp kernel will try to ensure that a - specified amount (the "lisp-heap-gc-threshold") of free memory - is available. The initial value of this kernel variable is 16MB - on 32-bit implementations and 32MB on 64-bit implementations ; - it can be manipulated from Lisp (see below.) - - The large reserved memory block consumes very little in - the way of system resources; memory that's actually committed to - the lisp heap (live data and the "threshold" area where - allocation takes place) consumes finite resources (physical - memory and swap space). The lisp's consumption of those - resources is proportional to its actual memory usage, which is - generally a good thing. - - This scheme is much more flexible than the old one, but it - may also increase the possibility that those resources can - become exhausted. Neither the new scheme nor the old handles - that situation gracefully; under the old scheme, a program that - consumes lots of memory may have run into an artificial limit on - heap size before exhausting virtual memory. - - The -R or -heap-reserve command-line option can be - use to limit the size of the reserved block and therefore bound - heap expansion. Running| - (code-block " -> openmcl --heap-reserve 8M -") - (para "would provide an execution environment that's very similar to -that provided by earlier {CCL} versions.")) - (defsection "Ephemeral GC" - (para "For many programs, the following observations are true to - a very large degree:") - (listing :number - (item #:|Most heap-allocated objects have very short lifetimes ("are - ephemeral"): they become inaccessible soon after they're created.|) - (item "Most non-ephemeral objects have very long lifetimes: it's - rarely productive for the GC to consider reclaiming them, since - it's rarely able to do so. (An object that has survived a large - number of GCs is likely to survive the next one. That's not always - true of course, but it's a reasonable heuristic.)") - (item "It's relatively rare for an old object to be destructively - modified (via SETF) so that it points to a new one, therefore most - references to newly-created objects can be found in the stacks and - registers of active threads. It's not generally necessary to scan - the entire heap to find references to new objects (or to prove that - such references don't exists), though it is necessary to keep - track of the (hopefully exceptional) cases where old objects are - modified to point at new ones.")) - #:|"Ephemeral" (or "generational") garbage collectors try to - exploit these observations: by concentrating on frequently - reclaiming newly-created objects quickly, it's less often - necessary to do more expensive GCs of the entire heap in order - to reclaim unreferenced memory. In some environments, the - pauses associated with such full GCs can be noticeable and - disruptive, and minimizing the frequency (and sometimes the - duration) of these pauses is probably the EGC's primary goal - (though there may be other benefits, such as increased locality - of reference and better paging behavior.) The EGC generally - leads to slightly longer execution times (and slightly higher, - amortized GC time), but there are cases where it can improve - overall performance as well; the nature and degree of its impact - on performance is highly application-dependent. - - Most EGC strategies (including the one employed by - {CCL}) logically or physically divide memory into one or more - areas of relatively young objects ("generations") and one or - more areas of old objects. Objects that have survived one or - more GCs as members of a young generation are promoted (or - "tenured") into an older generation, where they may or may not - survive long enough to be promoted to the next generation and - eventually may become "old" objects that can only be reclaimed - if a full GC proves that there are no live references to them. - This filtering process isn't perfect - a certain amount of - premature tenuring may take place - but it usually works very - well in practice. - - It's important to note that a GC of the youngest - generation is typically very fast (perhaps a few milliseconds on - a modern CPU, depending on various factors), {CCL}'s EGC is - not concurrent and doesn't offer realtime guarantees. - - {CCL}'s EGC maintains three ephemeral generations; all - newly created objects are created as members of the youngest - generation. Each generation has an associated - {emphasis threshold}, which indicates the number of - bytes in it and all younger generations that can be allocated - before a GC is triggered. These GCs will involve the target - generation and all younger ones (and may therefore cause some - premature tenuring); since the older generations have larger - thresholds, they're GCed less frequently and most short-lived - objects that make it into an older generation tend not to - survive there very long. - - The EGC can be {emphasis enabled} or - {emphasis disabled} under program control; under some - circumstances, it may be enabled but - {emphasis inactive} (because a full GC is imminent.) - Since it may be hard to know or predict the consing behavior of - other threads, the distinction between the "active" and - "inactive" state isn't very meaningful, especially when native - threads are involved.|) - (defsection "GC Page reclamation policy" - #:|After a full GC finishes, it'll try to ensure that at - least (LISP-HEAP-GC-THRESHOLD) of virtual memory are available; - objects will be allocated in this block of memory until it fills - up, the GC is triggered, and the process repeats itself. - - Many programs reach near stasis in terms of the amount of - logical memory that's in use after full GC (or run for long - periods of time in a nearly static state), so the logical - address range used for consing after the Nth full GC is likely - to be nearly or entirely identical to the address range used by - the N+1th full GC. - - By default (and traditionally in {CCL}), the GC's policy - is to "release" the pages in this address range: to advise the - virtual memory system that the pages contain garbage and any - physical pages associated with them don't need to be swapped out - to disk before being reused and to (re-)map the logical address - range so that the pages will be zero-filled by the virtual - memory system when they're next accessed. This policy is - intended to reduce the load on the VM system and keep {CCL}'s - working set to a minimum. - - For some programs (especially those that cons at a very - high rate), the default policy may be less than ideal: releasing - pages that are going to be needed almost immediately - and - zero-fill-faulting them back in, lazily - incurs unnecessary - overhead. (There's a false economy associated with minimizing - the size of the working set if it's just going to shoot back up - again until the next GC.) A policy of "retaining" pages between - GCs might work better in such an environment. - - Functions described below give the user some control over - this behavior. An adaptive, feedback-mediated approach might - yield a better solution.|) - (defsection "\"Pure\" areas are read-only, paged from image file" - #:|SAVE-APPLICATION identifies code vectors and the pnames of - interned symbols and copies these objects to a "pure" area of - the image file it creates. (The "pure" area accounts for most of - what the ROOM function reports as "static" space.) - - When the resulting image file is loaded, the pure area of - the file is now memory-mapped with read-only access. Code and - pure data are paged in from the image file as needed (and don't - compete for global virtual memory resources with other memory - areas.) - - Code-vectors and interned symbol pnames are immutable : it - is an error to try to change the contents of such an - object. Previously, that error would have manifested itself in - some random way. In the new scheme, it'll manifest itself as an - "unhandled exception" error in the Lisp kernel. The kernel could - probably be made to detect a spurious, accidental write to - read-only space and signal a lisp error in that case, but it - doesn't yet do so. - - The image file should be opened and/or mapped in some mode - which disallows writing to the memory-mapped regions of the file - from other processes. I'm not sure of how to do that; writing to - the file when it's mapped by {CCL} can have unpredictable and - unpleasant results. SAVE-APPLICATION will delete its output - file's directory entry and create a new file; one may need to - exercise care when using file system utilities (like tar, for - instance) that might overwrite an existing image file.|) - (defsection "Weak References" - #:|In general, a "weak reference" is a reference to an object - which does not prevent the object from being garbage-collected. - For example, suppose that you want to keep a list of all the - objects of a certain type. If you don't take special steps, the - fact that you have a list of them will mean that the objects are - always "live", because you can always reference them through the - list. Therefore, they will never be garbage-collected, and - their memory will never be reclaimed, even if they are - referenced nowhere else in the program. If you don't want this - behavior, you need weak references. - - {CCL} supports weak references with two kinds of objects: - weak hash tables and populations. - - Weak hash tables are created with the standard Common Lisp - function {code make-hash-table}, which is extended - to accept the keyword argument {code :weak}. Hash - tables may be weak with respect to either their keys or their - values. To make a hash table with weak keys, invoke - {code make-hash-table} with the option :weak t, or, - equivalently, :weak :key. To make one with weak values, use - :weak :value. When the key is weak, the equality test must be - #'eq (because it wouldn't make sense otherwise). - - When garbage-collection occurs, key-value pairs are - removed from the hash table if there are no non-weak references to - the weak element of the pair (key or value). - - In general, weak-key hash tables are useful when you want - to use the hash to store some extra information about the - objects you look up in it, while weak-value hash tables are - useful when you want to use the hash as an index for looking up - objects. - - A population encapsulates an object, causing certain - reference from the object to be considered weak. {CCL} supports - two kinds of populations: lists, in which case the encapsulated - object is a list of elements, which are spliced out of the list - when there are no non-weak references to the element; and alists, - in which case the encapsulated object is a list of conses which - are spliced out of the list if there are no non-weak references - to the car of the cons. - - If you are experimenting with weak references - interactively, remember that an object is not dead if it was - returned by one of the last three interactively-evaluated - expressions, because of the variables {code *}, - {code **}, and {code ***}. The easy - workaround is to evaluate some meaningless expression before - invoking {code gc}, to get the object out of the - REPL variables.|) - (defsection "Weak References Dictionary" - (definition (:function make-population) "make-population {code &key} type initial-contents" nil - (defsection "Arguments and Values" - (listing :definition - (item "{param type}" ccldoc::=> "The type of population, one of {code :LIST} (the default) or {code :ALIST}") - (item "{param initial-contents}" ccldoc::=> - " A sequence of elements (or conses, for {code :alist}) to be used to initialize the - population. The sequence itself (and the conses in case of an - alist) is not stored in the population, a new list or alist is created to hold the elements."))) - (defsection "Description" (para "Creates a new population of the specified type."))) - (definition (:function population-type) "population-type population" nil - (defsection "Description" (para "returns the type of {code population}, one of {code :LIST} or {code :ALIST}"))) - (definition (:function population-contents) "population-contents population" nil - (defsection "Description" - (para "returns the list encapsulated in {code population}. - Note that as long as there is a direct (non-weak) reference to this - list, it will not be modified by the garbage collector. Therefore it is - safe to traverse the list, and even modify it, no different from any - other list. If you want the elements to become garbage-collectable - again, you must stop refering to the list directly."))) - (definition (:function (setf population-contents)) "(setf ( population-contents population) contents)" nil - (defsection "Description" - (para "Sets the list encapsulated in {code population} to - {code contents}. {code Contents} is not copied, - it is used directly.")))) - (defsection "Garbage-Collection Dictionary" - (definition (:function gc) "gc" nil - (defsection "Description" (para "Causes a full GC to occur as soon as possible. Returns NIL."))) - (definition (:function lisp-heap-gc-threshold) "lisp-heap-gc-threshold" nil - (defsection "Description" - (para "Returns the value of the kernel variable that specifies the - amount of free space to leave in the heap after full GC."))) - (definition (:function set-lisp-heap-gc-threshold) "set-lisp-heap-gc-threshold new-threshold" nil - (defsection "Arguments and Values" - (listing :definition (item "{param new-threshold}" ccldoc::=> "The requested new lisp-heap-gc-threshold."))) - (defsection "Description" - (para "Sets the value of the kernel variable that specifies the - amount of free space to leave in the heap after full GC to - new-value, which should be a non-negative fixnum. Returns the - value of that kernel variable (which may be somewhat larger than - what was specified)."))) - (definition (:function use-lisp-heap-gc-threshold) "use-lisp-heap-gc-threshold" nil - (defsection "Description" - (para "Tries to grow or shrink lisp's heap space, so that the - free space is (approximately) equal to the current heap threshold. - Returns NIL"))) - (definition (:function egc) "egc arg" nil - (defsection "Arguments and Values" (listing :definition (item "{param arg}" ccldoc::=> "a generalized boolean"))) - (defsection "Description" - (para "Enables the EGC if arg is non-nil, disables the EGC - otherwise. Returns the previous enabled status. Although this - function is thread-safe (in the sense that calls to it are - serialized), it doesn't make a whole lot of sense to be - turning the EGC on and off from multiple threads ..."))) - (definition (:function egc-enabled-p) "egc-enabled-p" nil - (defsection "Description" - (para "Returns T if the EGC was enabled at the time of the call, - NIL otherwise."))) - (definition (:function egc-active-p) "egc-active-p" nil - (defsection "Description" - (para "Returns T if the EGC was active at the time of the call, NIL - otherwise. Since this is generally a volatile piece of - information, it's not clear whether this function serves a - useful purpose when native threads are involved."))) - (definition (:function egc-configuration) "egc-configuration" nil - (defsection "Description" - (para "Returns, as multiple values, the sizes in kilobytes of the - thresholds associated with the youngest ephemeral generation, the - middle ephemeral generation, and the oldest ephemeral generation"))) - (definition (:function configure-egc) "configure-egc generation-0-size generation-1-size generation-2-size" nil - (defsection "Arguments and Values" - (listing :definition - (item "{param generation-0-size}" ccldoc::=> "the requested threshold size of the youngest - generation, in kilobytes") - (item "{param generation-1-size}" ccldoc::=> "the requested threshold size of the middle generation, - in kilobytes") - (item "{param generation-2-size}" ccldoc::=> "the requested threshold size of the oldest generation, - in kilobytes"))) - (defsection "Description" - (para "Puts the indicated threshold sizes in effect. - Each threshold indicates the total size that may be allocated - in that and all younger generations before a GC is triggered. - Disables EGC while setting the values. - (The provided threshold sizes are rounded up to a multiple of - 64Kbytes in {CCL} 0.14 and to a multiple of 32KBytes in earlier - versions.)"))) - (definition (:function gc-retain-pages) "gc-retain-pages arg" nil - (defsection "Arguments and Values" (listing :definition (item "{param arg}" ccldoc::=> "a generalized boolean"))) - (defsection "Description" - (para "Tries to influence the GC to retain/recycle the pages - allocated between GCs if arg is true, and to release them - otherwise. This is generally a tradeoff between paging and other - VM considerations."))) - (definition (:function gc-retaining-pages) "gc-retaining-pages" nil - (defsection "Description" - (para "Returns T if the GC tries to retain pages between full GCs - and NIL if it's trying to release them to improve VM paging - performance."))))) \ No newline at end of file diff --git a/ccl-documentation/glossary.ccldoc b/ccl-documentation/glossary.ccldoc deleted file mode 100644 index ff42985..0000000 --- a/ccl-documentation/glossary.ccldoc +++ /dev/null @@ -1,124 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(glossary-section "Glossary of Terms" - (glossentry "application bundle" - (para "A specially-structured directory that Mac OS X - recognizes as a - launchable " - (term "Cocoa") " - application. Graphical applications on Mac OS X are - represented as application bundles.")) - (glossentry "Cocoa" - (para "The standard user-interface libraries and frameworks - provided by Apple for development of applications on Mac OS - X.")) - (glossentry "creator code" - (para "A four-character identifier used in Mac OS X to uniquely - identify an application.")) - (glossentry "displaced array" - (para "An array with no storage of its own for elements, which - points to the storage of another array, called its - target. Reading or writing the elements of the displaced array - returns or changes the contents of the target.")) - (glossentry "fasl file" - (para #:|A file containing compiled lisp code that the Lisp is - able to quickly load and use. A "fast-load" file.|)) - (glossentry "Hemlock" - (para "A text editor, written in Common Lisp, similar in - features to Emacs. Hemlock was originally developed as part of - CMU Common Lisp. A portable version of Hemlock is built into - the {CCL} " - (term "IDE") ".")) - (glossentry "IDE" - (para #:|"Integrated Development Environment". In the context of - {CCL}, "the IDE" refers to the experimental | - (term "Cocoa") " - windowing development environment provided in source form with - {CCL} distributions.")) - (glossentry "heap image" - (para "The in-memory state of a running Lisp system, containing - functions, data structures, variables, and so on. Also, a file - containing archived versions of these data in a format that - can be loaded and reconstituted by the - Lisp " - (term "lisp kernel") ". A - working {CCL} system consists of the kernel and - a " - (term "heap image") ".")) - (glossentry "InterfaceBuilder" - (para "An application supplied by Apple with their developer - tools that can be used to interactively build user-interface - elements for " - (term "Cocoa") " - applications.")) - (glossentry "lisp kernel" - (para "The binary executable program that implements the lowest - levels of the Lisp system. A working {CCL} system consists of - the kernel and - a " - (term "heap image") ".")) - (glossentry "listener window" - (para "In the " (term "IDE") ", - a " - (term "Cocoa") " - window that contains a pseudo-terminal session that - communicates with a Lisp " - (term "REPL") ".")) - (glossentry "memory-mapped file" - (para "A file whose contents are accessible as a range of - memory addresses. Some operating systems support this feature, - in which the virtual memory subsystem arranges for a range of - virtual memory addresses to point to the contents of an open - file. Programs can then gain access to the file's contents by - operating on memory addresses in that range. Access to the - file's contents is valid only as long as the file remains - open.")) - (glossentry "nibfile" - (para "A data file created by - Apple's " - (term "InterfaceBuilder") " - application, which contains archived Objective-C objects that - define user-interface elements for - a " - (term "Cocoa") " - application. Under Mac OS - X, " - (term "Cocoa") " applications - typically create their user interface elements by reading - nibfiles and unarchiving the objects in them.")) - (glossentry "REPL" - (para #:|"Read-eval-print loop". The interactive shell provided - by {CCL} for interaction with Lisp.|)) - (glossentry "s-expression" - (para "The simplest, most general element of Lisp syntax. An - s-expression may be an atom (such as a symbol, integer, or - string), or it may be a list of s-expressions.")) - (glossentry "special variable" - (para "A variable whose binding is in the dynamic - environment. Special variables are essentially equivalent to - global variables in languages other than Lisp. A special - variable binding is visible in any lexical environment, so - long as a lexical binding has not shadowed it.")) - (glossentry "static variable" - (para "In {CCL}, a variable whose value is shared across all - threads, and which may not be dynamically rebound. Changing a - static variable's value in one thread causes all threads to - see the new value. Attempting to dynamically rebind the - variable (for instance, by using {code LET}, or using - the variable name as a parameter in a {code LAMBDA} - form) signals an error.")) - (glossentry "toplevel function" - (para "The function executed by Lisp automatically once its - startup is complete. {CCL}'s default toplevel is the - interactive " - (ref (glossentry "REPL") "read-eval-print loop") " that you normally use to interact with - Lisp. You can, however, replace the toplevel with a function - of your own design, changing {CCL} from a Lisp development - system into some tool of your making.")) - (glossentry "type-specifier" - (para "An expression that denotes a type. Type specifiers may - be symbols (such as {code CONS} - and {code STRING}), or they may be more complex - " - (ref (glossentry "s-expression") "S-expressions") " - (such as (UNSIGNED-BYTE 8))."))) diff --git a/ccl-documentation/hemlock.ccldoc b/ccl-documentation/hemlock.ccldoc deleted file mode 100644 index abb93c2..0000000 --- a/ccl-documentation/hemlock.ccldoc +++ /dev/null @@ -1,3955 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Hemlock Programming" - (defsection "Introduction" - " -Hemlock is the text editor used in {CCL}. It was originally based on the {link http://www.cons.org/cmucl/hemlock/index.html CMU Hemlock editor}, but has since diverged from it in various ways. We continue to call the editor part of our IDE {code Hemlock} to give credit where credit is due, but we make no attempt at source or API compatibility with the original Hemlock. - - - -Like the code, this documentation is based on the original Hemlock documentation, modified as necessary. - - - -Hemlock follows in the tradition of Emacs-compatible editors, with a rich set of extensible commands. This document describes the API for implementing new commands. The basic editor consists of a set of Lisp utility functions for manipulating buffers and the other data structures of the editor. All user level commands are written in terms of these -functions. To find out how to define commands see {section Commands}. - ") - (defsection "Representation of Text" - " -In Hemlock, text is represented as a sequence of lines. Newline characters -are never stored but are implicit between lines. The -implicit newline character is treated as the single character {code #\\Newline} by the -text primitives. - - - -Text is broken into lines when it is first introduced into Hemlock. Text enters -Hemlock from the outside world in two ways: reading a file, or pasting text -from the system clipboard. Hemlock uses heuristics {emphasis (which should be documented here!)} -to decide what newline convention to use to convert the incoming text into its internal -representation as a sequence of lines. Similarly it uses heuristics -{emphasis (which should be documented here!)} to convert the internal representation into -a string with embedded newlines in order to write a file or paste a region into -the clipboard. - " - (defsection "Lines" - (para " -A {code line} is an object representing a sequence of characters with no line breaks. - ") - (definition (:function hemlock-interface:linep) "linep line" nil - (defsection "Description" - (para " -This function returns t if line is a line object, otherwise nil. - "))) - (definition (:function hemlock-interface:line-string) "line-string line" nil - (defsection "Description" - (para " -Given a line, this function returns as a simple string the characters -in the line. This is setf'able to set the line-string to any string -that does not contain newline characters. It is an error to -destructively modify the result of line-string or to destructively -modify any string after the line-string of some line has been set to -that string. - "))) - (definition (:function hemlock-interface:line-previous) "line-previous line" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:line-next) "line-next line" nil - (defsection "Description" - (para " -Given a line, line-previous returns the previous line or nil if there -is no previous line. Similarly, line-next returns the line following -line or nil. - "))) - (definition (:function hemlock-interface:line-buffer) "line-buffer line" nil - (defsection "Description" - (para " -This function returns the buffer which contains this line. Since a -line may not be associated with any buffer, in which case line-buffer -returns nil. - "))) - (definition (:function hemlock-interface:line-length) "line-length line" nil - (defsection "Description" - (para " -This function returns the number of characters in the line. This -excludes the newline character at the end. - "))) - (definition (:function hemlock-interface:line-character) "line-character line index" nil - (defsection "Description" - (para " -This function returns the character at position index within line. It -is an error for index to be greater than the length of the line or -less than zero. If index is equal to the length of the line, this -returns a #\\newline character. - "))) - (definition (:function hemlock-interface:line-plist) "line-plist line" nil - (defsection "Description" - (para " -This function returns the property-list for line. setf, getf, putf and -remf can be used to change properties. This is typically used in -conjunction with line-signature to cache information about the line's -contents. - "))) - (definition (:function hemlock-interface:line-signature) "line-signature line" nil - (defsection "Description" - (para " -This function returns an object that serves as a signature for a -line's contents. It is guaranteed that any modification of text on the -line will result in the signature changing so that it is not eql to -any previous value. The signature may change even when the text -remains unmodified, but this does not happen often. - ")))) - (defsection "Marks" - " -A {code mark} indicates a specific position within the text represented by a -line and a character position within that line. Although a mark is -sometimes loosely referred to as pointing to some character, it in -fact points between characters. If the charpos is zero, the previous -character is the newline character separating the previous line from -the mark's line. If the charpos is equal to the number of characters -in the line, the next character is the newline character separating -the current line from the next. If the mark's line has no previous -line, a mark with charpos of zero has no previous character; if the -mark's line has no next line, a mark with charpos equal to the length of -the line has no next character. - - - -This section discusses the very basic operations involving marks, but -a lot of Hemlock programming is built on altering some text at a mark. -For more extended uses of marks see {section Altering and Searching Text}. - " - (defsection "Kinds of Marks" - " -A mark may have one of two lifetimes: temporary or permanent. Permanent -marks remain valid after arbitrary operations on the text; temporary -marks do not. Temporary marks are used because less bookkeeping -overhead is involved in their creation and use. If a temporary mark -is used after the text it points to has been modified results will be -unpredictable. Permanent marks continue to point between the same two -characters regardless of insertions and deletions made before or after -them. - - - -There are two different kinds of permanent marks which differ only in -their behavior when text is inserted at the position of the mark; text -is inserted to the left of a left-inserting mark and to the right of -right-inserting mark. - ") - (defsection "Mark Functions" - (definition (:function hemlock-interface:markp) "markp mark" nil - (defsection "Description" - (para " -This function returns t if mark is a mark object, otherwise nil. - "))) - (definition (:function hemlock-interface:mark-line) "mark-line mark" nil - (defsection "Description" - (para " -This function returns the line to which mark points. - "))) - (definition (:function hemlock-interface:mark-charpos) "mark-charpos mark" nil - (defsection "Description" - (para " -This function returns the character position {emphasis in the line} of the character -after mark, i.e. the number of characters before the mark in the mark's line. - "))) - (definition (:function hemlock-interface:mark-buffer) "mark-buffer mark" nil - (defsection "Description" - (para " -Returns the buffer containing this mark. - "))) - (definition (:function hemlock-interface:mark-absolute-position) "mark-absolute-position mark" nil - (defsection "Description" - (para " -This function returns the character position {emphasis in the buffer} of the character -after the mark, i.e. the number of characters before the mark in the mark's -buffer. - "))) - (definition (:function hemlock-interface:mark-kind) "mark-kind mark" nil - (defsection "Description" - (para " -This function returns one of {code :right-inserting}, {code :left-inserting} or - {code :temporary} depending on the mark's kind. A corresponding setf form -changes the mark's kind. - "))) - (definition (:function hemlock-interface:previous-character) "previous-character mark" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:next-character) "next-character mark" nil - (defsection "Description" - (para " -This function returns the character immediately before (after) the -position of the mark, or nil if there is no previous (next) character. -These characters may be set with setf when they exist; the setf -methods for these forms signal errors when there is no previous or -next character. - ")))) - (defsection "Making Marks" - (definition (:function hemlock-interface:mark) "mark line charpos {code &optional} kind" nil - (defsection "Description" - (para " -This function returns a mark object that points to the charpos'th -character of the line. Kind is the kind of mark to create, one -of {code :temporary}, {code :left-inserting}, or {code :right-inserting}. The default is -:temporary. - "))) - (definition (:function hemlock-interface:copy-mark) "copy-mark mark {code &optional} kind" nil - (defsection "Description" - (para " -This function returns a new mark pointing to the same position and of -the same kind, or of kind kind if it is supplied. - "))) - (definition (:function hemlock-interface:delete-mark) "delete-mark mark" nil - (defsection "Description" - (para " -This function deletes mark. Delete any permanent marks when you are -finished using it. - "))) - (definition (:macro hemlock-interface:with-mark) - "with-mark ({lbrace}(mark pos [kind]){rbrace}*) {lbrace}form{rbrace}*" nil - (defsection "Description" - (para " -This macro binds to each variable mark a mark of kind kind, which -defaults to {code :temporary}, pointing to the same position as the -markpos. On exit from the scope the mark is deleted. The value of the -last form is the value returned. - ")))) - (defsection "Moving Marks" - (para " -These functions destructively modify marks to point to new positions. -Other sections of this document describe mark moving routines specific -to higher level text forms than characters and lines, such as words, -sentences, paragraphs, Lisp forms, etc. - ") - (definition (:function hemlock-interface:move-to-position) - "move-to-position mark charpos {code &optional} line" nil - (defsection "Description" - (para " -This function changes the mark to point to the given character -position on the line line. Line defaults to mark's line. - "))) - (definition (:function hemlock-interface:move-to-absolute-position) "move-to-absolute-position mark position" - nil - (defsection "Description" - (para " -This function changes the mark to point to the given character -position in the buffer. - "))) - (definition (:function hemlock-interface:move-mark) "move-mark mark new-position" nil - (defsection "Description" - (para " -This function moves mark to the same position as the -mark new-position and returns it. - "))) - (definition (:function hemlock-interface:line-start) "line-start mark {code &optional} line" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:line-end) "line-end mark {code &optional} line" nil - (defsection "Description" - (para " -This function changes mark to point to the beginning or the end of -line and returns it. Line defaults to mark's line. - "))) - (definition (:function hemlock-interface:buffer-start) "buffer-start mark {code &optional} buffer" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:buffer-end) "buffer-end mark {code &optional} buffer" nil - (defsection "Description" - (para " -These functions change mark to point to the beginning or end of -buffer, which defaults to the buffer mark currently points into. If -buffer is unsupplied, then it is an error for mark to be disassociated -from any buffer. - "))) - (definition (:function hemlock-interface:mark-before) "mark-before mark" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:mark-after) "mark-after mark" nil - (defsection "Description" - (para " -These functions change mark to point one character before or after the -current position. If there is no character before/after the current -position, then they return nil and leave mark unmodified. - "))) - (definition (:function hemlock-interface:character-offset) "character-offset mark n" nil - (defsection "Description" - (para " -This function changes mark to point n characters after (n before if n -is negative) the current position. If there are less than n -characters after (before) the mark, then this returns nil and mark is -unmodified. - "))) - (definition (:function hemlock-interface:line-offset) "line-offset mark n {code &optional} charpos" nil - (defsection "Description" - (para " -This function changes mark to point n lines after (n before if n is -negative) the current position. The character position of the -resulting mark is (min (line-length resulting-line) (mark-charpos -mark)) if charpos is unspecified, or (min (line-length resulting-line) -charpos) if it is. As with character-offset, if there are not n lines -then nil is returned and mark is not modified. - "))))) - (defsection "Regions" - (para " -A {code region} is simply a pair of marks: a starting mark and an ending -mark. The text in a region consists of the characters following the -starting mark and preceding the ending mark (keep in mind that a mark -points between characters on a line, not at them). By modifying the -starting or ending mark in a region it is possible to produce regions -with a start and end which are out of order or even in different -buffers. The use of such regions is undefined and may result in -arbitrarily bad behavior. - ") - (defsection "Region Functions" - (definition (:function hemlock-interface:region) "region start end" nil - (defsection "Description" - (para " -This function returns a region constructed from the marks start and -end. It is an error for the marks to point to non-contiguous lines or -for start to come after end. - "))) - (definition (:function hemlock-interface:regionp) "regionp region" nil - (defsection "Description" - (para " -This function returns t if region is a region object, otherwise nil. - "))) - (definition (:function hemlock-interface:make-empty-region) "make-empty-region" nil - (defsection "Description" - (para " -This function returns a region with start and end marks pointing to -the start of one empty line. The start mark is a {code :right-inserting} -mark, and the end is a {code :left-inserting} mark. - "))) - (definition (:function hemlock-interface:copy-region) "copy-region region" nil - (defsection "Description" - (para " -This function returns a region containing a copy of the text in the -specified region. The resulting region is completely disjoint -from region with respect to data references --- marks, lines, text, etc. - "))) - (definition (:function hemlock-interface:region-to-string) "region-to-string region" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:string-to-region) "string-to-region string" nil - (defsection "Description" - (para " -These functions coerce regions to Lisp strings and vice versa. Within -the string, lines are delimited by newline characters. - "))) - (definition (:function hemlock-interface:line-to-region) "line-to-region line" nil - (defsection "Description" - (para " -This function returns a region containing all the characters on -line. The first mark is {code :right-inserting} and the last is - {code :left-inserting}. - "))) - (definition (:function hemlock-interface:region-start) "region-start region" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:region-end) "region-end region" nil - (defsection "Description" - (para " -This function returns the start or end mark of region. - "))) - (definition (:function hemlock-interface:region-bounds) "region-bounds region" nil - (defsection "Description" - (para " -This function returns as multiple-values the starting and ending marks -of region. - "))) - (definition (:function hemlock-interface:set-region-bounds) "set-region-bounds region start end" nil - (defsection "Description" - (para " -This function sets the start and end of region to start and end. It is -an error for start to be after or in a different buffer from end. - "))) - (definition (:function hemlock-interface:count-lines) "count-lines region" nil - (defsection "Description" - (para " -This function returns the number of lines in the region, first and -last lines inclusive. A newline is associated with the line it -follows, thus a region containing some number of non-newline -characters followed by one newline is one line, but if a newline were -added at the beginning, it would be two lines. - "))) - (definition (:function hemlock-interface:count-characters) "count-characters region" nil - (defsection "Description" - (para " -This function returns the number of characters in a given region. This -counts line breaks as one character. - ")))))) - (defsection "Buffers" - (para " -A buffer is an object consisting of: - " - (listing :number - (item " -A name. - ") - (item " -A piece of text. - ") - (item " -The insertion point. - ") - (item " -An associated file (optional). - ") - (item " -A write protect flag. - ") - (item " -Some " - (ref (section "Hemlock Variables") "variables") ". - ") - (item " -Some " - (ref (section "Commands") "key bindings") ". - ") - (item " -A collection of {section Modes}. - ") - (item " -A list of modeline fields (optional). - ")) - "Because of the way Hemlock is currently integrated in Cocoa, all modifications -to buffer contents must take place in the GUI thread. Hemlock commands always -run in the GUI thread, so most of the time you do not need to worry about it. -If you are running code in another thread that needs to modify a buffer, you -should perform that action using {code gui::execute-in-gui} or {code gui::queue-for-gui}. - ") - (para " -There are no intrinsic limitations on examining buffers from any thread, -however, Hemlock currently does no locking, so you risk seeing the buffer -in an inconsistent state if you look at it outside the GUI thread. - ") - (defsection "The Current Buffer" - (para #:| -Hemlock has the concept of the "current buffer". The current buffer -is defined during Hemlock commands as the buffer of the hemlock view -that received the key events that invoked the command. Many hemlock -function operate on the current buffer rather than taking an explicit -buffer argument. In effect, the current buffer is an implicit argument -to many text manipulation functions. - |) - (definition (:function hemlock-interface:current-buffer) "current-buffer" nil - (defsection "Description" - (para " -Returns the current buffer, which, during command execution, is the -buffer that is the target of the command. - "))) - (definition (:function hemlock-interface:current-point) "current-point" nil - (defsection "Description" - (para " -This function returns the buffer-point of the current buffer . This is -such a common idiom in commands that it is defined despite its trivial -implementation. - "))) - (definition (:function hemlock-interface:current-point-collapsing-selection) "current-point-collapsing-selection" - nil - (defsection "Description" - (para " -This function returns the buffer-point of the current buffer, after first -deactivating any active region. - "))) - (definition (:function hemlock-interface:current-point-extending-selection) "current-point-extending-selection" - nil - (defsection "Description" - (para " -This function returns the buffer-point of the current buffer, after first -making sure there is an active region - if the region is already active, -keeps it active, otherwise it establishes a new (empty) region at point. - "))) - (definition (:function hemlock-interface:current-point-for-insertion) "current-point-for-insertion" nil - (defsection "Description" - (para " -This function checks to see if the current buffer can be modified at its -current point, and errors if not. Otherwise, it deletes the current -selection if any, and returns the current point. - "))) - (definition (:function hemlock-interface:current-point-for-deletion) "current-point-for-deletion" nil - (defsection "Description" - (para " -This function checks to see if the current buffer can be modified at its -current point and errors if not. Otherwise, if there is a section -in the current buffer, it deletes it and returns NIL. If there is no -selection, it returns the current point. - "))) - (definition (:function hemlock-interface:current-point-unless-selection) "current-point-unless-selection" nil - (defsection "Description" - (para " -This function checks to see if the current buffer can be modified at its -current point and errors if not. Otherwise, if there's a selection in the -current buffer, returns NIL. If there is no selection, it returns the -current point. - "))) - (definition (:function hemlock-interface:current-mark) "current-mark" nil - (defsection "Description" - (para " -This function returns the top of the current buffer's mark stack. -There always is at least one mark at the beginning of the buffer's -region, and all marks returned are right-inserting. - "))) - (definition (:function hemlock-interface:pop-buffer-mark) "pop-buffer-mark" nil - (defsection "Description" - (para " -This function pops the current buffer's mark stack, returning the -mark. If the stack becomes empty, this pushes a new mark on the stack -pointing to the buffer's start. This always deactivates the current -region (see {section Active Regions}). - "))) - (definition (:function hemlock-interface:push-buffer-mark) - "push-buffer-mark mark {code &optional} activate-region" nil - (defsection "Description" - (para " -This function pushes mark into the current buffer's mark stack, -ensuring that the mark is right-inserting. If mark does not point into -the current buffer, this signals an error. Optionally, the current -region is made active, but this never deactivates the current region -(see {section Active Regions}). -Mark is returned. - "))) - (definition (:function hemlock-interface:push-new-buffer-mark) - "push-new-buffer-mark mark {code &optional} activate-region" nil - (defsection "Description" - (para " -This function pushes a new mark onto the mark stack, at the position of {code mark}. -It's equivalent to calling {code push-buffer-mark} on {code (copy-mark mark)}. - "))) - (definition (:function hemlock-interface:all-buffers) "all-buffers" nil - (defsection "Description" - (para " -This function returns a list of all the buffer objects made with make-buffer. - "))) - (definition (:variable hi:*buffer-names*) "*buffer-names*" nil - (defsection "Description" - (para " -This variable holds a " - (ref (section "String-table Functions") "string-table") " -mapping the name of a buffer to the corresponding buffer object. - ")))) - (defsection "Buffer Functions" - (definition (:function hemlock-interface:make-buffer) - "make-buffer name {code &key} :modes :modeline-fields :delete-hook" nil (defsection "Description" (para " "))) - (definition (:hemlock-variable "Default Modeline Fields") "Default Modeline Fields" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Make Buffer Hook") "Make Buffer Hook" nil - (defsection "Description" - (para " -make-buffer creates and returns a buffer with the given name. If a -buffer named name already exists, nil is returned. Modes is a list of -modes which should be in effect in the buffer, major mode first, -followed by any minor modes. If this is omitted then the buffer is -created with the list of modes contained in " - (ref (definition :hemlock-variable "Default Modes")) - ". Modeline-fields is a list of modeline-field objects (see -the {section Modelines} section) -which may be nil. delete-hook is a list of delete hooks specific -to this buffer, and delete-buffer invokes these along with Delete -Buffer Hook. - ") - (para " -Buffers created with make-buffer are entered into the list -(all-buffers), and their names are inserted into the string-table -*buffer-names*. When a buffer is created the hook Make Buffer Hook is -invoked with the new buffer. - "))) - (definition (:function hemlock-interface:bufferp) "bufferp buffer" nil - (defsection "Description" - (para " -Returns t if buffer is a buffer object, otherwise nil. - "))) - (definition (:function hemlock-interface:buffer-name) "buffer-name buffer" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Buffer Name Hook") "Buffer Name Hook" nil - (defsection "Description" - (para " -buffer-name returns the name, which is a string, of the given buffer. -The corresponding setf method invokes Buffer Name Hook with buffer -and the new name and then sets the buffer's name. When the user -supplies a name for which a buffer already exists, the setf method -signals an error. - "))) - (definition (:function hemlock-interface:buffer-region) "buffer-region buffer" nil - (defsection "Description" - (para " -Returns the buffer's region. Note this is the region that contains all -the text in a buffer, as opposed to the " - (ref (definition :function hemlock-interface:current-region)) ". - ") - (para " -This can be set with setf to replace the buffer's text. - "))) - (definition (:function hemlock-interface:buffer-pathname) "buffer-pathname buffer" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Buffer Pathname Hook") "Buffer Pathname Hook" nil - (defsection "Description" - (para " -buffer-pathname returns the pathname of the file associated with the -given buffer, or nil if it has no associated file. This is the -truename of the file as of the most recent time it was read or -written. There is a setf form to change the pathname. When the -pathname is changed the hook Buffer Pathname Hook is invoked with the -buffer and new value. - "))) - (definition (:function hemlock-interface:buffer-write-date) "buffer-write-date buffer" nil - (defsection "Description" - (para " -Returns the write date for the file associated with the buffer in -universal time format. When this the buffer-pathname is set, use setf -to set this to the corresponding write date, or to nil if the date is -unknown or there is no file. - "))) - (definition (:function hemlock-interface:buffer-point) "buffer-point buffer" nil - (defsection "Description" - (para " -Returns the mark which is the current location within buffer. To move -the point, use " - (ref (definition :function hemlock-interface:move-mark)) " or " - (ref (definition :function hemlock-interface:move-to-position))))) - (definition (:function hemlock-interface:buffer-mark) "buffer-mark buffer" nil - (defsection "Description" - (para " -This function returns the top of buffer's mark stack. There always is -at least one mark at the beginning of buffer's region, and all marks -returned are right-inserting. - "))) - (definition (:function hemlock-interface:buffer-start-mark) "buffer-start-mark buffer" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:buffer-end-mark) "buffer-end-mark buffer" nil - (defsection "Description" - (para " -These functions return the start and end marks of buffer's region: -" - (code-block " -(buffer-start-mark buffer ) <==> (region-start (buffer-region buffer)) -") - "and -" - (code-block " -(buffer-end-mark buffer ) <==> (region-end (buffer-region buffer)) -")))) - (definition (:function hemlock-interface:buffer-writable) "buffer-writable buffer" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Buffer Writable Hook") "Buffer Writable Hook" nil - (defsection "Description" - (para " -This function returns t if you can modify the buffer, nil if you -cannot. If a buffer is not writable, then any attempt to alter text -in the buffer results in an error. There is a setf method to change -this value. The setf method invokes the functions in Buffer Writable -Hook on the buffer and new value before storing the new value. - "))) - (definition (:function hemlock-interface:buffer-modified) "buffer-modified buffer" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Buffer Modified Hook") "Buffer Modified Hook" nil - (defsection "Description" - (para " -buffer-modified returns t if the buffer has been modified, nil if it -hasn't. This attribute is set whenever a text-altering operation is -performed on a buffer. There is a setf method to change this value. -The setf method invokes the functions in Buffer Modified Hook with the -buffer whenever the value of the modified flag changes. - "))) - (definition (:macro hemlock-interface:with-writable-buffer) "with-writable-buffer (buffer) {code &body} body" nil - (defsection "Description" - (para " -This macro executes forms with buffer's writable status set. After -forms execute, this resets the buffer's writable and modified status. - "))) - (definition (:function hemlock-interface:buffer-signature) "buffer-signature buffer" nil - (defsection "Description" - (para " -This function returns an arbitrary number which reflects the buffer's -current signature. The result is eql to a previous result if and only if -the buffer has not been modified between the calls. - "))) - (definition (:function hemlock-interface:buffer-variables) "buffer-variables buffer" nil - (defsection "Description" - (para " -This function returns a " - (ref (section "String-table Functions") "string-table") " containing the names of -the buffer's local " - (ref (section "Hemlock Variables") "variables") ". - "))) - (definition (:function hemlock-interface:buffer-modes) "buffer-modes buffer" nil - (defsection "Description" - (para " -This function returns the list of the names of the modes active in -buffer. The major mode is first, followed by any minor modes. See -the {section Modes} chapter. - "))) - (definition (:function hemlock-interface:buffer-delete-hook) "buffer-delete-hook buffer" nil - (defsection "Description" - (para " -This function returns the list of buffer specific functions -delete-buffer invokes when deleting a buffer . This is setf-able. - "))) - (definition (:function hemlock-interface:delete-buffer) "delete-buffer buffer" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Delete Buffer Hook") "Delete Buffer Hook" nil - (defsection "Description" - (para " -delete-buffer removes buffer from (" - (ref (definition :function hemlock-interface:all-buffers)) ") and its name -from " - (ref (definition :variable hi:*buffer-names*)) ". Before buffer is deleted, this invokes -the functions on buffer returned by buffer-delete-hook and those found -in Delete Buffer Hook. If buffer is the current-buffer, or if it is -displayed in any view, then this function signals an error. - ")))) - (defsection "Modelines" - " -A Buffer may specify a modeline, a line of text which is displayed -across the bottom of a view to indicate status information. -Modelines are described by a list of modeline-field objects which have -individual update functions and are optionally fixed-width. These have -an eql name for convenience in referencing and updating, but the name -must be unique for all created modeline-field objects. All modeline-field -functions must take a buffer as an -argument and return a string. When displaying -a modeline-field with a specified width, the result of the update -function is either truncated or padded on the right to meet the -constraint. - - - -Whenever one of the following changes occurs, all of a buffer's -modeline fields are updated: - " - (listing :bullet - (item " -A buffer's major mode is set. - ") - (item " -One of a buffer's minor modes is turned on or off. - ") - (item " -A buffer is renamed. - ") - (item " -A buffer's pathname changes. - ") - (item " -A buffer's modified status changes. - ")) - " -The policy is that whenever one of these changes occurs, it is -guaranteed that the modeline will be updated before the next trip -through redisplay. Furthermore, since the system cannot know what -modeline-field objects the user has added whose update functions rely -on these values, or how he has changed Default Modeline Fields, we must -update all the fields. - - - -The user should note that modelines can be updated at any time, so -update functions should be careful to avoid needless delays (for -example, waiting for a local area network to determine information). - " - (definition (:function hemlock-interface:make-modeline-field) - "make-modeline-field {code &key} :name :width :function" nil - (defsection "Description" - (para " -This function returns a modeline-field object with name, width, -and function. Width defaults to nil meaning that the field is variable -width; otherwise, the programmer must supply this as a positive -integer. Function must take a buffer as an arguments and -return a string. If name already names a modeline-field object, -then this signals an error. - "))) - (definition (:function hemlock-interface:modeline-field-name) "modeline-field-name modeline-field" nil - (defsection "Description" - (para " -This function returns the name field of a modeline-field object. -If this is set with setf, and the new name already names a -modeline-field, then the setf method signals an error. - "))) - (definition (:function hemlock-interface:modeline-field-p) "modeline-field-p modeline-field" nil - (defsection "Description" - (para " -This function returns t if its argument is a modeline-field object, nil -otherwise. - "))) - (definition (:function hemlock-interface:modeline-field) "modeline-field name" nil - (defsection "Description" - (para " -This returns the modeline-field object named name. If none exists, this -returns nil. - "))) - (definition (:function hemlock-interface:modeline-field-function) "modeline-field-function modeline-field" nil - (defsection "Description" - (para " -Returns the function called when updating the modeline-field. When this -is set with setf, the setf method updates modeline-field for all views -on all buffers that contain the given field, so the next trip through -redisplay will reflect the change. All modeline-field functions must -take a buffer as an argument and return a string. - "))) - (definition (:function hemlock-interface:modeline-field-width) "modeline-field-width modeline-field" nil - (defsection "Description" - (para " -Returns the width to which modeline-field is constrained, or nil -indicating that it is variable width. When this is set with setf, the -setf method updates all modeline-fields for all views on all buffers -that contain the given field, so the next trip through redisplay will -reflect the change. - "))) - (definition (:function hemlock-interface:buffer-modeline-fields) "buffer-modeline-fields buffer" nil - (defsection "Description" - (para " -Returns a copy of the list of buffer's modeline-field objects. This -list can be destructively modified without affecting display of -buffer's modeline, but modifying any particular field's components -(for example, width or function) causes the changes to be reflected -the next trip through redisplay in every modeline display that uses -the modified modeline-field. When this is set with setf, the setf -method method updates all modeline-fields on all views on the buffer, -so next trip through the redisplay will reflect the change. - "))) - (definition (:function hemlock-interface:buffer-modeline-field-p) "buffer-modeline-field-p buffer field" nil - (defsection "Description" - (para " -If field, a modeline-field or the name of one, is in buffer's list of -modeline-field objects, it is returned; otherwise, this returns nil. - "))) - (definition (:function hemlock-interface:update-modeline-fields) "update-modeline-fields buffer" nil - (defsection "Description" - (para " -Arranges so that the modeline display is updated with the latest values -at the end of current command. - "))))) - (defsection "Altering and Searching Text" - " -A note on marks and text alteration: :temporary marks are invalid -after any change has been made to the buffer the mark points to; it is -an error to use a temporary mark after such a change has been made. - - - -If text is deleted which has permanent marks pointing into it then -they are left pointing to the position where the text was. - " - (defsection "Altering Text" - (definition (:function hemlock-interface:insert-character) "insert-character mark character" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:insert-string) "insert-string mark string" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:insert-region) "insert-region mark region" nil - (defsection "Description" - (para " -Inserts character, string or region at mark. {code insert-character} signals -an error if character is not {code string-char-p}. If string or region is -empty, and mark is in some buffer, then Hemlock leaves buffer-modified of -mark's buffer unaffected. - "))) - (definition (:function hemlock-interface:ninsert-region) "ninsert-region mark region" nil - (defsection "Description" - (para " -Like {code insert-region}, inserts the region at the mark's position, -destroying the source region. This must be used with caution, since -if anyone else can refer to the source region bad things will -happen. In particular, one should make sure the region is not linked -into any existing buffer. If region is empty, and mark is in some -buffer, then Hemlock leaves buffer-modified of mark's buffer unaffected. - "))) - (definition (:function hemlock-interface:delete-characters) "delete-characters mark n" nil - (defsection "Description" - (para " -This deletes n characters after the mark (or -n before if n is -negative). If n characters after (or -n before) the mark do not -exist, then this returns nil; otherwise, it returns t. If n is zero, -and mark is in some buffer, then Hemlock leaves buffer-modified of -mark's buffer unaffected. - "))) - (definition (:function hemlock-interface:delete-region) "delete-region region" nil - (defsection "Description" - (para " -This deletes region. This is faster than delete-and-save-region -(below) because no lines are copied. If region is empty and contained -in some buffer's buffer-region, then Hemlock leaves buffer-modified of -the buffer unaffected. - "))) - (definition (:function hemlock-interface:delete-and-save-region) "delete-and-save-region region" nil - (defsection "Description" - (para " -This deletes region and returns a region containing the original -region's text. If region is empty and contained in some buffer's -buffer-region, then Hemlock leaves buffer-modified of the buffer -unaffected. In this case, this returns a distinct empty region. - "))) - (definition (:function hemlock-interface:filter-region) "filter-region function region" nil - (defsection "Description" - (para " -Destructively modifies region by replacing the text of each line with -the result of the application of function to a string containing that -text. Function must obey the following restrictions: - ") - (listing :number - (item " -The argument may not be destructively modified. - ") - (item " -The return value may not contain newline characters. - ") - (item " -The return value may not be destructively modified after it is returned from function. - ")) - " -The strings are passed in order. - - - -Using this function, a region could be uppercased by doing: - {code (filter-region #'string-upcase region)}"))) - (defsection "Text Predicates" - (definition (:function hemlock-interface:start-line-p) "start-line-p mark" nil - (defsection "Description" - (para " -Returns t if the mark points before the first character in a line, nil -otherwise. - "))) - (definition (:function hemlock-interface:end-line-p) "end-line-p mark" nil - (defsection "Description" - " -Returns t if the mark points after the last character in a line and -before the newline, nil otherwise. - - -{code empty-line-p} mark [Function] -Return t if the line which mark points to contains no characters. - ")) - (definition (:function hemlock-interface:blank-line-p) "blank-line-p line" nil - (defsection "Description" - (para " -Returns t if line contains only characters with a Whitespace attribute -of 1. See the {section Character Attributes} -chapter for discussion of character attributes. - "))) - (definition (:function hemlock-interface:blank-before-p) "blank-before-p mark" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:blank-after-p) "blank-after-p mark" nil - (defsection "Description" - (para " -These functions test if all the characters preceding or following mark -on the line it is on have a Whitespace attribute of 1. - "))) - (definition (:function hemlock-interface:same-line-p) "same-line-p mark1 mark2" nil - (defsection "Description" - (para " -Returns t if mark1 and mark2 point to the same line, or nil otherwise; That is, -" - (code-block " -(same-line-p a b) <==> (eq (mark-line a) (mark-line b)) -")))) - (definition (:function hemlock-interface:mark<) "mark< mark1 mark2" nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:mark<=) "mark<= mark1 mark2" nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:mark=) "mark= mark1 mark2" nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:mark/=) "mark/= mark1 mark2" nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:mark>=) "mark>= mark1 mark2" nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:mark>) "mark> mark1 mark2" nil - (defsection "Description" - (para " -These predicates test the relative ordering of two marks in a piece of -text, that is a mark is mark> another if it points to a position after -it. An error is signalled if the marks do not point into the same buffer, -except that for such marks mark= is always false and mark/= is always true. - "))) - (definition (:function hemlock-interface:line<) "line< line1 line2" nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:line<=) "line<= line1 line2" nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:line>=) "line>= line1 line2" nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:line>) "line> line1 line2" nil - (defsection "Description" - (para " -These predicates test the ordering of line1 and line2. An error is signalled -if the lines are not in the same buffer. - "))) - (definition (:function hemlock-interface:lines-related) "lines-related line1 line2" nil - (defsection "Description" - (para " -This function returns t if line1 and line2 are in the same buffer, nil -nil otherwise. - "))) - (definition (:function hemlock-interface:first-line-p) "first-line-p mark" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:last-line-p) "last-line-p mark" nil - (defsection "Description" - (para "{code first-line-p} returns t if there is no line before the line mark is on, -and nil otherwise. {code Last-line-p} similarly tests tests whether there is -no line after mark. - ")))) - (defsection "Kill Ring" - (para " -There is a global " - (ref (section "Ring Functions") "ring") " of regions deleted from buffers. -Some commands save affected regions on the kill ring before performing -modifications. You should consider making the command " - (ref (section "Undoing commands") "undoable") ", -but this is a simple way of achieving a less -satisfactory means for the user to recover. - ") - (definition (:function hemlock-interface:kill-region) "kill-region region current-type" nil - (defsection "Description" - (para " -This kills region saving it in the kill ring. Current-type is either -:kill-forward or :kill-backward. When the " - (ref (definition :function hemlock-interface:last-command-type)) " -is one of these, this adds region to the beginning or end, -respectively, of the top of the kill ring. The result of calling this is -undoable using the command Undo (see the Hemlock User's Manual). This -sets last-command-type to current-type, and it interacts with -kill-characters. - "))) - (definition (:function hemlock-interface:kill-characters) "kill-characters mark count" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Character Deletion Threshold") "Character Deletion Threshold (initial value 5)" - nil - (defsection "Description" - (para " -kill-characters kills count characters after mark if count is -positive, otherwise before mark if count is negative. When count is -greater than or equal to Character Deletion Threshold, the killed -characters are saved on the kill ring. This may be called multiple times -contiguously (that is, without " - (ref (definition :function hemlock-interface:last-command-type)) " being set) -to accumulate an effective count for purposes of comparison with the -threshold. - ") - " -This sets last-command-type, and it interacts with kill-region. When -this adds a new region to the kill ring, it sets last-command-type to -:kill-forward (if count is positive) or :kill-backward (if count is -negative). When last-command-type is :kill-forward or :kill-backward, -this adds the killed characters to the beginning (if count is -negative) or the end (if count is positive) of the top of the kill ring, -and it sets last-command-type as if it added a new region to the -kill ring. When the kill ring is unaffected, this sets -last-command-type to :char-kill-forward or :char-kill-backward -depending on whether count is positive or negative, respectively. - - - -This returns mark if it deletes characters. If there are not count -characters in the appropriate direction, this returns nil. - "))) - (defsection "Active Regions" - " -Every buffer has a mark stack and a mark known as the point -where most text altering nominally occurs. Between the top of the -mark stack, the current-mark, and the current-buffer's point, the -current-point, is what is known as the current-region . Certain -commands signal errors when the user tries to operate on the -current-region without its having been activated. If the user turns -off this feature, then the current-region is effectively always -active. - - - -When writing a command that marks a region of text, the programmer -should make sure to activate the region. This typically occurs -naturally from the primitives that you use to mark regions, but -sometimes you must explicitly activate the region. These commands -should be written this way, so they do not require the user to -separately mark an area and then activate it. Commands that modify -regions do not have to worry about deactivating the region since -modifying a buffer automatically deactivates the region. Commands -that insert text often activate the region ephemerally; that is, the -region is active for the immediately following command, allowing the -user wants to delete the region inserted, fill it, or whatever. - - - -Once a marking command makes the region active, it remains active until: - " - (listing :bullet - (item " -a command uses the region, - ") - (item " -a command modifies the buffer, - ") - (item " -a command changes the current window or buffer, - ") - (item " -a command signals an editor-error, - ") - (item " -or the user types C-g. - ")) - (definition (:hemlock-variable "Active Regions Enabled") "Active Regions Enabled (initial value t)" nil - (defsection "Description" - (para " -When this variable is non-nil, some primitives signal an editor-error -if the region is not active. This may be set to nil for more -traditional Emacs region semantics. - "))) - (definition (:variable hemlock-interface:*ephemerally-active-command-types*) "*ephemerally-active-command-types*" - nil - (defsection "Description" - (para " -This is a list of {section Command Types}, and its initial -value is the list of :ephemerally-active and :unkill. When the -previous command's type is one of these, the current-region is active -for the currently executing command only, regardless of whether it -does something to deactivate the region. However, the current command -may activate the region for future commands. :ephemerally-active is a -default command type that may be used to ephemerally activate the -region, and:unkill is the type used by two commands, Un-kill and -Rotate Kill Ring (what users typically think of as C-y and M-y). - "))) - (definition (:function hemlock-interface:activate-region) "activate-region" nil - (defsection "Description" - (para " -This makes the current-region active. - "))) - (definition (:function hemlock-interface:deactivate-region) "deactivate-region" nil - (defsection "Description" - (para " -After invoking this the current-region is no longer active. - "))) - (definition (:function hemlock-interface:region-active-p) "region-active-p" nil - (defsection "Description" - (para " -Returns whether the current-region is active, including -ephemerally. This ignores Active Regions Enabled. - "))) - (definition (:function hemlock-interface:check-region-active) "check-region-active" nil - (defsection "Description" - (para " -This signals an editor-error when active regions are enabled, and the -current-region is not active. - "))) - (definition (:function hemlock-interface:current-region) - "current-region {code &optional} error-if-not-active deactivate-region" nil - (defsection "Description" - (para " -This returns a region formed with current-mark and current-point, -optionally signaling an editor-error if the current region is not -active. Error-if-not-active defaults to t. Each call returns a -distinct region object. Depending on deactivate-region (defaults to -t), fetching the current region deactivates it. Hemlock primitives -are free to modify text regardless of whether the region is active, so -a command that checks for this can deactivate the region whenever it -is convenient. - ")))) - (defsection "Searching and Replacing" - (para " -Before using any of these functions to do a character search, look at -{section Character Attributes}. They provide a facility similar to -the syntax table in real Emacs. Syntax tables are a powerful, -general, and efficient mechanism for assigning meanings to characters -in various modes. - ") - (definition (:function hemlock-interface:new-search-pattern) - "new-search-pattern kind direction pattern {code &optional} result-search-pattern" nil - (defsection "Description" - (para " -Returns a search-pattern object which can be given to the find-pattern -and replace-pattern functions. A search-pattern is a specification of -a particular sort of search to do. direction is either :forward or -:backward, indicating the direction to search in. kind specifies the -kind of search pattern to make, and pattern is a thing which specifies -what to search for. The interpretation of pattern depends on the kind -of pattern being made. Currently defined kinds of search pattern are: - ") - (listing :definition - (item ":string-insensitive" ccldoc::=> " -Does a case-insensitive string search for pattern - ") - (item ":string-sensitive" ccldoc::=> " -Does a case-sensitive string search for pattern. - ") - (item ":character" ccldoc::=> " -Finds an occurrence of the character pattern. This is case sensitive. - ") - (item ":not-character" ccldoc::=> " -Find a character which is not the character pattern. - ") - (item ":test" ccldoc::=> " -Finds a character which satisfies the function pattern. This function may not be applied an any particular fashion, so it should depend only on what its argument is, and should have no side-effects. - ") - (item ":test-not" ccldoc::=> " -Similar to :test, except it finds a character that fails the test. - ") - (item ":any" ccldoc::=> " -Finds a character that is in the string pattern. - ") - (item ":not-any" ccldoc::=> " -Finds a character that is not in the string pattern. - ")) - (para " -result-search-pattern, if supplied, is a search-pattern to -destructively modify to produce the new pattern. Where reasonable -this should be supplied, since some kinds of search patterns may -involve large data structures. - "))) - (definition (:function hemlock-interface:search-pattern-p) "search-pattern-p search-pattern" nil - (defsection "Description" - (para " -Returns t if search-pattern is a search-pattern object, otherwise nil. - "))) - (definition (:function hemlock-interface:get-search-pattern) "get-search-pattern string direction" nil - (defsection "Description" - (para " -get-search-pattern interfaces to a default search string and pattern -that search and replacing commands can use. These commands then share -a default when prompting for what to search or replace, and save on -consing a search pattern each time they execute. This uses Default -Search Kind (see the Hemlock User's Manual) when updating the pattern -object. - "))) - (definition (:variable hemlock-interface:*last-search-string*) "*last-search-string*" nil - (defsection "Description" - (para " -Returns the last string searched for, useful when prompting. - "))) - (definition (:function hemlock-interface:find-pattern) "find-pattern mark search-pattern" nil - (defsection "Description" - (para " -Find the next match of search-pattern starting at mark. If a match is -found then mark is altered to point before the matched text and the -number of characters matched is returned. If no match is found then -nil is returned and mark is not modified. - "))) - (definition (:function hemlock-interface:replace-pattern) - "replace-pattern mark search-pattern replacement {code &optional} n" nil - (defsection "Description" - (para " -Replace n matches of search-pattern with the string replacement -starting at mark. If n is nil (the default) then replace all matches. -A mark pointing before the last replacement done is returned. - "))))) - (defsection "The Current Environment" - (defsection "Different Scopes" - (para #:| -In Hemlock the "current" values of | - (ref (section "Hemlock Variables") "variables") ", -" - (ref (section "Commands") "key bindings") " and -" - (ref (section "Character Attributes") "character-attributes") " -depend on the " - (ref (section "The Current Buffer") "current buffer") " -and the modes active in it. There are three possible scopes for -Hemlock values: - ") - (listing :definition - (item "buffer local" ccldoc::=> " -The value is present only if the buffer it is local to is the current buffer. - ") - (item "mode local" ccldoc::=> " -The value is present only when the mode it is local to is active in the current buffer. - ") - (item "global" ccldoc::=> " -The value is always present unless shadowed by a buffer or mode local value. - "))) - (defsection "Shadowing" - " -It is possible that there are different values for the same thing in -in different scopes. For example, there be might a global binding for a given -variable and also a local binding in the current buffer. Whenever there is a -conflict, shadowing occurs, permitting only one of the values to be visible in -the current environment. - - - -The process of resolving such a conflict can be described as a search -down a list of places where the value might be defined, returning the -first value found. The order for the search is as follows: - " - (listing :number - (item " -Local values in the current buffer. - ") - (item " -Mode local values in the minor modes of the current buffer, in order from the highest precedence mode to the lowest precedence mode. The order of minor modes with equal precedences is undefined. - ") - (item " -Mode local values in the current buffer's major mode. - ") - (item " -Global values. - ")))) - (defsection "Hemlock Variables" - (para " -Hemlock implements a system of variables separate from normal Lisp -variables for the following reasons: - ") - (listing :number - (item " -Hemlock has different scoping rules which are useful in an editor. Hemlock variables can be local to a " - (ref (section "Buffers") "buffer") " or a " (ref (section "Modes") "mode") ". - ") - (item " -Hemlock variables have " - (ref (section "Mode Hooks") "hooks") - ", lists of functions called when someone sets the variable. See variable-value for the arguments Hemlock passes to these hook functions. - ") - (item " -There is a database of variable names and documentation which makes it easier to find out what variables exist and what their values mean. - ")) - (defsection "Variable Names" - " -To the user, a variable name is a case insensitive string. This -string is referred to as the string name of the variable. A string -name is conventionally composed of words separated by spaces. - - - -In Lisp code a variable name is a symbol. The name of this symbol is -created by replacing any spaces in the string name with hyphens. This -symbol name is always interned in the Hemlock package. - " - (definition (:variable hemlock-interface:*global-variable-names*) "*global-variable-names*" nil - (defsection "Description" - (para " -This variable holds a string-table of the names of all the global -Hemlock variables. The value of each entry is the symbol name of the -variable. - "))) - (definition (:function hemlock-interface:current-variable-tables) "current-variable-tables" nil - (defsection "Description" - (para " -This function returns a list of variable tables currently established, -globally, in the current buffer, and by the modes of the -current-buffer. This list is suitable for use with -prompt-for-variable. - ")))) - (defsection "Variable Functions" - (para " -In the following descriptions name is the symbol name of the variable. - ") - (definition (:function hemlock-interface:defhvar) - "defhvar string-name documentation {code &key} :mode :buffer :hooks :value" nil - (defsection "Description" - (para " -This function defines a Hemlock variable. Functions that take a -variable name signal an error when the variable is undefined. - ") - (listing :definition - (item "{param string-name}" ccldoc::=> " -The string name of the variable to define. - ") - (item "{param documentation}" ccldoc::=> " -The documentation string for the variable. - ") - (item "{param mode}, {param buffer}" ccldoc::=> " -If buffer is supplied, the variable is local to that buffer. If mode is supplied, it is local to that mode. If neither is supplied, it is global. - ") - (item "{param value}" ccldoc::=> " -This is the initial value for the variable, which defaults to nil. - ") - (item "{param hooks}" ccldoc::=> " -This is the initial list of functions to call when someone sets the variable's value. These functions execute before Hemlock establishes the new value. See variable-value for the arguments passed to the hook functions. - ")) - (para " -If a variable with the same name already exists in the same place, -then defhvar sets its hooks and value from hooks and value if the user -supplies these keywords. - "))) - (definition (:function hemlock-interface:variable-value) "variable-value name {code &optional} kind where" nil - (defsection "Description" - (para " -This function returns the value of a Hemlock variable in some place. The following values for kind are defined: - ") - (listing :definition - (item ":current" ccldoc::=> " -Return the value present in the current environment, taking into consideration any mode or buffer local variables. This is the default. - ") - (item ":global" ccldoc::=> " -Return the global value. - ") - (item ":mode" ccldoc::=> " -Return the value in the mode named where. - ") - (item ":buffer" ccldoc::=> " -Return the value in the buffer where. - ")) - (para " -When set with setf, Hemlock sets the value of the specified variable -and invokes the functions in its hook list with name, kind, where, and -the new value. - "))) - (definition (:function hemlock-interface:variable-documentation) - "variable-documentation name {code &optional} kind where" nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:variable-hooks) "variable-hooks name {code &optional} kind where" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:variable-name) "variable-name name {code &optional} kind where" nil - (defsection "Description" - (para " -These function return the documentation, hooks and string name of a -Hemlock variable. The kind and where arguments are the same as for -variable-value. The documentation and hook list may be set using setf. - "))) - (definition (:function hemlock-interface:string-to-variable) "string-to-variable string" nil - (defsection "Description" - (para " -This function converts a string into the corresponding variable symbol -name. String need not be the name of an actual Hemlock variable. - "))) - (definition (:macro hemlock-interface:value) "value name" nil (defsection "Description" (para " "))) - (definition (:macro hemlock-interface:setv) "setv name new-value" nil - (defsection "Description" - (para " -These macros get and set the current value of the Hemlock variable -name. Name is not evaluated. There is a setf form for {code value}. - "))) - (definition (:macro hemlock-interface:hlet) "hlet ({lbrace}(var value){rbrace}*){lbrace}form{rbrace}*" nil - (defsection "Description" - (para " -This macro is very similar to let in effect; within its scope each of -the Hemlock variables var have the respective values, but after the -scope is exited by any means the binding is removed. This does not -cause any hooks to be invoked. The value of the last form is -returned. - "))) - (definition (:function hemlock-interface:hemlock-bound-p) "hemlock-bound-p name {code &optional} kind where" nil - (defsection "Description" - (para " -Returns t if name is defined as a Hemlock variable in the place -specified by kind and where, or nil otherwise. - "))) - (definition (:function hemlock-interface:delete-variable) "delete-variable name {code &optional} kind where" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Delete Variable Hook") "Delete Variable Hook" nil - (defsection "Description" - " -delete-variable makes the Hemlock variable name no longer defined in -the specified place. Kind and where have the same meanings as they do -for variable-value, except that :current is not available, and the -default for kind is :global - - - -An error will be signaled if no such variable exists. The hook, -Delete Variable Hook is invoked with the same arguments before the -variable is deleted. - "))) - (defsection "Hooks" - " -Hemlock actions such as setting variables, changing buffers, changing -windows, turning modes on and off, etc., often have hooks associated -with them. A hook is a list of functions called before the system -performs the action. The manual describes the object specific hooks -with the rest of the operations defined on these objects. - - - -Often hooks are stored in Hemlock variables, Delete Buffer Hook and -Set Window Hook for example. This leads to a minor point of confusion -because these variables have hooks that the system executes when -someone changes their values. These hook functions Hemlock invokes -when someone sets a variable are an example of a hook stored in an -object instead of a Hemlock variable. These are all hooks for editor -activity, but Hemlock keeps them in different kinds of locations. -This is why some of the routines in this section have a special -interpretation of the hook place argument. - " - (definition (:macro hemlock-interface:add-hook) "add-hook place hook-fun" nil - (defsection "Description" (para " "))) - (definition (:macro hemlock-interface:remove-hook) "remove-hook place hook-fun" nil - (defsection "Description" - (para " -These macros add or remove a hook function in some place. If hook-fun -already exists in place, this call has no effect. If place is a -symbol, then it is a Hemlock variable; otherwise, it is a generalized -variable or storage location. Here are two examples: - ") - (code-block " -(add-hook delete-buffer-hook 'remove-buffer-from-menu) -(add-hook (variable-hooks 'check-mail-interval) - 'reschedule-mail-check) -"))) - (definition (:macro hemlock-interface:invoke-hook) "invoke-hook place {code &rest} args" nil - (defsection "Description" - (para " -This macro calls all the functions in place. If place is a symbol, -then it is a Hemlock variable; otherwise, it is a generalized -variable. - "))))) - (defsection "Commands" - (defsection "Introduction" - (para " -The way that the user tells Hemlock to do something is by invoking a -command. Commands have three attributes: - ") - (listing :definition - (item "name" ccldoc::=> " -A command's name provides a way to refer to it. Command names are -usually capitalized words separated by spaces, such as Forward Word. - ") - (item "documentation" ccldoc::=> " -The documentation for a command is used by on-line help facilities. - ") - (item "function" ccldoc::=> " -A command is implemented by a Lisp function, which is callable from Lisp. - ")) - (defsection "Defining Commands" - (definition (:variable hemlock-interface:*command-names*) "*command-names*" nil - (defsection "Description" - (para " -Holds a " - (ref (section "String-table Functions") "string-table") " associating command names to command -objects. Whenever a new command is defined it is entered in this -table. - "))) - (definition (:macro hemlock-interface:defcommand) - "defcommand {lbrace}command-name | (command-name function-name {code &key}){rbrace} lambda-list command-doc {lbrace}function-doc{rbrace} {lbrace}form{rbrace}*" - nil - (defsection "Description" - (para " -Defines a command named name. defcommand creates a function to -implement the command from the lambda-list and forms supplied. The -lambda-list must specify one required argument, see " - (ref (section "Command Arguments") "below") #:|, -which by convention is typically named {code p}. If the caller does not specify -function-name, defcommand creates the command name by replacing all -spaces with hyphens and appending "-command". Any keyword arguments -are as for {code make-command}. Command-doc becomes the command -documentation for the command. Function-doc, if present, becomes the -documentation for the function and should primarily describe -issues involved in calling the command as a function, such as what any -additional arguments are. - |))) - (definition (:function hemlock-interface:make-command) - "make-command name documentation function {code &key} :transparent-p" nil - (defsection "Description" - (para " -Defines a new command named name, with command documentation -documentation and function function. If :transparent-p is true, -the command becomes " - (ref (section "Transparent Key Bindings") "transparent") ". -The command in entered in the -string-table " - (ref (definition :variable hemlock-interface:*command-names*)) ", with the command object as its -value. Normally command implementors will use the defcommand macro, -but this permits access to the command definition mechanism at a lower -level, which is occasionally useful. - "))) - (definition (:function hemlock-interface:commandp) "commandp command" nil - (defsection "Description" - (para " -Returns t if command is a command object, otherwise nil. - "))) - (definition (:function hemlock-interface:command-documentation) "command-documentation command" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:command-function) "command-function command" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:command-name) "command-name command" nil - (defsection "Description" - (para " -Returns the documentation, function, or name for command. These may be -set with setf. - ")))) - (defsection "Command Documentation" - (para " -Command documentation is a description of what the command does when -it is invoked as an extended command or from a key. Command -documentation may be either a string or a function. If the -documentation is a string then the first line should briefly summarize -the command, with remaining lines filling the details. Example: - ") - (code-block #:| -(defcommand "Forward Character" (p) - "Move the point forward one character. - With prefix argument move that many characters, with negative - argument go backwards." -. . .) -|) - (para " -Command documentation may also be a function of one argument. The -function is called with either :short or :full, indicating that the -function should return a short documentation string or do something -to document the command fully. - "))) - (defsection "The Command Interpreter" - (para " -The command interpreter is the functionality invoked by the event -handler to process key-events from the keyboard and dispatch to -different commands on the basis of what the user types. When the -command interpreter executes a command, we say it invokes the command. The -command interpreter also provides facilities for communication between -contiguously running commands, such as a last command type register. -It also takes care of resetting communication mechanisms, clearing the -echo area, displaying partial keys typed slowly by the user, etc. - ") - (defsection "Controlling The Command Interpreter" - (definition (:hemlock-variable "Command Abort Hook") "Command Abort Hook" nil - (defsection "Description" - (para " -The command interpreter invokes the function in this variable whenever -someone aborts a command (for example, if someone called -editor-error). - ")))) - (defsection "Editor Input" - (para " -The canonical representation of editor input is a key-event structure. -Users can bind commands to keys, which are -non-empty sequences of key-events. A key-event consists of an -identifying token known as a keysym and a field of bits representing -modifiers. Users define keysym names by supplying names that reflect -the legends on their keyboard's keys. Users define modifier names -similarly, but the system chooses the bit and mask for recognizing the -modifier. You can use keysym and modifier names to textually specify -key-events and Hemlock keys in a #k syntax. The following are some -examples: - ") - (code-block #:| -#k"C-u" -#k"Control-u" -#k"c-m-z" -#k"control-x meta-d" -#k"a" -#k"A" -#k"Linefeed" -|) - " -This is convenient for use within code and in init files -containing {code bind-key} calls. - - - -The #k syntax is delimited by double quotes. Within the -double quotes, spaces separate multiple key-events. A single -key-event optionally starts with modifier names terminated by hyphens. -Modifier names are alphabetic sequences of characters which the system -uses case-insensitively. Following modifiers is a keysym name, which -is case-insensitive if it consists of multiple characters, but if the -name consists of only a single character, then it is case-sensitive. - - - -You can escape special characters---hyphen, double quote, open angle -bracket, close angle bracket, and space---with a backslash, and you -can specify a backslash by using two contiguously. You can use angle -brackets to enclose a keysym name with many special characters in it. -Between angle brackets appearing in a keysym name position, there are -only two special characters, the closing angle bracket and backslash. - - - -For more information on key-events see the {section Key-events} section. - ") - (defsection "Binding Commands to Keys" - (para " -The command interpreter determines which command to invoke on the -basis of {emphasis key bindings}. A key binding is an association between a -command and a sequence of key-events. A sequence -of key-events is called a key and is represented by a single key-event -or a sequence (list or vector) of key-events. - ") - (para " -Since key bindings may be local to a mode or buffer, the " - (ref (section "The Current Environment") "current environment") - " determines the set of key bindings in effect at -any given time. When the command interpreter tries to find the -binding for a key, it first checks if there is a local binding in -the " - (ref (section "The Current Buffer") "current buffer") ", then if there is a binding in each of the -minor modes and the major " - (ref (section "Modes") "mode") " for the current buffer, and -finally checks to see if there is a global binding. If no binding is -found, then the command interpreter beeps or flashes the screen to -indicate this. - ") - (definition (:function hemlock-interface:bind-key) "bind-key name key {code &optional} kind where" nil - (defsection "Description" - (para " -This function associates command name and key in some environment. Key -is either a key-event or a sequence of key-events. There are three -possible values of kind: - ") - (listing :definition - (item ":global" ccldoc::=> " -The default, make a global key binding. - ") - (item ":mode" ccldoc::=> " -Make a mode specific key binding in the mode whose name is where. - ") - (item ":buffer" ccldoc::=> " -Make a binding which is local to buffer where. - ")) - (para " -This processes key for " - (ref (section "Key Translation") "key translations") " before establishing the -binding. - ") - " -If the key is some prefix of a key binding which already exists in the -specified place, then the new one will override the old one, -effectively deleting it. - - -{code do-alpha-key-events} is useful for setting up bindings in certain new modes. - ")) - (definition (:function hemlock-interface:command-bindings) "command-bindings command" nil - (defsection "Description" - (para " -This function returns a list of the places where command is bound. A -place is specified as a list of the key (always a vector), the kind of -binding, and where (either the mode or buffer to which the binding is -local, or nil if it is a global). - "))) - (definition (:function hemlock-interface:delete-key-binding) - "delete-key-binding key {code &optional} kind where" nil - (defsection "Description" - " -This function removes the binding of key in some place. Key is either -a key-event or a sequence of key-events. kind is the kind of binding -to delete, one of :global(the default), :mode or :buffer. If kind is -:mode, where is the mode name, and if kind is :buffer, then where is -the buffer. - - - -This function signals an error if key is unbound. - " - (para " -This processes key for " - (ref (section "Key Translation") "key translations") " before deleting the binding. - "))) - (definition (:function hemlock-interface:get-command) "get-command key {code &optional} kind where" nil - (defsection "Description" - (para " -This function returns the command bound to key, returning nil if it is -unbound. Key is either a key-event or a sequence of key-events. If -key is an initial subsequence of some keys, then this returns the -keyword :prefix. There are four cases of kind: - ") - (listing :definition - (item ":current" ccldoc::=> " -Return the current binding of key using the current buffer's search -list. If there are any transparent key bindings for key, then they -are returned in a list as a second value. - ") - (item ":global" ccldoc::=> " -Return the global binding of key. This is the default. - ") - (item ":mode" ccldoc::=> " -Return the binding of key in the mode named where. - ") - (item ":buffer" ccldoc::=> " -Return the binding of key local to the buffer where. - ")) - (para " -This processes key for " - (ref (section "Key Translation") "key translations") " before looking for any -binding. - "))) - (definition (:function hemlock-interface:map-bindings) "map-bindings function kind {code &optional} where" nil - (defsection "Description" - (para " -This function maps over the key bindings in some place. For each -binding, this passes function the key and the command bound to -it. Kind and where are the same as in bind-key. The key is not -guaranteed to remain valid after a given iteration. - ")))) - (defsection "Key Translation" - " -Key translation is a process that the command interpreter applies to -keys before doing anything else. There are two kinds of key -translations: substitution and bit-prefix. In either case, the command -interpreter translates a key when a specified key-event sequence -appears in a key. - - - -In a substitution translation, the system replaces the matched -subsequence with another key-event sequence. Key translation is not -recursively applied to the substituted key-events. - - - -In a bit-prefix translation, the system removes the matched -subsequence and effectively sets the specified bits in the next -key-event in the key. - - - -While translating a key, if the system encounters an incomplete final -subsequence of key-events, it aborts the translation process. This -happens when those last key-events form a prefix of some -translation. It also happens when they translate to a bit-prefix, but -there is no following key-event to which the system can apply the -indicated modifier. If there is a binding for this partially -untranslated key, then the command interpreter will invoke that -command; otherwise, it will wait for the user to type more key-events. - " - (definition (:function hemlock-interface:key-translation) "key-translation key" nil - (defsection "Description" - " -This form is setf-able and allows users to register key translations -that the command interpreter will use as users type key-events. - - - -This function returns the key translation for key, returning nil if -there is none. Key is either a key-event or a sequence of key-events. -If key is a prefix of a translation, then this returns :prefix. - - - -A key translation is either a key or modifier specification. The bits -translations have a list form: (:bits {lbrace}bit-name{rbrace}*). - - - -Whenever key appears as a subsequence of a key argument to the binding -manipulation functions, that portion will be replaced with the -translation. - "))) - (defsection "Transparent Key Bindings" - (para " -Key bindings local to a mode may be transparent. A transparent key -binding does not shadow less local key bindings, but rather indicates -that the bound command should be invoked before the first normal key -binding. Transparent key bindings are primarily useful for -implementing minor modes such as auto fill and word -abbreviation. There may be several transparent key bindings for a -given key, in which case all of the transparent commands are invoked in the -order they were found. If there no normal key binding for a key typed, -then the command interpreter acts as though the key is unbound even if -there are transparent key bindings. - ") - (para " -The :transparent-p argument to " - (ref (definition :function hemlock-interface:defmode)) " determines whether -all the key bindings in a mode are transparent or not. In addition -a particular command may be declared to be transparent by the -:transparent-p argument to defcommand and make-command. - "))) - (defsection "Command Types" - (para " -In many editors the behavior of a command depends on the kind of -command invoked before it. Hemlock provides a mechanism to support -this known as {code command type}. - ") - (definition (:function hemlock-interface:last-command-type) "last-command-type" nil - (defsection "Description" - (para " -This returns the command type of the last command invoked. If this is -set with setf, the supplied value becomes the value of -last-command-type until the next command completes. If the previous -command did not set last-command-type, then its value is nil. Normally -a command type is a keyword. The command type is not cleared after a -command is invoked due to a transparent key binding. - ")))) - (defsection "Command Arguments" - (para " -There are three ways in which a command may be invoked: It may be -bound to a key which has been typed, it may be invoked as an extended -command, or it may be called as a Lisp function. Ideally commands -should be written in such a way that they will behave sensibly no -matter which way they are invoked. The functions which implement -commands must obey certain conventions about argument passing if the -command is to function properly. - ") - (defsection "The Prefix Argument" - (para " -Whenever a command is invoked it is passed as its first argument what -is known as the prefix argument. The prefix argument is always either -an integer or nil. When a command uses this value it is usually as a -repeat count, or some conceptually similar function. - ") - (definition (:function hemlock-interface:prefix-argument) "prefix-argument" nil - (defsection "Description" - (para " -This function returns the current value of the prefix argument. When -set with setf, the new value becomes the prefix argument for the next -command. If the prefix argument is not set by the previous command -then the prefix argument for a command is nil. The prefix argument is -not cleared after a command is invoked due to a transparent key -binding. - ")))) - (defsection "Lisp Arguments" - (para " -It is often desirable to call commands from Lisp code, in which case -arguments which would otherwise be prompted for are passed as optional -arguments following the prefix argument. A command should prompt for -any arguments not supplied. - ")))) - (defsection "Modes" - (para " -A mode is a collection of Hemlock values which may be present in the -" - (ref (section "The Current Environment") "current environment") " depending on the editing task at hand. -An example of a typical mode is Lisp, for editing Lisp code. - ") - (defsection "Mode Hooks" - (para " -When a mode is added to or removed from a buffer, its mode hook is -invoked. The hook functions take two arguments, the buffer involved -and t if the mode is being added or nil if it is being removed. Mode -hooks are typically used to make a mode do something additional to -what it usually does. One might, for example, make a Text mode hook -that turned on auto-fill mode when you entered. - ")) - (defsection "Major and Minor Modes" - " -There are two kinds of modes, major modes and minor modes. A buffer -always has exactly one major mode, but it may have any number of minor -modes. Major modes may have mode character attributes while minor -modes may not. - - - -A major mode is usually used to change the environment in some major -way, such as to install special commands for editing some language. -Minor modes generally change some small attribute of the environment, -such as whether lines are automatically broken when they get too long. -A minor mode should work regardless of what major mode and minor modes -are in effect. - " - (definition (:hemlock-variable "Default Modes") #:|Default Modes (initial value '("Fundamental" "Save"))| nil - (defsection "Description" - (para " -This variable contains a list of mode names which are instantiated in -a buffer when no other information is available. - "))) - (definition (:variable hemlock-interface:*mode-names*) "*mode-names*" nil - (defsection "Description" - (para " -Holds a string-table of the names of all the modes. - "))) - (definition (:hemlock-command "Illegal") "Illegal" nil - (defsection "Description" - (para " -This is a useful command to bind in modes that wish to shadow global -bindings by making them effectively illegal. Also, although less -likely, minor modes may shadow major mode bindings with this. This -command calls editor-error. - ")))) - (defsection "Mode Functions" - (definition (:function hemlock-interface:defmode) - "defmode name {code &key} :setup-function :cleanup-function :major-p :precedence :transparent-p :documentation" - nil - (defsection "Description" - (para " -This function defines a new mode named name, and enters it in -" - (ref (definition :variable hemlock-interface:*mode-names*)) ". If major-p is supplied and is not nil then -the mode is a major mode; otherwise it is a minor mode. - ") - " -Setup-function and cleanup-function are functions which are invoked -with the buffer affected, after the mode is turned on, and before it -is turned off, respectively. These functions typically are used to -make buffer-local key or variable bindings and to remove them when the -mode is turned off. - - - -Precedence is only meaningful for a minor mode. The precedence of a -minor mode determines the order in which it in a buffer's list of -modes. When searching for values in the current environment, minor -modes are searched in order, so the precedence of a minor mode -determines which value is found when there are several definitions. - - - -Transparent-p determines whether key bindings local to the defined mode -are transparent. Transparent key bindings are invoked in addition to -the first normal key binding found rather than shadowing less local -key bindings. - - - -Documentation is some introductory text about the mode. Commands such -as Describe Mode use this. - ")) - (definition (:function hemlock-interface:mode-documentation) "mode-documentation name" nil - (defsection "Description" - (para " -This function returns the documentation for the mode named name. - "))) - (definition (:function hemlock-interface:buffer-major-mode) "buffer-major-mode buffer" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Buffer Major Mode Hook") "Buffer Major Mode Hook" nil - (defsection "Description" - (para " -buffer-major-mode returns the name of buffer's major mode. The major -mode may be changed with setf; then Buffer Major Mode Hook is invoked -with buffer and the new mode. - "))) - (definition (:function hemlock-interface:buffer-minor-mode) "buffer-minor-mode buffer name" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Buffer Minor Mode Hook") "Buffer Minor Mode Hook" nil - (defsection "Description" - (para " -buffer-minor-mode returns t if the minor mode name is active in -buffer, nil otherwise. A minor mode may be turned on or off by using -setf; then Buffer Minor Mode Hook is invoked with buffer, name and the -new value. - "))) - (definition (:function hemlock-interface:mode-variables) "mode-variables name" nil - (defsection "Description" - (para " -Returns the string-table of mode local variables. - "))) - (definition (:function hemlock-interface:mode-major-p) "mode-major-p name" nil - (defsection "Description" - (para " -Returns t if name is the name of a major mode, or nil if it is the -name of a minor mode. It is an error for name not to be the name of a -mode. - "))))) - (defsection "Character Attributes" - (defsection "Introduction" - (para " -Character attributes provide a global database of information about -characters. This facility is similar to, but more general than, the -syntax tables of other editors such as Emacs. For example, you should -use character attributes for commands that need information regarding -whether a character is whitespace or not. Use character attributes -for these reasons: - ") - (listing :number - (item " -If this information is all in one place, then it is easy the -change the behavior of the editor by changing the syntax table, -much easier than it would be if character constants were wired -into commands. - ")) - (listing :number - (item " -This centralization of information avoids needless duplication of effort. - ")) - (listing :number - (item " -The syntax table primitives are probably faster than anything that -can be written above the primitive level. - ")) - (para " -Note that an essential part of the character attribute scheme is that -character attributes are global and are there for the user to -change. Information about characters which is internal to some set of -commands (and which the user should not know about) should not be -maintained as a character attribute. For such uses various character -searching abilities are provided by the function " - (ref (definition :function hemlock-interface:find-pattern)) ". -20). - ")) - (defsection "Character Attribute Names" - (para #:| -As for Hemlock variables, character attributes have a user visible -string name, but are referred to in Lisp code as a symbol. The string -name, which is typically composed of capitalized words separated by -spaces, is translated into a keyword by replacing all spaces with -hyphens and interning this string in the keyword package. The -attribute named "Ada Syntax" would thus become :ada-syntax. - |) - (definition (:variable hemlock-interface:*character-attribute-names*) "*character-attribute-names*" nil - (defsection "Description" - (para " -Whenever a character attribute is defined, its name is entered in this -" - (ref (section "String-table Functions") "string-table") ", with the corresponding keyword as the value. - ")))) - (defsection "Character Attribute Functions" - (definition (:function hemlock-interface:defattribute) - "defattribute name documentation {code &optional} type initial-value" nil - (defsection "Description" - " -This function defines a new character attribute with name, a -string. Character attribute operations take attribute -arguments as a keyword whose name is name uppercased with spaces -replaced by hyphens. - - - -Documentation describes the uses of the character attribute. - - - -Type, which defaults to (mod 2), specifies what type the values of the -character attribute are. Values of a character attribute may be of -any type which may be specified to make-array. Initial-value (default -0) is the value which all characters will initially have for this -attribute. - ")) - (definition (:function hemlock-interface:character-attribute-name) "character-attribute-name attribute" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:character-attribute-documentation) - "character-attribute-documentation attribute" nil - (defsection "Description" - (para " -These functions return the name or documentation for attribute. - "))) - (definition (:function hemlock-interface:character-attribute) "character-attribute attribute character" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Character Attribute Hook") "Character Attribute Hook" nil - (defsection "Description" - " -character-attribute returns the value of attribute for character. This -signals an error if attribute is undefined. - - - -setf will set a character's attributes. This setf method invokes the -functions in Character Attribute Hook on the attribute and character -before it makes the change. - - - -If character is nil, then the value of the attribute for the beginning -or end of the buffer can be accessed or set. The buffer beginning and -end thus become a sort of fictitious character, which simplifies the -use of character attributes in many cases. - ")) - (definition (:function hemlock-interface:character-attribute-p) "character-attribute-p symbol" nil - (defsection "Description" - (para " -This function returns t if symbolis the name of a character attribute, -nil otherwise. - "))) - (definition (:function hemlock-interface:shadow-attribute) "shadow-attribute attribute character value mode" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Shadow Attribute Hook") "Shadow Attribute Hook" nil - (defsection "Description" - (para " -This function establishes value as the value of character's attribute -attribute when in the mode mode. Mode must be the name of a major -mode. Shadow Attribute Hook is invoked with the same arguments when -this function is called. If the value for an attribute is set while -the value is shadowed, then only the shadowed value is affected, not -the global one. - "))) - (definition (:function hemlock-interface:unshadow-attribute) "unshadow-attribute attribute character mode" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Unshadow Attribute Hook") "Unshadow Attribute Hook" nil - (defsection "Description" - (para " -Make the value of attribute for character no longer be shadowed in -mode. Unshadow Attribute Hook is invoked with the same arguments when -this function is called. - "))) - (definition (:function hemlock-interface:find-attribute) "find-attribute mark attribute {code &optional} test" - nil (defsection "Description" (para " "))) - (definition (:function hemlock-interface:reverse-find-attribute) - "reverse-find-attribute mark attribute {code &optional} test" nil - (defsection "Description" - (para " -These functions find the next (or previous) character with some value -for the character attribute attribute starting at mark. They pass test -one argument, the value of attribute for the character tested. If the -test succeeds, then these routines modify mark to point before (after -for reverse-find-attribute) the character which satisfied the test. -If no characters satisfy the test, then these return nil, and mark -remains unmodified. Test defaults to {code #'not-zerop}. There is no guarantee -that the test is applied in any particular fashion, so it should have -no side effects and depend only on its argument. - "))) - (definition (:function hemlock-interface:find-not-attribute) "find-not-attribute mark attribute" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:reverse-find-not-attribute) "reverse-find-not-attribute mark attribute" - nil - (defsection "Description" - (para " -These are equivalent to (find-attribute mark attribute #'zerop) and -(reverse-find-attribute mark attribute #'zerop), respectively. - ")))) - (defsection "Character Attribute Hooks" - " -It is often useful to use the character attribute mechanism as an -abstract interface to other information about characters which in fact -is stored elsewhere. For example, some implementation of Hemlock -might decide to define a Print Representation attribute which controls -how a character is displayed on an output device. - - - -To make this easy to do, each attribute has a list of hook functions -which are invoked with the attribute, character and new value whenever -the current value changes for any reason. - " - (definition (:function hemlock-interface:character-attribute-hooks) "character-attribute-hooks attribute" nil - (defsection "Description" - (para " -Return the current hook list for attribute. This may be set with -setf. The " - (ref (definition :macro hemlock-interface:add-hook)) " and " - (ref (definition :macro hemlock-interface:remove-hook)) " macros should be used to -manipulate these lists. - ")))) - (defsection "System Defined Character Attributes" - (para " -These are predefined in Hemlock: - ") - (listing :definition - (item #:|"Whitespace"| ccldoc::=> " -A value of 1 indicates the character is whitespace. - ") - (item #:|"Word Delimiter"| ccldoc::=> " -A value of 1 indicates the character separates words (see the {section English Text Buffers} section). - - ") - (item #:|"Space"| ccldoc::=> " -This is like Whitespace, but it should not include Newline. Hemlock -uses this primarily for handling indentation on a line. - ") - (item #:|"Sentence Terminator"| ccldoc::=> " -A value of 1 indicates these characters terminate sentences (see the {section English Text Buffers} section). - ") - (item #:|"Sentence Closing Char"| ccldoc::=> #:| -A value of 1 indicates these delimiting characters, such as " or ), -may follow a Sentence Terminator. - |) - (item #:|"Paragraph Delimiter"| ccldoc::=> " -A value of 1 indicates these characters delimit paragraphs when they -begin a line (see the {section English Text Buffers} section). - ") - (item #:|"Page Delimiter"| ccldoc::=> " -A value of 1 indicates this character separates {section Logical Pages} -when it begins a line. - ") - (item #:|"Lisp Syntax"| ccldoc::=> " -This uses symbol values from the following: - ")) - (listing :bullet - (item " -nil These characters have no interesting properties. - ")) - (listing :bullet - (item " -:space These characters act like whitespace and should not include Newline. - ")) - (listing :bullet - (item " -:newline This is the Newline character. - ")) - (listing :bullet - (item " -:open-paren This is ( character. - ")) - (listing :bullet - (item " -:close-paren This is ) character. - ")) - (listing :bullet - (item " -:prefix This is a character that is a part of any form it precedes for example, the single quote, '. - ")) - (listing :bullet - (item #:| -:string-quote This is the character that quotes a string literal, ". - |)) - (listing :bullet - (item " -:char-quote This is the character that escapes a single character, \\. - ")) - (listing :bullet - (item " -:comment This is the character that makes a comment with the rest of the line,;. - ")) - (listing :bullet - (item " -:constituent These characters are constitute symbol names. - ")))) - (defsection "Controlling the Display" - (defsection "Views" - " -A {code hemlock-view} represents the GUI object(s) used to display the contents -of a buffer. Conceptually it consists of a text buffer, a -modeline for semi-permanent status info, an echo area for transient -status info, and a text input area for reading prompted -input. (Currently the last two are conflated, i.e. text input happens -in the echo area). - - - -The API for working with hemlock-views is not fully -defined yet. If you need to work with views beyond what's listed -here, you will probably need to get in the sources and find some -internal functions to call. - ") - (defsection "The Current View" - (definition (:function hemlock-interface:current-view) "current-view" nil - (defsection "Description" - (para " -current-view returns the hemlock view which is the target of the -currently executing command. This is usually the frontmost hemlock -window in the current application. - ")))) - (defsection "View Functions" - (definition (:function hemlock-interface:hemlock-view-p) "hemlock-view-p object" nil - (defsection "Description" - (para " -This function returns t if object is a hemlock view, otherwise nil. - "))) - (definition (:function hemlock-interface:hemlock-view-buffer) "hemlock-view-buffer view" nil - (defsection "Description" - (para " -This function returns the buffer which is displayed in the view. - ")))) - (defsection "Cursor Positions" - (definition (:function hemlock-interface:mark-column) "mark-column mark" nil - (defsection "Description" - (para " -This function returns the X position at which mark would be displayed, -supposing its line was displayed on an infinitely wide screen. This -takes into consideration strange characters such as tabs. - "))) - (definition (:function hemlock-interface:move-to-column) "move-to-column mark column {code &optional} line" nil - (defsection "Description" - (para " -This function is analogous to " - (ref (definition :function hemlock-interface:move-to-position)) ", except that -it moves mark to the position on line which corresponds to the -specified column. If the line would not reach to the specified column, then nil is -returned and mark is not modified. Note that since a character may be -displayed on more than one column on the screen, several different -values of column may cause mark to be moved to the same position. - ")))) - (defsection "Redisplay" - (para " -The display of the buffer contents on the screen is updated at the -end of each command. The following function can be used to control -the scroll position of the buffer in the view. - ") - (definition (:function hemlock-interface:set-scroll-position) "set-scroll-position how {code &optional} what" nil - (defsection "Description" - (para " -Normally, after a command that changes the contents of the buffer -or the selection (i.e. the active region), the event handler repositions -the view so that the selection is visible, scrolling the buffer as -necessary. Calling this function tells the system to not do that, -and instead to position the buffer in a particular way. {code how} can -be one of the following: - ") - (listing :definition - (item ":center-selection" ccldoc::=> " -This causes the selection (or the point) to be centered in the visible area. {code what} is ignored. - - ") - (item ":page-up" ccldoc::=> " -This causes the previous page of the buffer to be shown {code what} is ignored. - ") - (item ":page-down" ccldoc::=> " -This causes the next page of the buffer to be shown. {code what} is ignored. - ") - (item ":lines-up" ccldoc::=> " - This causes {code what} previous lines to be scrolled in at the top. {code what} must be an integer. - ") - (item ":lines-down" ccldoc::=> " -This causes {code what} next lines to be scrolled in at the bottom. {code what} must be an integer. - ") - (item ":line" ccldoc::=> " - This causes the line containing {code what} to be scrolled to the top of the view. {code what} must be a mark. - ")))))) - (defsection "Logical Key-Events" - (defsection "Introduction" - (para " -Some primitives such as " - (ref (definition :function hemlock-interface:prompt-for-key)) " and commands such as -Emacs query replace read key-events directly from the keyboard instead -of using the command interpreter. To encourage consistency between -these commands and to make them portable and easy to customize, there -is a mechanism for defininglogical key-events. A logical key-event is -a keyword which stands for some set of key-events. The system -globally interprets these key-events as indicators a particular -action. For example, the :help logical key-event represents the set of -key-events that request help in a given Hemlock implementation. This -mapping is a many-to-many mapping, not one-to-one, so a given logical -key-event may have multiple corresponding actual key-events. Also, -any key-event may represent different logical key-events. - ")) - (defsection "Logical Key-Event Functions" - (definition (:variable hemlock-interface:*logical-key-event-names*) "*logical-key-event-names*" nil - (defsection "Description" - (para " -This variable holds a string-table mapping all logical key-event names -to the keyword identifying the logical key-event. - "))) - (definition (:function hemlock-interface:define-logical-key-event) - "define-logical-key-event string-name documentation" nil - (defsection "Description" - " -This function defines a new logical key-event with name string-name. -Logical key-event operations take logical key-events -arguments as a keyword whose name is string-name uppercased with -spaces replaced by hyphens. - - - -Documentation describes the action indicated by the logical key-event. - ")) - (definition (:function hemlock-interface:logical-key-event-key-events) "logical-key-event-key-events keyword" nil - (defsection "Description" - (para " -This function returns the list of key-events representing the logical -key-event keyword. - "))) - (definition (:function hemlock-interface:logical-key-event-name) "logical-key-event-name keyword" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:logical-key-event-documentation) - "logical-key-event-documentation keyword" nil - (defsection "Description" - (para " -These functions return the string name and documentation given -to define-logical-key-event for logical key-event keyword. - "))) - (definition (:function hemlock-interface:logical-key-event-p) "logical-key-event-p key-event keyword" nil - (defsection "Description" - (para " -This function returns t if key-event is the logical key-event -keyword. This is setf-able establishing or disestablishing key-events -as particular logical key-events. It is a error for keyword to be an -undefined logical key-event. - ")))) - (defsection "System Defined Logical Key-Events" - (para " -There are many default logical key-events, some of which are used by -functions documented in this manual. If a command wants to read a -single key-event command that fits one of these descriptions then the -key-event read should be compared to the corresponding logical -key-event instead of explicitly mentioning the particular key-event in -the code. In many cases you can use the " - (ref (definition :macro hemlock-interface:command-case)) " macro. -It makes logical key-events easy to use and takes care of prompting -and displaying help messages. - ") - (listing :bullet - (item " -:abort Indicates the prompter should terminate its activity without performing any closing actions of convenience, for example. - ") - (item " -:yes Indicates the prompter should take the action under consideration. - ") - (item " -:no Indicates the prompter should NOT take the action under consideration. - ") - (item " -:do-all Indicates the prompter should repeat the action under consideration as many times as possible. - ") - (item " -:do-once Indicates the prompter should execute the action under consideration once and then exit. - ") - (item " -:help Indicates the prompter should display some help information. - ") - (item " -:confirm Indicates the prompter should take any input provided or use the default if the user entered nothing. - ") - (item " -:quote Indicates the prompter should take the following key-event as itself without any sort of command interpretation. - ") - (item " -:keep Indicates the prompter should preserve something. - ") - (item " -:y Indicates a short positive response - ") - (item " -:n Indicates a short negative response - ")) - (para " -Define a new logical key-event whenever: - ") - (listing :number - (item " -The key-event concerned represents a general class of actions, and -several commands may want to take a similar action of this type. - ")) - (listing :number - (item " -The exact key-event a command implementor chooses may generate -violent taste disputes among users, and then the users can trivially -change the command in their init files. - ")) - (listing :number - (item " -You are using {code command-case} which prevents implementors from -specifying non-standard characters for dispatching in otherwise -possibly portable code, and you can define and set the logical -key-event in a site dependent file where you can mention -implementation dependent characters. - ")))) - (defsection "The Echo Area" - (para " -Hemlock provides a number of facilities for displaying information and -prompting the user for it. Most of these work through a small area -displayed at the bottom of the screen, called the Echo Area. - ") - (defsection "Echo Area Functions" - (definition (:function hemlock-interface:clear-echo-area) "clear-echo-area" nil - (defsection "Description" - (para " -Clears the echo area. - "))) - (definition (:function hemlock-interface:message) "message control-string {code &rest} format-arguments" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:loud-message) - "loud-message control-string {code &rest} format-arguments" nil - (defsection "Description" - (para " -Displays a message in the echo area, replacing previous contents if any. -loud-message is like message, but it also beeps. - "))) - (definition (:function hemlock-interface:beep) "beep" nil - (defsection "Description" - (para " -Gets the user's attention, typically by making a sound. - ")))) - (defsection "Prompting Functions" - #:| -Prompting functions can be used to obtain short one-line input from the user. - - - -Cocoa note: Because of implementation restrictions, only one buffer at -a time is allowed to read prompted input. If a prompting function is -invoked while a prompting operation is already in effect in another -buffer, the attempt fails, telling the user "Buffer xxx is already -waiting for input". - - - -Most of the prompting functions accept the following keyword arguments: - | - (listing :definition - (item ":must-exist" ccldoc::=> " -If :must-exist has a non-nil value then the user is -prompted until a valid response is obtained. If :must-exist is nil -then return as a string whatever is input. The default is t. - ") - (item ":default" ccldoc::=> " -If null input is given when the user is prompted then this -value is returned. If no default is given then some input must be -given before anything interesting will happen. - ") - (item ":default-string" ccldoc::=> " -If a :default is given then this is a string to be -printed to indicate what the default is. The default is some -representation of the value for :default, for example for a buffer it -is the name of the buffer. - ") - (item ":prompt" ccldoc::=> " -This is the prompt string to display. - ") - (item ":help" ccldoc::=> " -This is similar to :prompt, except that it is displayed when the help -command is typed during input. - ")) - (block nil - (para "This may also be a function. When called with no arguments, it -should either return a string which is the help text or perform some -action to help the user, returning nil. - ")) - (definition (:function hemlock-interface:prompt-for-buffer) - "prompt-for-buffer {code &key} :prompt :help :must-exist :default :default-string" nil - (defsection "Description" - (para " -Prompts with completion for a buffer name and returns the -corresponding buffer. If must-exist is nil, then it returns the input -string if it is not a buffer name. This refuses to accept the empty -string as input when :default and :default-string are -nil. :default-string may be used to supply a default buffer name -when:default is nil, but when :must-exist is non-nil, it must name an -already existing buffer. - "))) - (definition (:function hemlock-interface:prompt-for-key-event) "prompt-for-key-event {code &key} :prompt :help" - nil - (defsection "Description" - (para " -This function prompts for a key-event returning immediately when the -user types the next key-event. " - (ref (definition :macro hemlock-interface:command-case)) " is more useful -for most purposes. When appropriate, use {section Logical Key-Events}. - "))) - (definition (:function hemlock-interface:prompt-for-key) - "prompt-for-key {code &key} :prompt :help :must-exist :default :default-string" nil - (defsection "Description" - (para " -This function prompts for a key, a vector of key-events, suitable for -passing to any of the functions that manipulate " - (ref (section "Binding Commands to Keys") "key bindings") ". -If must-exist is true, then the key must be bound in the current -environment, and the command currently bound is returned as the second -value. - "))) - (definition (:function hemlock-interface:prompt-for-file) - "prompt-for-file {code &key} :prompt :help :must-exist :default :default-string" nil - (defsection "Description" - (para #:| -This function prompts for an acceptable filename. "Acceptable" means -that it is a legal filename, and it exists if must-exist is -non-nil. prompt-for-file returns a Common Lisp pathname. If the file -exists as entered, then this returns it, otherwise it is merged with -default as by merge-pathnames. - |))) - (definition (:function hemlock-interface:prompt-for-integer) - "prompt-for-integer {code &key} :prompt :help :must-exist :default :default-string" nil - (defsection "Description" - (para " -This function prompts for a possibly signed integer. If must-exist is -nil, then prompt-for-integer returns the input as a string if it is -not a valid integer. - "))) - (definition (:function hemlock-interface:prompt-for-keyword) - "prompt-for-keyword string-tables {code &key} :prompt :help :must-exist :default :default-string" nil - (defsection "Description" - " -This function prompts for a keyword with completion, using the string -tables in the list string-tables. If must-exist is non-nil, then the -result must be an unambiguous prefix of a string in one of the -string-tables, and the returns the complete string even if only a -prefix of the full string was typed. In addition, this returns the -value of the corresponding entry in the string table as the second -value. - - - -If must-exist is nil, then this function returns the string exactly as -entered. The difference between prompt-for-keyword with must-exist -nil, and prompt-for-string, is the user may complete the input using -the Complete Parse and Complete Field commands. - ")) - (definition (:function hemlock-interface:prompt-for-expression) - "prompt-for-expression {code &key} :prompt :help :must-exist :default :default-string" nil - (defsection "Description" - (para " -This function reads a Lisp expression. If must-exist is nil, and a -read error occurs, then this returns the string typed. - "))) - (definition (:function hemlock-interface:prompt-for-string) - "prompt-for-string {code &key} :prompt :help :default :default-string" nil - (defsection "Description" - (para " -This function prompts for a string; this cannot fail. - "))) - (definition (:function hemlock-interface:prompt-for-variable) - "prompt-for-variable {code &key} :prompt :help :must-exist :default :default-string" nil - (defsection "Description" - (para " -This function prompts for a variable name. If must-exist is non-nil, -then the string must be a variable defined in the current environment, -in which case the symbol name of the variable found is returned as the -second value. - "))) - (definition (:function hemlock-interface:prompt-for-y-or-n) - "prompt-for-y-or-n {code &key} :prompt :help :must-exist :default :default-string" nil - (defsection "Description" - (para " -This prompts for logical key events :Y or :N, returning t or nil without waiting for -confirmation. When the user types a confirmation key, this returns -default if it is supplied. If must-exist is nil, this returns -whatever key-event the user first types; however, if the user types -one of the above key-events, this returns t or nil. This is analogous to -the Common Lisp function y-or-n-p. - "))) - (definition (:function hemlock-interface:prompt-for-yes-or-no) - "prompt-for-yes-or-no {code &key} :prompt :help :must-exist :default :default-string" nil - (defsection "Description" - (para #:| -This function is to prompt-for-y-or-n as yes-or-no-p is to -y-or-n-p. "Yes" or "No" must be typed out in full and confirmation -must be given. - |))) - (definition (:macro hemlock-interface:command-case) - "command-case ({lbrace}key value{rbrace}*){lbrace}({lbrace}({lbrace}tag{rbrace}*) | tag{rbrace} help {lbrace}form{rbrace}*){rbrace}*" - nil - (defsection "Description" - (para " -This macro is analogous to the Common Lisp case macro. Commands such -as Help use this to get a key-event, translate it to a -character, and then to dispatch on the character to some case. In -addition to character dispatching, this supports {section Logical Key-Events} -by using the input key-event directly without translating it -to a character. Since the description of this macro is rather -complex, first consider the following example: -" - (code-block #:| -(defcommand "Save All Buffers" (p) - "Give the User a chance to save each modified buffer." - (dolist (b *buffer-list*) - (select-buffer-command () b) - (when (buffer-modified b) - (command-case (:prompt "Save this buffer: [Y] " - :help "Save buffer, or do something else:") - ((:yes :confirm) - "Save this buffer and go on to the next." - (save-file-command () b)) - (:no "Skip saving this buffer, and go on to the next.") - ((:exit #\\p) "Punt this silly loop." - (return nil)))))) -|)) - " -command-case prompts for a key-event and then executes the code in the -first branch with a logical key-event or a character (called tags) -matching the input. Each character must be a standard-character, one -that satisfies the Common Lisp standard-char-p predicate, and the -dispatching mechanism compares the input key-event to any character -tags by mapping the key-event to a character with -ext:key-event-char. If the tag is a logical key-event, then the search -for an appropriate case compares the key-event read with the tag -using logical-key-event-p. - - - -All uses of command-case have two default cases, :help and :abort. You -can override these easily by specifying your own branches that include -these logical key-event tags. The :help branch displays in a pop-up -window the a description of the valid responses using the variously -specified help strings. The :abort branch signals an editor-error. - - - -The key/value arguments control the prompting. The following are valid values: - " - (listing :definition - (item ":help" ccldoc::=> " -The default :help case displays this string in a pop-up window. In -addition it formats a description of the valid input including each -case's help string. - ") - (item ":prompt" ccldoc::=> " -This is the prompt used when reading the key-event. - ") - (item ":bind" ccldoc::=> " -This specifies a variable to which the prompting mechanism binds the -input key-event. Any case may reference this variable. If you wish -to know what character corresponds to the key-event, use -key-event-char. - ")) - " -Instead of specifying a tag or list of tags, you may use t. This -becomes the default branch, and its forms execute if no other branch -is taken, including the default :help and :abort cases. This option has -no helpstring, and the default :help case does not describe the default -branch. Every command-case has a default branch; if none is specified, -the macro includes one that beep's and reprompt's (see below). - - - -Within the body of command-case, there is a defined reprompt macro. It -causes the prompting mechanism and dispatching mechanism to -immediately repeat without further execution in the current branch. - "))) - (defsection "Control of Parsing Behavior" - (definition (:hemlock-variable "Beep On Ambiguity") "Beep On Ambiguity (initial value t)" nil - (defsection "Description" - (para #:| -If this variable is true, then an attempt to complete a parse which is -ambiguous will result in a "beep". - |)))) - (defsection "Defining New Prompting Functions" - (para #:| -Prompting functionality is implemented by the function parse-for-something -in cooperation with commands defined in "Echo Area" mode on the buffer associated -with the echo area. You can implement new prompting functions by invoking -parse-for-something with appropriate arguments. - |) - (definition (:function hemlock-interface:parse-for-something) "parse-for-something {code &key}" nil - (defsection "Description" - (para #:| -This function enters a mode reading input from the user and echoing it in the echo area, and -returns a value when done. The input is managed by commands bound in "Echo Area" mode on the -buffer associated with the echo area. The following keyword arguments are accepted: - |) - (listing :definition - (item "{code :verification-function}" ccldoc::=> " -This is invoked by the " - (ref (definition :hemlock-command "Confirm Parse")) " command. It does most of -the work when parsing prompted input. Confirm Parse calls it -with one argument, which is the string that the user typed so far. -The function should return a list of values which are to be the result -of the recursive edit, or nil indicating that the parse failed. In order -to return zero values, a non-nil second value may be returned along with -a nil first value. - ") - (item "{code :string-tables}" ccldoc::=> " -This is the list of string-tables, if any, that pertain to this parse. - ") - (item "{code :value-must-exist}" ccldoc::=> " -This is referred to by the verification function, and possibly some of the -commands. - ") - (item "{code :default}" ccldoc::=> " -The string representing the default object when prompting the user. -Confirm Parse supplies this to the parse verification function when the -user input is empty. - ") - (item "{code :default-string}" ccldoc::=> " -When prompting the user, if :default is not specified, Hemlock displays -this string as a representation of the default object; for example, -when prompting for a buffer, this argument would be a default buffer name. - ") - (item "{code :type}" ccldoc::=> " -The kind of parse, e.g. :file, :keyword, :string. This tells the completion -commands how to do completion, with :string disabling completion. - ") - (item "{code :prompt}" ccldoc::=> " -The prompt to display to the user. - ") - (item "{code :help}" ccldoc::=> " -The help string or function being used for the current parse. - "))))) - (defsection "Some Echo Area Commands" - (para " -These are some of the Echo Area commands that coordinate with the -prompting routines. Hemlock binds other commands specific to the Echo -Area, but they are uninteresting to mention here, such as deleting to -the beginning of the line or deleting backwards a word. - ") - (definition (:hemlock-command "Help On Parse") "Help On Parse (bound to Home, C-_ in Echo Area mode)" nil - (defsection "Description" - (para " -Display the help text for the parse currently in progress. - "))) - (definition (:hemlock-command "Complete Keyword") "Complete Keyword (bound to Escape in Echo Area mode)" nil - (defsection "Description" - (para " -This attempts to complete the current region. -It signals an editor-error if the input is ambiguous or incorrect. - "))) - (definition (:hemlock-command "Complete Field") "Complete Field (bound to Space in Echo Area mode)" nil - (defsection "Description" - (para " -Similar to {code Complete Keyword}, but only attempts to complete up to and -including the first character in the keyword with a non-zero -:parse-field-separator attribute. If there is no field separator then -attempt to complete the entire keyword. If it is not a keyword parse -then just self-insert. - "))) - (definition (:hemlock-command "Confirm Parse") "Confirm Parse (bound to Return in Echo Area mode)" nil - (defsection "Description" - (para " -Call the verification function with the current input. If it -returns a non-nil value then that is returned as the value of the -parse. A parse may return a nil value if the verification function -returns a non-nil second value. - "))))) - (defsection "Files" - (para " -This chapter discusses ways to read and write files at various -levels---at marks, into regions, and into buffers. This also treats -automatic mechanisms that affect the state of buffers in which files -are read. - ") - (defsection "File Options and Type Hooks" - (para #:| -The user specifies file options with a special syntax on the first -line of a file. If the first line contains the string "-*-", -then Hemlock interprets the text between the first such occurrence and -the second, which must be contained in one line , as a list of -"option: value" pairs separated by semicolons. The following is a -typical example: -| - (code-block " -;;; -*- Mode: Lisp, Editor; Package: Hemlock -*- -") - "See the Hemlock User's Manual for more details and predefined options. - ") - (para " -File type hooks are executed when Hemlock reads a file into a buffer -based on the type of the pathname. When the user specifies a Mode -file option that turns on a major mode, Hemlock ignores type hooks. -This mechanism is mostly used as a simple means for turning on some -appropriate default major mode. - ") - (definition (:macro hemlock-interface:define-file-option) - "define-file-option name (buffer value) {lbrace}declaration{rbrace}* {lbrace}form{rbrace}*" nil - (defsection "Description" - (para " -This defines a new file option with the string -name name. Buffer and value specify variable names for the buffer and the -option value string, and forms are evaluated with these bound. - "))) - (definition (:macro hemlock-interface:define-file-type-hook) - "define-file-type-hook type-list (buffer type) {lbrace}declaration{rbrace}* {lbrace}form{rbrace}*" nil - (defsection "Description" - (para " -This defines some code that process-file-options(below) executes when -the file options fail to set a major mode. This associates each type, -a string, in type-list with a routine that binds buffer to the -buffer the file is in and type to the type of the pathname. - "))) - (definition (:function hemlock-interface:process-file-options) - "process-file-options buffer {code &optional} pathname" nil - (defsection "Description" - (para " -This checks for file options in buffer and invokes handlers if there -are any. Pathname defaults to buffer's pathname but may be nil. If -there is no Mode file option that specifies a major mode, and pathname -has a type, then this tries to invoke the appropriate file type -hook. read-buffer-file calls this. - ")))) - (defsection "Pathnames and Buffers" - (para " -There is no good way to uniquely identify buffer names and pathnames. -However, Hemlock has one way of mapping pathnames to buffer names that -should be used for consistency among customizations and primitives. -Independent of this, Hemlock provides a means for consistently -generating prompting defaults when asking the user for pathnames. - ") - (definition (:function hemlock-interface:pathname-to-buffer-name) "pathname-to-buffer-name pathname" nil - (defsection "Description" - (para #:| -This function returns a string of the form "file-namestring directory-namestring". - |))) - (definition (:hemlock-variable "Pathname Defaults") #:|Pathname Defaults (initial value (pathname "gazonk.del"))| - nil (defsection "Description" (para " "))) - (definition (:hemlock-variable "Last Resort Pathname Defaults Function") "Last Resort Pathname Defaults Function" - nil (defsection "Description" (para " "))) - (definition (:hemlock-variable "Last Resort Pathname Defaults") - #:|Last Resort Pathname Defaults (initial value (pathname "gazonk"))| nil - (defsection "Description" - (para " -These variables control the computation of default pathnames when -needed for promting the user. Pathname Defaults is a sticky -default. See the Hemlock User's Manual for more details. - "))) - (definition (:function hemlock-interface:buffer-default-pathname) "buffer-default-pathname buffer" nil - (defsection "Description" - (para " -This returns Buffer Pathname if it is bound. If it is not bound, and -buffer's name is composed solely of alphnumeric characters, then -return a pathname formed from buffer's name. If buffer's name has -other characters in it, then return the value of Last Resort Pathname -Defaults Function called on buffer. - ")))) - (defsection "File Groups" - (para " -Currently Hemlock doesn't have support for file groups. - ")) - (defsection "File Reading and Writing" - (para " -Common Lisp pathnames are used by the file primitives. For probing, -checking write dates, and so forth, all of the Common Lisp file -functions are available. - ") - (definition (:function hemlock-interface:read-file) "read-file pathname mark" nil - (defsection "Description" - (para " -This inserts the file named by pathname at mark. - "))) - (definition (:function hemlock-interface:write-file) - "write-file region pathname {code &key} :keep-backup :append" nil (defsection "Description" (para " "))) - (definition (:hemlock-variable "Keep Backup Files") "Keep Backup Files (initial value nil)" nil - (defsection "Description" - " -This function writes the contents of region to the file named by -pathname. This writes region using a stream as if it were opened with -:if-exists supplied as :rename-and-delete. - - - -When keep-backup, which defaults to the value of Keep Backup Files, is -non-nil, this opens the stream as if :if-exists were :rename. If -append is non-nil, this writes the file as if it were opened -with:if-exists supplied as :append. - - - -This signals an error if both append and keep-backup are supplied as non-nil. - ")) - (definition (:function hemlock-interface:write-buffer-file) "write-buffer-file buffer pathname" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Write File Hook") "Write File Hook" nil (defsection "Description" (para " "))) - (definition (:hemlock-variable "Add Newline at EOF on Writing File") - "Add Newline at EOF on Writing File (initial value :ask-user)" nil - (defsection "Description" - (para " -write-buffer-file writes buffer to the file named by pathname -including the following: - ") - (listing :bullet - (item " -It assumes pathname is somehow related to buffer's pathname: if -the buffer's write date is not the same as pathname's, then this -prompts the user for confirmation before overwriting the file. - ")) - (listing :bullet - (item " -It consults Add Newline at EOF on Writing File (see Hemlock User's -Manual for possible values) and interacts with the user if -necessary. - ")) - (listing :bullet - (item " -It sets Pathname Defaults, and after using write-file, -marks buffer unmodified. - ")) - (listing :bullet - (item " -It updates Buffer's pathname and write date. - ")) - (listing :bullet - (item " -It renames the buffer according to the new pathname if possible. - ")) - (listing :bullet - (item " -It invokes Write File Hook. - ")) - (para " -Write File Hook is a list of functions that take the newly written buffer as an argument. - "))) - (definition (:function hemlock-interface:read-buffer-file) "read-buffer-file pathname buffer" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Read File Hook") "Read File Hook" nil - (defsection "Description" - (para " -read-buffer-file deletes buffer's region and uses read-file to read -pathname into it, including the following: - ") - (listing :bullet - (item " -It sets buffer's write date to the file's write date if the file -exists; otherwise, it messages that this is a new file and sets -buffer's write date to nil. - ")) - (listing :bullet - (item " -It moves buffer's point to the beginning. - ")) - (listing :bullet - (item " -It sets buffer's unmodified status. - ")) - (listing :bullet - (item " -It sets buffer's pathname to the result of probing pathname if the -file exists; otherwise, this function sets buffer's pathname to the -result of merging pathname with default-directory. - ")) - (listing :bullet - (item " -It sets Pathname Defaults to the result of the previous item. - ")) - (listing :bullet - (item " -It processes the file options. - ")) - (listing :bullet - (item " -It invokes Read File Hook. - ")) - (para " -Read File Hook is a list functions that take two arguments---the -buffer read into and whether the file existed, t if so. - "))))) - (defsection "Hemlock's Lisp Environment" - (para " -This chapter is sort of a catch all for any functions and variables -which concern Hemlock's interaction with the outside world. - ") - (defsection "Entering and Leaving the Editor" - (definition (:function ed) "ed {code &optional} x" nil - (defsection "Description" - " -This a standard Common Lisp function. If x is supplied and is a -string or pathname, the file specified by x is visited in a hemlock -view (opening a new window if necessary, otherwise bringing an -existing window with the file to the front), and the hemlock view -object is the return value from the function. - - - -If x is null, a new empty hemlock view is created and returned. - - - -If x is a symbol or a setf function name, it attempts to -edit the definition of the name. In this last case, the -function returns without waiting for the operation to complete -(for example, it might put up a non-modal dialog asking the -user to select one of multiple definitions) and hence the -return value is always NIL. - "))) - (defsection "Keyboard Input" - (definition (:variable hemlock-interface:*key-event-history*) "*key-event-history*" nil - (defsection "Description" - (para " -This is a Hemlock " - (ref (section "Ring Functions") "ring buffer") " that holds the last 60 -key-events received. - "))) - (definition (:function hemlock-interface:last-key-event-typed) "last-key-event-typed" nil - (defsection "Description" - (para " -This function returns the last key-event the user typed to invoke the current command. - "))) - (definition (:function hemlock-interface:last-char-typed) "last-char-typed" nil - (defsection "Description" - (para " -This function returns the character corresponding to the last key event typed. - ")))) - (defsection "Hemlock Streams" - (para " -It is possible to create streams which output to or get input from a -buffer. This mechanism is quite powerful and permits easy interfacing -of Hemlock to Lisp. - ") - (para " -Note that operations on these streams operate directly on buffers, -therefore they have the same restrictions as described " - (ref (section "Buffers") "here") " -for interacting with buffers from outside of the GUI thread. - ") - (definition (:function hemlock-interface:make-hemlock-output-stream) - "make-hemlock-output-stream mark {code &optional} buffered" nil - (defsection "Description" - (para " -This function returns a stream that inserts at mark all -output directed to it. It works best if mark is a left-inserting mark. -Buffered controls whether the stream is buffered or not, and its valid values -are the following keywords: - ") - (listing :definition - (item ":none" ccldoc::=> " -No buffering is done. This is the default. - ") - (item ":line" ccldoc::=> " -The buffer is flushed whenever a newline is written or when it is -explicitly done with force-output. - ") - (item ":full" ccldoc::=> " -The stream is only brought up to date when it is explicitly -done with force-output - ")))) - (definition (:function hemlock-interface:hemlock-output-stream-p) "hemlock-output-stream-p object" nil - (defsection "Description" - (para " -This function returns t if object is a hemlock-output-stream object. - "))) - (definition (:function hemlock-interface:make-hemlock-region-stream) "make-hemlock-region-stream region" nil - (defsection "Description" - (para " -This function returns a stream from which the text in -region can be read. - "))) - (definition (:function hemlock-interface:hemlock-region-stream-p) "hemlock-region-stream-p object" nil - (defsection "Description" - (para " -This function returns t if object is a hemlock-region-stream object. - "))) - (definition (:macro hemlock-interface:with-input-from-region) - "with-input-from-region (var region) {lbrace}declaration{rbrace}* {lbrace}form{rbrace}*" nil - (defsection "Description" - (para " -While evaluating forms, binds var to a stream which returns input from region. - "))) - (definition (:macro hemlock-interface:with-output-to-mark) - "with-output-to-mark (var mark [buffered]) {lbrace}declaration{rbrace}* {lbrace}form{rbrace}*" nil - (defsection "Description" - (para " -During the evaluation of the forms, binds var to a stream which inserts -output at the permanent mark. Buffered has the same meaning as for -make-hemlock-output-stream. - "))) - (definition (:macro hemlock-interface:with-pop-up-display) - "with-pop-up-display (var {code &key} height name) {lbrace}declaration{rbrace}* {lbrace}form{rbrace}*" nil - (defsection "Description" - (para " -This macro executes forms in a context with var bound to a -stream. Hemlock collects output to this stream and tries to pop up a -display of the appropriate height containing all the output. When -height is supplied, Hemlock creates the pop-up display immediately, -forcing output on line breaks. This is useful for displaying information -of temporary interest. - ")))) - (defsection "Interface to the Error System" - " -Hemlock commands are executed from an event handler in the initial -Cocoa thread. They are executed within a -ccl::with-standard-abort-handling form, which means cl:abort, -ccl:abort-break, ccl:throw-cancel will abort the current command only -and exit the event handler in an orderly fashion. - - - -In addition, for now, lisp errors during command execution dump a -backtrace in the system console and are otherwise handled as if by - {code handle-lisp-errors} below, which means it is not possible to debug -errors at the point of the error. Once {CCL} has better support -for debugging errors in the initial Cocoa thread, better Hemlock error -handling will be provided that will allow for some way to debug. - " - (definition (:function hemlock-interface:editor-error) "editor-error {code &rest} args" nil - (defsection "Description" - (para " -This function is called to report minor errors to the user. These are -errors that a normal user could encounter in the course of editing, -such as a search failing or an attempt to delete past the end of the -buffer. This function simply aborts the current command. Any args -specified are used to format an error message to be placed in the echo -area. This function never returns. - "))) - (definition (:macro hemlock-interface:handle-lisp-errors) "handle-lisp-errors {lbrace}form{rbrace}*" nil - (defsection "Description" - (para " -Within the body of this macro any Lisp errors that occur are handled -by displaying an error message in a dialog and aborting the current -command, leaving the error text in the echo area. This macro should -be wrapped around code which may get an error due to some action of -the user --- for example, evaluating code fragments on the behalf of -and supplied by the user. - ")))) - (defsection "Definition Editing" - (para " -Hemlock provides commands for finding the definition of a function -or variable and placing the user at the definition in a buffer. A -function is provided to allow invoking this functionality outside -of Hemlock. Note that this function is unusual in that it is -it is safe to call outside of the command interpreter, and in fact -it can be called from any thread. - ") - (definition (:function hemlock:edit-definition) "edit-definition name" nil - (defsection "Description" - (para " -This function tries to find the definition of {code name}, create -or activate the window containing it, and scroll the view -to show the definition. If there are multiple definitions -available, the user is given a choice of which one to -use. This function may return before the operation is complete. - ")))) - (defsection "Event Scheduling" - (para " -No Event Scheduling functionality is provided at this time. - ")) - (defsection "Miscellaneous" - (definition (:function hemlock-interface:in-lisp) "in-lisp {lbrace}form{rbrace}*" nil - (defsection "Description" - (para " -This evaluates forms inside handle-lisp-errors. It also binds -*package* to the package named by Current Package if it is -non-nil. Use this when evaluating Lisp code on behalf of the user. - "))) - (definition (:macro hemlock-interface:do-alpha-chars) "do-alpha-chars (var kind [result]) {lbrace}form{rbrace}*" - nil - (defsection "Description" - (para " -This iterates over alphabetic characters in Common Lisp binding var to -each character in order as specified under character relations in -Common Lisp the Language. Kind is one of:lower, :upper, or :both. When -the user supplies :both, lowercase characters are processed first. - "))))) - (defsection "High-Level Text Primitives" - (para " -This chapter discusses primitives that operate on higher level text -forms than characters and words. For English text, there are functions -that know about sentence and paragraph structures, and for Lisp -sources, there are functions that understand this language. This -chapter also describes mechanisms for organizing file sections into -logical pages and for formatting text forms. - ") - (defsection "Indenting Text" - (definition (:hemlock-variable "Indent Function") "Indent Function (initial value tab-to-tab-stop)" nil - (defsection "Description" - (para " -The value of this variable determines how indentation is done, and it -is a function which is passed a mark as its argument. The function -should indent the line that the mark points to. The function may move -the mark around on the line. The mark will be :left-inserting. The -default simply inserts a tab character at the mark. A function for -Lisp mode probably moves the mark to the beginning of the line, -deletes horizontal whitespace, and computes some appropriate -indentation for Lisp code. - "))) - (definition (:hemlock-variable "Indent with Tabs") "Indent with Tabs (initial value nil)" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Spaces per Tab") "Spaces per Tab (initial value 8)" nil - (defsection "Description" - (para " -Indent with Tabs should be true if indenting should use tabs -whenever possible. If nil, the default, it only uses spaces. -Spaces per Tab defines the size of a tab. - "))) - (definition (:function hemlock-interface:indent-region) "indent-region region" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:indent-region-for-commands) "indent-region-for-commands region" nil - (defsection "Description" - (para " -indent-region invokes the value of Indent Function on every line of -region. indent-region-for-commands uses indent-region but first saves -the region for the Undo command. - "))) - (definition (:function hemlock-interface:delete-horizontal-space) "delete-horizontal-space mark" nil - (defsection "Description" - (para " -This deletes all characters on either side of mark with a Space attribute (see {section System Defined Character Attributes}) of 1. - ")))) - (defsection "Lisp Text Buffers" - " -Hemlock bases its Lisp primitives on parsing a block of the buffer and -annotating lines as to what kind of Lisp syntax occurs on the line or -what kind of form a mark might be in (for example, string, comment, -list, etc.). These do not work well if the block of parsed forms is -exceeded when moving marks around these forms, but the block that gets -parsed is somewhat programmable. - - - -There is also a notion of a top level form which this documentation -often uses synonymously with defun, meaning a Lisp form occurring in a -source file delimited by parentheses with the opening parenthesis at -the beginning of some line. The names of the functions include this -inconsistency. - " - (definition (:function hemlock-interface:pre-command-parse-check) "pre-command-parse-check mark for-sure" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Parse Start Function") - "Parse Start Function (initial value start-of-parse-block)" nil (defsection "Description" (para " "))) - (definition (:hemlock-variable "Parse End Function") "Parse End Function (initial value end-of-parse-block)" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Minimum Lines Parsed") "Minimum Lines Parsed (initial value 50)" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Maximum Lines Parsed") "Maximum Lines Parsed (initial value 500)" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Defun Parse Goal") "Defun Parse Goal (initial value 2)" nil - (defsection "Description" - " -pre-command-parse-check calls Parse Start Function and Parse End -Function on mark to get two marks. It then parses all the lines -between the marks including the complete lines they point into. When -for-sure is non-nil, this parses the area regardless of any cached -information about the lines. Every command that uses the following -routines calls this before doing so. - - - -The default values of the start and end variables use Minimum Lines -Parsed, Maximum Lines Parsed, and Defun Parse Goal to determine how -big a region to parse. These two functions always include at least the -minimum number of lines before and after the mark passed to them. They -try to include Defun Parse Goal number of top level forms before and -after the mark passed them, but these functions never return marks -that include more than the maximum number of lines before or after the -mark passed to them. - ")) - (definition (:function hemlock-interface:form-offset) "form-offset mark count" nil - (defsection "Description" - (para " -This tries to move mark count forms forward if positive or -count -forms backwards if negative. Mark is always moved. If there were -enough forms in the appropriate direction, this returns mark, -otherwise nil. - "))) - (definition (:function hemlock-interface:top-level-offset) "top-level-offset mark count" nil - (defsection "Description" - (para " -This tries to move mark count top level forms forward if positive or --count top level forms backwards if negative. If there were enough top -level forms in the appropriate direction, this returns mark, otherwise -nil. Mark is moved only if this is successful. - "))) - (definition (:function hemlock-interface:mark-top-level-form) "mark-top-level-form mark1 mark2" nil - (defsection "Description" - (para " -This moves mark1 and mark2 to the beginning and end, respectively, of -the current or next top level form. Mark1 is used as a reference to -start looking. The marks may be altered even if unsuccessful. If -successful, return mark2, else nil. Mark2 is left at the beginning of -the line following the top level form if possible, but if the last -line has text after the closing parenthesis, this leaves the mark -immediately after the form. - "))) - (definition (:function hemlock-interface:defun-region) "defun-region mark" nil - (defsection "Description" - (para " -This returns a region around the current or next defun with respect to -mark. Mark is not used to form the region. If there is no appropriate -top level form, this signals an editor-error. This calls -pre-command-parse-check first. - "))) - (definition (:function hemlock-interface:inside-defun-p) "inside-defun-p mark" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:start-defun-p) "start-defun-p mark" nil - (defsection "Description" - (para " -These return, respectively, whether mark is inside a top level form or -at the beginning of a line immediately before a character whose Lisp -Syntax (see {section System Defined Character Attributes}) -value is :opening-paren. - "))) - (definition (:function hemlock-interface:forward-up-list) "forward-up-list mark" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:backward-up-list) "backward-up-list mark" nil - (defsection "Description" - (para " -Respectively, these move mark immediately past a character whose Lisp -Syntax (see {section System Defined Character Attributes}) -value is :closing-paren or immediately before -a character whose Lisp Syntax value is :opening-paren. - "))) - (definition (:function hemlock-interface:valid-spot) "valid-spot mark forwardp" nil - (defsection "Description" - (para " -This returns t or nil depending on whether the character indicated by -mark is a valid spot. When forwardp is set, use the character after -mark and vice versa. Valid spots exclude commented text, inside -strings, and character quoting. - "))) - (definition (:function hemlock-interface:defindent) "defindent name count" nil - (defsection "Description" - (para " -This defines the function with name to have count special -arguments. indent-for-lisp, the value of " - (ref (definition :hemlock-variable "Indent Function")) #:| -in Lisp mode, uses this to specially indent these arguments. For -example, do has two, with-open-file has one, etc. There are many of -these defined by the system including definitions for special Hemlock -forms. Name is a simple-string, case insensitive and purely textual -(that is, not read by the Lisp reader); therefore, "with-a-mumble" is -distinct from "mumble:with-a-mumble". - |)))) - (defsection "English Text Buffers" - (para " -This section describes some routines that understand basic English -language forms. - ") - (definition (:function hemlock-interface:word-offset) "word-offset mark count" nil - (defsection "Description" - (para " -This moves mark count words forward (if positive) or backwards (if -negative). If mark is in the middle of a word, that counts as one. If -there were count (-count if negative) words in the appropriate -direction, this returns mark, otherwise nil. This always moves mark. A -word lies between two characters whose Word Delimiter attribute value -is 1 (see {section System Defined Character Attributes}). - "))) - (definition (:function hemlock-interface:sentence-offset) "sentence-offset mark count" nil - (defsection "Description" - " -This moves mark count sentences forward (if positive) or backwards (if negative). If mark is in the middle of a sentence, that counts as one. If there were count (-count if negative) sentences in the appropriate direction, this returns mark, otherwise nil. This always moves mark. - - - -A sentence ends with a character whose Sentence Terminator attribute -is 1 followed by two spaces, a newline, or the end of the buffer. The -terminating character is optionally followed by any number of -characters whose Sentence Closing Char attribute is 1. A sentence -begins after a previous sentence ends, at the beginning of a -paragraph, or at the beginning of the buffer. - ")) - (definition (:function hemlock-interface:paragraph-offset) "paragraph-offset mark count {code &optional} prefix" - nil (defsection "Description" (para " "))) - (definition (:hemlock-variable "Paragraph Delimiter Function") "Paragraph Delimiter Function (initial value )" - nil - (defsection "Description" - " -This moves mark count paragraphs forward (if positive) or backwards -(if negative). If mark is in the middle of a paragraph, that counts as -one. If there were count (-count if negative) paragraphs in the -appropriate direction, this returns mark, otherwise nil. This only -moves mark if there were enough paragraphs. - - - -Paragraph Delimiter Function holds a function that takes a mark, -typically at the beginning of a line, and returns whether or not the -current line should break the paragraph. default-para-delim-function -returns t if the next character, the first on the line, has a -Paragraph Delimiter attribute value of 1. This is typically a space, -for an indented paragraph, or a newline, for a block style. Some modes -require a more complicated determinant; for example, Scribe modes adds -some characters to the set and special cases certain formatting -commands. - " - (para " -Prefix defaults to " - (ref (definition :hemlock-variable "Fill Prefix")) ", and the right -prefix is necessary to correctly skip paragraphs. If prefix is -non-nil, and a line begins with prefix, then the scanning process -skips the prefix before invoking the Paragraph Delimiter -Function. Note, when scanning for paragraph bounds, and prefix is -non-nil, lines are potentially part of the paragraph regardless of -whether they contain the prefix; only the result of invoking the -delimiter function matters. - ") - (para " -The programmer should be aware of an idiom for finding the end of the -current paragraph. Assume paragraphp is the result of moving mark one -paragraph, then the following correctly determines whether there -actually is a current paragraph: -" - (code-block " -(or paragraphp - (and (last-line-p mark) - (end-line-p mark) - (not (blank-line-p (mark-line mark))))) -")) - (para " -In this example mark is at the end of the last paragraph in the -buffer, and there is no last newline character in the -buffer. paragraph-offset would have returned nil since it could not -skip any paragraphs since mark was at the end of the current and last -paragraph. However, you still have found a current paragraph on which -to operate. mark-paragraph understands this problem. - "))) - (definition (:function hemlock-interface:mark-paragraph) "mark-paragraph mark1 mark2" nil - (defsection "Description" - (para " -This marks the next or current paragraph, setting mark1 to the -beginning and mark2 to the end. This uses " - (ref (definition :hemlock-variable "Fill Prefix")) ". -Mark1 is always on the first line of the paragraph, regardless -of whether the previous line is blank. Mark2 is typically at the -beginning of the line after the line the paragraph ends on, this -returns mark2 on success. If this cannot find a paragraph, then the -marks are left unmoved, and nil is returned. - ")))) - (defsection "Logical Pages" - (para " -Logical pages are not supported at this time. - ")) - (defsection "Filling" - (para " -Filling is an operation on text that breaks long lines at word -boundaries before a given column and merges shorter lines together in -an attempt to make each line roughly the specified length. This is -different from justification which tries to add whitespace in awkward -places to make each line exactly the same length. Hemlock's filling -optionally inserts a specified string at the beginning of each -line. Also, it eliminates extra whitespace between lines and words, -but it knows two spaces follow sentences. - ") - (definition (:hemlock-variable "Fill Column") "Fill Column (initial value 75)" nil - (defsection "Description" (para " "))) - (definition (:hemlock-variable "Fill Prefix") "Fill Prefix (initial value nil)" nil - (defsection "Description" - (para " -These variables hold the default values of the prefix and column -arguments to Hemlock's filling primitives. If Fill Prefix is nil, then -there is no fill prefix. - "))) - (definition (:function hemlock-interface:fill-region) "fill-region region {code &optional} prefix column" nil - (defsection "Description" - (para " -This deletes any blank lines in region and fills it according to -prefix and column. Prefix and column default to Fill Prefix and Fill -Column. - "))) - (definition (:function hemlock-interface:fill-region-by-paragraphs) - "fill-region-by-paragraphs region {code &optional} prefix column" nil - (defsection "Description" - (para " -This finds paragraphs within region and fills them -with fill-region. This ignores blank lines between paragraphs. Prefix -and column default to Fill Prefix and Fill Column. - "))))) - (defsection "Utilities" - (para " -This chapter describes a number of utilities for manipulating some -types of objects Hemlock uses to record information. String-tables are -used to store names of variables, commands, modes, and buffers. Ring -lists can be used to provide a kill ring, recent command history, or -other user-visible features. - ") - (defsection "String-table Functions" - " -String tables are similar to Common Lisp hash tables in that they -associate a value with an object. There are a few useful differences: -in a string table the key is always a case insensitive string, and -primitives are provided to facilitate keyword completion and -recognition. Any type of string may be added to a string table, but -the string table functions always return simple-string's. - - - -A string entry in one of these tables may be thought of as being -separated into fields or keywords. The interface provides keyword -completion and recognition which is primarily used to implement some -Echo Area commands. These routines perform a prefix match on a -field-by-field basis allowing the ambiguous specification of earlier -fields while going on to enter later fields. While string tables may -use any string-char as a separator, the use of characters other than -space may make the Echo Area commands fail or work unexpectedly. - " - (definition (:function hemlock-interface:make-string-table) "make-string-table" nil - (defsection "Description" - (para " -This function creates an empty string table that uses separator as the -character, which must be a string-char, that distinguishes -fields. Initial-contents specifies an initial set of strings and their -values in the form of a dotted a-list, for example: -" - (code-block #:| -'(("Global" . t) ("Mode" . t) ("Buffer" . t)) -|)))) - (definition (:function hemlock-interface:string-table-p) "string-table-p string-table" nil - (defsection "Description" - (para " -This function returns t if string-table is a string-table object, -otherwise nil. - "))) - (definition (:function hemlock-interface:string-table-separator) "string-table-separator string-table" nil - (defsection "Description" - (para " -This function returns the separator character given to -make-string-table. - "))) - (definition (:function hemlock-interface:delete-string) "delete-string string table" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:clrstring) "clrstring table" nil - (defsection "Description" - (para " -delete-string removes any entry for string from the string-table -table, returning t if there was an entry. clrstring removes all -entries from table. - "))) - (definition (:function hemlock-interface:getstring) "getstring string table" nil - (defsection "Description" - " -This function returns as multiple values, first the value -corresponding to the string if it is found and nil if it isn't, and -second t if it is found and nil if it isn't. - - - -This may be set with setf to add a new entry or to store a new value -for a string. It is an error to try to insert a string with more than -one field separator character occurring contiguously. - ")) - (definition (:function hemlock-interface:complete-string) "complete-string string tables" nil - (defsection "Description" - (para " -This function completes string as far as possible over the list of -tables, returning five values. It is an error for tables to have -different separator characters. The five return values are as follows: - ") - (listing :bullet - (item " -The maximal completion of the string or nil if there is none. - ")) - (listing :bullet - (item " -An indication of the usefulness of the returned string: - ")) - (listing :definition - (item ":none" ccldoc::=> " -There is no completion of string. - ") - (item ":complete" ccldoc::=> " -The completion is a valid entry, but other valid -completions exist too. This occurs when the supplied string is an -entry as well as initial substring of another entry. - ") - (item ":unique" ccldoc::=> " -The completion is a valid entry and unique. - ") - (item ":ambiguous" ccldoc::=> " -The completion is invalid; get-string would return nil -and nil if given the returned string. - ")) - (listing :bullet - (item " -The value of the string when the completion is :unique or -:complete, otherwise nil. - ")) - (listing :bullet - (item " -An index, or nil, into the completion returned, indicating where -the addition of a single field to string ends. The command Complete -Field uses this when the completion contains the addition to string -of more than one field. - ")) - (listing :bullet - (item " -An index to the separator following the first ambiguous field when -the completion is :ambiguous or :complete, otherwise nil. - ")))) - (definition (:function hemlock-interface:find-ambiguous) "find-ambiguous string table" nil - (defsection "Description" (para " "))) - (definition (:function hemlock-interface:find-containing) "find-containing string table" nil - (defsection "Description" - " -find-ambiguous returns a list in alphabetical order of all the strings -in table matching string. This considers an entry as matching if each -field in string, taken in order, is an initial substring of the -entry's fields; entry may have fields remaining. - - - -find-containing is similar, but it ignores the order of the fields in -string, returning all strings in table matching any permutation of the -fields in string. - ")) - (definition (:macro hemlock-interface:do-strings) - "do-strings (string-var value-var table result) declaration tag statement" nil - (defsection "Description" - (para " -This macro iterates over the strings in table in alphabetical -order. On each iteration, it binds string-var to an entry's string and -value-var to an entry's value. - ")))) - (defsection "Ring Functions" - (para " -There are various purposes in an editor for which a ring of values can -be used, so Hemlock provides a general ring buffer type. It is used -for maintaining a ring of " - (ref (section "Kill Ring") "killed regions") ", a ring of -" - (ref (section "The Current Buffer") "marks") ", or a ring of command strings which various -modes and commands maintain as a history mechanism. - ") - (definition (:function hemlock-interface:make-ring) "make-ring length {code &optional} delete-function" nil - (defsection "Description" - (para " -Makes an empty ring object capable of holding up to length Lisp -objects. Delete-function is a function that each object is passed to -before it falls off the end. Length must be greater than zero. - "))) - (definition (:function hemlock-interface:ringp) "ringp ring" nil - (defsection "Description" - (para " -Returns t if ring is a ring object, otherwise nil. - "))) - (definition (:function hemlock-interface:ring-length) "ring-length ring" nil - (defsection "Description" - (para " -Returns as multiple-values the number of elements which ring currently -holds and the maximum number of elements which it may hold. - "))) - (definition (:function hemlock-interface:ring-ref) "ring-ref ring index" nil - (defsection "Description" - (para " -Returns the index'th item in the ring, where zero is the index of the -most recently pushed. This may be set with setf. - "))) - (definition (:function hemlock-interface:ring-push) "ring-push object ring" nil - (defsection "Description" - (para " -Pushes object into ring, possibly causing the oldest item to go away. - "))) - (definition (:function hemlock-interface:ring-pop) "ring-pop ring" nil - (defsection "Description" - (para " -Removes the most recently pushed object from ring and returns it. If -the ring contains no elements then an error is signalled. - "))) - (definition (:function hemlock-interface:rotate-ring) "rotate-ring ring offset" nil - (defsection "Description" - (para " -With a positive offset, rotates ring forward that many times. In a -forward rotation the index of each element is reduced by one, except -the one which initially had a zero index, which is made the last -element. A negative offset rotates the ring the other way. - ")))) - (defsection "Undoing commands" - (para " -No API to the undo facility is provided at this time. - "))) - (defsection "Miscellaneous" - (para " -This chapter is somewhat of a catch-all for comments and features that -don't fit well anywhere else. - ") - (defsection "Key-events" - (defsection "Introduction" - (para " -The canonical representation of editor input is a key-event -structure. Users can bind commands to keys, which -are non-empty sequences of key-events. A key-event consists of -an identifying token known as a keysym and a field of bits -representing modifiers. Users define keysyms by supplying names -that reflect the legends on their keyboard's keys. -Users define modifier names similarly, but the system chooses the -bit and mask for recognizing the modifier. You can -use keysym and modifier names to textually specify key-events and -Hemlock keys in a #k syntax. The following are some examples: -" - (code-block #:| -#k"C-u" -#k"Control-u" -#k"c-m-z" -#k"control-x meta-d" -#k"a" -#k"A" -#k"Linefeed" -|)) - " -This is convenient for use within code and in init files containing -bind-key calls. - - - -The #k syntax is delimited by double quotes, but the system parses the -contents rather than reading it as a Common Lisp string. Within the -double quotes, spaces separate multiple key-events. A single key-event -optionally starts with modifier names terminated by hyphens. Modifier -names are alphabetic sequences of characters which the system uses -case-insensitively. Following modifiers is a keysym name, which is -case-insensitive if it consists of multiple characters, but if the -name consists of only a single character, then it is case-sensitive. - - - -You can escape special characters --- hyphen, double quote, open angle -bracket, close angle bracket, and space --- with a backslash, and you -can specify a backslash by using two contiguously. You can use angle -brackets to enclose a keysym name with many special characters in -it. Between angle brackets appearing in a keysym name position, there -are only two special characters, the closing angle bracket and -backslash. - ") - (defsection "Interface" - (definition (:function hemlock-interface:define-keysym) - "define-keysym keysym preferred-name {code &rest} other-names" nil - (defsection "Description" - " -This function establishes a mapping from preferred-name to keysym for -purposes of #k syntax. Other-names also map to keysym, but the system -uses preferred-name when printing key-events. The names are -case-insensitive simple-strings; however, if the string contains a -single character, then it is used case-sensitively. Redefining a -keysym or re-using names has undefined effects. - - - -Keysym can be any object, but generally it is either an integer -representing the window-system code for the event, or a keyword -which allows the mapping of the keysym to its code to be defined -separately. - ")) - (definition (:function hemlock-interface:define-keysym-code) "define-keysym-code keysym code" nil - (defsection "Description" - (para " -Defines the window-system code for the key event which in Hemlock is -represented by keysym. - "))) - (definition (:function hemlock-interface:define-mouse-keysym) - "define-mouse-keysym button keysym name shifted-bit event-key" nil - (defsection "Description" - (para " -This function defines keysym named name for key-events representing -mouse click events. Shifted-bit is a defined modifier name that -translate-mouse-key-event sets in the key-event it returns whenever -the shift bit is set in an incoming event. - "))) - (definition (:function hemlock-interface:name-keysym) "name-keysym name" nil - (defsection "Description" - (para " -This function returns the keysym named name. If name is unknown, this -returns nil. - "))) - (definition (:function hemlock-interface:keysym-names) "keysym-names keysym" nil - (defsection "Description" - (para " -This function returns the list of all names for keysym. If keysym is -undefined, this returns nil. - "))) - (definition (:function hemlock-interface:keysym-preferred-name) "keysym-preferred-name keysym" nil - (defsection "Description" - (para " -This returns the preferred name for keysym, how it is typically -printed. If keysym is undefined, this returns nil. - "))) - (definition (:function hemlock-interface:define-key-event-modifier) - "define-key-event-modifier long-name short-name" nil - (defsection "Description" - " -This establishes long-name and short-name as modifier names for -purposes of specifying key-events in #k syntax. The names are -case-insensitive strings. If either name is already defined, -this signals an error. - - - -The system defines the following default modifiers (first the long -name, then the short name): - " - (listing :bullet - (item #:| -"Hyper", "H" - |) - (item #:| -"Super", "S" - |) - (item #:| -"Meta", "M" - |) - (item #:| -"Control", "C" - |) - (item #:| -"Shift", "Shift" - |) - (item #:| -"Lock", "Lock" - |)))) - (definition (:variable hemlock-interface:*all-modifier-names*) "*all-modifier-names*" nil - (defsection "Description" - (para " -This variable holds all the defined modifier names. - "))) - (definition (:function hemlock-interface:make-key-event-bits) "make-key-event-bits {code &rest} modifier-names" - nil - (defsection "Description" - (para " -This function returns bits suitable for make-key-event from the -supplied modifier-names. If any name is undefined, this signals an -error. - "))) - (definition (:function hemlock-interface:key-event-modifier-mask) "key-event-modifier-mask modifier-name" nil - (defsection "Description" - (para " -This function returns a mask for modifier-name. This mask is suitable -for use with key-event-bits. If modifier-name is undefined, this -signals an error. - "))) - (definition (:function hemlock-interface:key-event-bits-modifiers) "key-event-bits-modifiers bits" nil - (defsection "Description" - (para " -This returns a list of key-event modifier names, one for each modifier -set in bits. - "))) - (definition (:function hemlock-interface:make-key-event) "make-key-event object bits" nil - (defsection "Description" - (para " -This function returns a key-event described by object with -bits. Object is one of keysym, string, or key-event. When object is a -key-event, this uses key-event-keysym. You can form bits with -make-key-event-bits or key-event-modifier-mask. - "))) - (definition (:function hemlock-interface:key-event-p) "key-event-p object" nil - (defsection "Description" - (para " -This function returns whether object is a key-event. - "))) - (definition (:function hemlock-interface:key-event-bits) "key-event-bits key-event" nil - (defsection "Description" - (para " -This function returns the bits field of a key-event. - "))) - (definition (:function hemlock-interface:key-event-keysym) "key-event-keysym key-event" nil - (defsection "Description" - (para " -This function returns the keysym field of a key-event. - "))) - (definition (:function hemlock-interface:char-key-event) "char-key-event character" nil - (defsection "Description" - (para " -This function returns the key-event associated with character. You can -associate a key-event with a character by setf-ing this form. - "))) - (definition (:function hemlock-interface:key-event-char) "key-event-char key-event" nil - (defsection "Description" - (para #:| -This function returns the character associated with key-event. You can -associate a character with a key-event by setf'ing this form. The -system defaultly translates key-events in some implementation -dependent way for text insertion; for example, under an ASCII system, -the key-event #k"C-h", as well as #k"backspace" would map to the -Common Lisp character that causes a backspace. - |))) - (definition (:function hemlock-interface:key-event-bit-p) "key-event-bit-p key-event bit-name" nil - (defsection "Description" - (para " -This function returns whether key-event has the bit set named by -bit-name. This signals an error if bit-name is undefined. - "))) - (definition (:macro hemlock-interface:do-alpha-key-events) - "do-alpha-key-events (var kind {code &optional} result) form" nil - (defsection "Description" - (para " -This macro evaluates each form with var bound to a key-event -representing an alphabetic character. Kind is one of :lower, :upper, -or :both, and this binds var to each key-event in order a-z A-Z. -When :both is specified, this processes lowercase letters -first. - "))) - (definition (:function hemlock-interface:pretty-key-string) - "pretty-key-string key {code &optional} stream long-names-p" nil - (defsection "Description" - (para " -This returns a string representing key, a key-event or vector of key-events, in a -user-expected fashion. Long-names-p indicates whether -modifiers should be described by their long or short name. - "))))))) \ No newline at end of file diff --git a/ccl-documentation/ide.ccldoc b/ccl-documentation/ide.ccldoc deleted file mode 100644 index c2bc762..0000000 --- a/ccl-documentation/ide.ccldoc +++ /dev/null @@ -1,369 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "The {CCL} IDE" - (defsection "Introduction" - #:|{CCL} ships with the complete source code for an integrated - development environment written using Cocoa on Mac OS X. This - chapter describes how to build and use that environment, - referred to hereafter simply as "the IDE". - - The IDE provides a programmable text editor, listener - windows, an inspector for Lisp data structures, and a means of - easily building a Cocoa application in Lisp. In addition, its - source code provides an example of a fairly complex Cocoa - application written in Lisp. - - The current version of the IDE has seen the addition of numerous - features and many bugfixes. Although it's by no means a finished product, - we hope it will prove more useful than previous versions, and we - plan additional work on the IDE for future releases.|) - (defsection "Building the IDE" - (para "Building the {CCL} IDE is now a very simple - process.") - (listing :number - (item "In a shell session, cd to the ccl directory.") - (item "Run ccl from the shell. The easiest way to do this is - generally to execute the ccl or ccl64 command.") - (item "Evaluate the form {code (require :cocoa-application)}")) - (para #:|For example, assuming that the {CCL} distribution is - installed in "/usr/local/ccl", the following sequence of shell - interactions builds the IDE:|) - (code-block #:| -oshirion:ccl mikel$ ccl64 -Welcome to Clozure Common Lisp Version 1.2-r9198M-trunk (DarwinX8664)! -? (require :cocoa-application) -;Loading #P"ccl:cocoa-ide;fasls;cocoa-utils.dx64fsl.newest"... -;Loading #P"ccl:cocoa-ide;fasls;cocoa-defaults.dx64fsl.newest"... - -[...many lines of "Compiling" and "Loading" omitted...] - -Saving application to /usr/local/ccl/Clozure CL.app/ - -oshirion:ccl mikel$ - - |) - (para #:|{CCL} compiles and loads the various subsystems that - make up the IDE, then constructs a Cocoa application bundle - named "Clozure CL.app" and saves the Lisp image into - it. Normally {CCL} creates the application bundle in the root - directory of the {CCL} distribution.|)) - (defsection "Running the IDE" - (para #:|After it has been built, you can run the "Clozure CL.app" - application normally, by double-clicking its icon. When - launched, the IDE initially displays a - single | - (term "listener window") " that you can use to interact with Lisp. You - can type Lisp expressions for evaluation at the prompt in the - listener window. You can also - use " - (term "Hemlock") " editing - commands to edit the text of expressions in the listener - window.")) - (defsection "IDE Features" - (defsection "Editor Windows" - (para "You can open an editor window either by choosing Open from - the File menu and then selecting a text file, or by choosing - New from the File menu. You can also evaluate the - expression {code (ed)} in the listener window; in that - case {CCL} creates a new window as if you had chosen New from - the File menu.") - (para "Editor windows - implement " - (term "Hemlock") " - editing commands. You can use all the editing and customization - features of Hemlock within any editor window (including listener - windows).")) - (defsection "The Lisp Menu" - (para "The Lisp menu provides several commands for interacting - with the running Lisp session, in addition to the ways you can - interact with it by evaluating expressions. You can evaluate a - selected range of text in any editing buffer. You can compile - and load the contents of editor windows (please note that in the - current version, {CCL} compiles and loads the contents of the - file associated with an editor window; that means that if you - try to load or compile a window that has not been saved to a - file, the result is an error).") - (para "You can interrupt computations, trigger breaks, and select - restarts from the Lisp menu. You can also display a backtrace or - open the " - (ref (section "The Inspector Window") "Inspector window") ".") - (defsection "Checking for Updates" - #:|At the bottom of the Lisp menu is an item entitled - "Check for Updates". If your copy of {CCL} came from the - Clozure Subversion server (which is the preferred source), and - if your internet connection is working, then you can select - this menu item to check for updates to your copy of - {CCL}. - - When you select "Check for Updates", {CCL} uses the svn - program to query the Clozure Subversion repository and - determine whether new updates to {CCL} are available. (This - means that on Mac OS X versions earlier than 10.5, you must - ensure that the Subversion client software is installed before - using the "Check for Updates" feature. See - the {link http://www.wikihow.com/Install-Subversion-on-Mac-OS-X wikiHow - page} on installing Subversion for more information.) - If updates are available, {CCL} automatically downloads and - installs them. After a successful download, {CCL} rebuilds - itself, and then rebuilds the IDE on the newly-rebuilt - Lisp. Once this process is finished, you should quit the - running IDE and start the newly built one (which will be in - the same place that the old one was). - - Normally, {CCL} can install updates and rebuild itself - without any problems. Occasionally, an unforeseen problem - (such as a network outage, or a hardware failure) might - interrupt the self-rebuilding process, and leave your copy of - {CCL} unusable. If you are expecting to update your copy of - {CCL} frequently, it might be prudent to keep a backup copy of - your working environment ready in case of such - situtations. You can also always obtain a full, fresh copy of - {CCL} from Clozure's repository..|)) - (defsection "The Tools Menu" - (para "The tools menu provides access to the Apropos and - Processes windows. The Apropos window searches the running Lisp - image for symbols that match any text you enter. You can use the - Apropos window to quickly find function names and other useful - symbols. The Processes window lists all threads running in the - current Lisp session. If you double-click a process entry, {CCL} - opens an " - (ref (section "The Inspector Window") "Inspector window") " on that process.")) - (defsection "The Inspector Window" - "The Inspector window displays information about a Lisp - value. The information displayed varies from the very simple, in - the case of a simple data value such as a character, to the - complex, in the case of structured data such as lists or CLOS - objects. The left-hand column of the window's display shows the - names of the object's attributes; the righthand column shows the - values associated with those attributes. You can inspect the - values in the righthand column by double-clicking them. - - Inspecting a value in the righthand column changes the - Inspector window to display the double-clicked object. You can - quickly navigate the fields of structured data this way, - inspecting objects and the objects that they refer - to. Navigation buttons at the top left of the window enable you - to retrace your steps, backing up to return to previously-viewed - objects, and going forward again to objects you navigated into - previously. - - You can change the contents of a structured object by - evaluating expressions in a listener window. The refresh button - (marked with a curved arrow) updates the display of the - Inspector window, enabling you to quickly see the results of - changing a data structure.")) - (defsection "IDE Sources" - #:|{CCL} builds the IDE from sources in the "objc-bridge" and - "cocoa-ide" directories in the {CCL} distribution. The IDE as a - whole is a relatively complicated application, and is probably not - the best place to look when you are first trying to understand how - to build Cocoa applications. For that, you might benefit more from - the examples in the "examples/cocoa/" directory. Once you are - familiar with those examples, though, and have some experience - building your own application features using Cocoa and the - Objective-C bridge, you might browse through the IDE sources to - see how it implements its features. - - The search path for {CCL}'s {code REQUIRE} feature - includes the "objc-bridge" and "cocoa-ide" directories. You can - load features defined in these directories by - using {code REQUIRE}. For example, if you want to use the - Cocoa features of {CCL} from a terminal session (or from an Emacs - session using SLIME or ILISP), you can evaluate {code (require - :cocoa)}.|) - (defsection "The Application Builder" - (para "One important feature of the IDE currently has no Cocoa user - interface: the application builder. The application builder - constructs a - Cocoa " - (term "application bundle") " that runs a Lisp image when double-clicked. You - can use the application builder to create Cocoa applications in - Lisp. These applications are exactly like Cocoa applications - created with XCode and Objective-C, except that they are written - in Lisp.") - (para "To make the application builder available, evaluate the - expression {code (require :build-application)}. {CCL} loads - the required subsystems, if necessary.") - (definition (:function ccl::build-application) - #:|BUILD-APPLICATION {code &key} ( name "MyApplication" ) ( type-string "APPL" ) ( creator-string "OMCL" ) ( directory (current-directory) ) ( copy-ide-resources t ) ( info-plist NIL ) ( nibfiles NIL ) ( main-nib-name NIL ) ( application-class 'GUI::COCOA-APPLICATION ) ( toplevel-function NIL )| - nil - (defsection "Description" - " - The {variable ccl::build-application} function constructs an - application bundle, populates it with the files needed to satisfy - Mac OS X that the bundle is a launchable application, and saves an - executable Lisp image to the proper subdirectory of the - bundle. Assuming that the saved Lisp image contains correct code, - a user can subsequently launch the resulting Cocoa application by - double-clicking its icon in the Finder, and the saved Lisp - environment runs. - - - The keyword arguments control various aspects of application - bundle as {code BUILD-APPLICATION} builds it." - (listing :definition - (item "{param name}" ccldoc::=> #:|Specifies the application name of the - bundle. {code BUILD-APPLICATION} creates an application - bundle whose name is given by this parameter, with the - extension ".app" appended. For example, using the default - value for this parameter results in a bundle named - "MyApplication.app".|) - (item "{param type-string}" ccldoc::=> "Specifies type of bundle to create. You should normally - never need to change the default value, which Mac OS X uses to - identify application bundles.") - (item "{param creator-string}" ccldoc::=> "Specifies the " (term "creator code") - ", which uniquely identifies the application - under Mac OS X. The default creator code is that of {CCL}. For - more information about reserving and assigning creator codes, - see - Apple's {link http://developer.apple.com/datatype/index.html developer - page} on the topic.") - (item "{param directory}" ccldoc::=> #:|The directory in which {code BUILD-APPLICATION} - creates the application bundle. By default, it creates the - bundle in the current working directory. Unless you - use {code CURRENT-DIRECTORY} to set the working - directory, the bundle may be created in some unexpected place, - so it's safest to specify a full pathname for this argument. A - typical value might be {code "/Users/foo/Desktop/"} - (assuming, of course, that your username is "foo").|) - (item "{param copy-ide-resources}" ccldoc::=> "Whether to copy the resource files from the IDE's - application bundle. By - default, {code BUILD-APPLICATION} copies nibfiles - and other resources from the IDE to the newly-created - application bundle. This option is often useful when you - are developing a new application, because it enables your - built application to have a fully-functional user - interface even before you have finished designing one. By - default, the application uses the application menu and - other UI elements of the IDE until you specify - otherwise. Once your application's UI is fully - implemented, you may choose to pass {code NIL} - for the value of this parameter, in which case the IDE - resources are not copied into your application - bundle.") - (item "{param info-plist}" ccldoc::=> #:|A user-supplied NSDictionary object that defines the - contents of the Info.plist file to be written to the - application bundle. The default value - is {code NIL}, which specifies that the - Info.plist from the IDE is to be used - if {sample copy-ide-resources} is true, - and a new dictionary created with default values is to be - used otherwise. You can create a suitable NSDictionary - object using the - function {code make-info-dict}. For details on - the parameters to this function, see its definition in - "ccl/cocoa-ide/builder-utilities.lisp".|) - (item "{param nibfiles}" ccldoc::=> "A list of pathnames, where each pathname identifies - a " - (term "nibfile") " created - with - Apple's " - (term "InterfaceBuilder") #:| - application. {code BUILD-APPLICATION} copies each - nibfile into the appropriate place in the application bundle, - enabling the application to load user-interface elements from - them as-needed. It is safest to provide full pathnames to the - nibfiles in the list. Each nibfile must be in ".nib" format, - not ".xib" format, in order that the application can load - it.|) - (item "{param main-nib-name}" ccldoc::=> "The name of - the " - (term "nibfile") " to load - initially when launching. The user-interface defined in this - nibfile becomes the application's main interface. You must - supply the name of a suitable nibfile for this parameter, or - the resulting application uses the {CCL} user - interface.") - (item "{param application-class}" ccldoc::=> "The name of the application's CLOS class. The default - value is the class provided by {CCL} for graphical - applications. Supply the name of your application class if you - implement one. If not, {CCL} uses the default class.") - (item "{param toplevel-function}" ccldoc::=> #:|The toplevel function that runs when the application - launches. Normally the default value, which is {CCL}'s - toplevel, works well, but in some cases you may wish to - customize the behavior of the application's toplevel. The best - source of information about writing your own toplevel is the - {CCL} source code, especially the implementations - of {code TOPLEVEL-FUNCTION} in - "ccl/level-1/l1-application.lisp"|)) - #:|{code BUILD-APPLICATION} creates a folder named - "{sample name}.app" in the - directory {sample directory}. Inside that - folder, it creates the "Contents" folder that Mac OS X - application bundles are expected to contain, and populates it - with the "MacOS" and "Resources" folders, and the "Info.plist" - and "PkgInfo" files that must be present in a working - application bundle. It takes the contents of the "Info.plist" - and "PkgInfo" files from the parameters - to {code BUILD-APPLICATION}. If {sample copy-ide-resources} - is true then it copies the contents of the "Resources" folder - from the "Resources" folder of the running IDE. - - The work needed to produce a running Cocoa application is - very minimal. In fact, if you - supply {code BUILD-APPLICATION} with a valid nibfile and - pathnames, it builds a running Cocoa application that displays - your UI. It doesn't need you to write any code at all to do - this. Of course, the resulting application doesn't do anything - apart from displaying the UI defined in the nibfile. If you want - your UI to accomplish anything, you need to write the code to - handle its events. But the path to a running application with your - UI in it is very short indeed. - - Please note that {code BUILD-APPLICATION} is a work in - progress. It can easily build a working Cocoa application, but it - still has limitations that may in some cases prove - inconvenient. For example, in the current version it provides no - easy way to specify an application delegate different from the - default. If you find the current limitations - of {code BUILD-APPLICATION} too restrictive, and want to try - extending it for your use, you can find the source code for it in - "ccl/cocoa-ide/build-application.lisp". You can see the default - values used to populate the "Info.plist" file in - "ccl/cocoa-ide/builder-utilities.lisp". - - For more information on how to - use {code BUILD-APPLICATION}, see the Currency Converter - example in "ccl/examples/cocoa/currency-converter/".|)) - (defsection "Running the Application Builder From the Command - Line" - (para #:|It's possible to automate use of the application builder - by running a call to {code CCL:BUILD-APPLICATION} - from the terminal command line. For example, the following - command, entered at a shell prompt in Mac OS X's Terminal - window, builds a working copy of the {CCL} environment called - "Foo.app":|) - (code-block #:| -ccl -b -e "(require :cocoa)" -e "(require :build-application)" -e "(ccl::build-application :name \\"Foo\\")" - |) - #:|You can use the same method to automate building your - Lisp/Cocoa applications. {CCL} handles each Lisp expressions - passed with a {code -e} argument in order, so you - can simply evaluate a sequence of Lisp expressions as in the - above example to build your application, ending with a call - to {code CCL:BUILD-APPLICATION}. The call - to {code CCL:BUILD-APPLICATION} can process all the - same arguments as if you evaluated it in a Listener window in - the {CCL} IDE. - - Building a substantial Cocoa application (rather than just - reproducing the Lisp environment using defaults, as is done in - the above example) is likely to involve a relatively complicated - sequence of loading source files and perhaps evaluating Lisp - forms. You might be best served to place your command line in a - shell script that you can more easily edit and test. - - One potentially complicated issue concerns loading all - your Lisp source files in the right order. You might consider - using ASDF to define and load a system that includes all the - parts of your application before - calling {code CCL:BUILD-APPLICATION}. ASDF is a - "another system-definition facility", a sort - of {code make} for Lisp, and is included in the - {CCL} distribution. You can read more about ASDF at the ASDF - {link http://common-lisp.net/project/asdf/ home - page}. - - Alternatively, you could use the standard features of - Common Lisp to load your application's files in the proper - order.|))) \ No newline at end of file diff --git a/ccl-documentation/implementation.ccldoc b/ccl-documentation/implementation.ccldoc deleted file mode 100644 index 67e3095..0000000 --- a/ccl-documentation/implementation.ccldoc +++ /dev/null @@ -1,1386 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Implementation Details of {CCL}" - (para #:|This chapter describes many aspects of OpenMCL's - implementation as of (roughly) version 1.1. Details vary a bit - between the three architectures (PPC32, PPC64, and x86-64) - currently supported and those details change over time, so the - definitive reference is the source code (especially some files in - the ccl/compiler/ directory whose names contain the string "arch" - and some files in the ccl/lisp-kernel/ directory whose names - contain the string "constants".) Hopefully, this chapter will make - it easier for someone who's interested to read and understand the - contents of those files.|) - (defsection "Threads and exceptions" - #:|{CCL}'s threads are "native" (meaning that they're - scheduled and controlled by the operating system.) Most of the - implications of this are discussed elsewhere; this section tries - to describe how threads look from the lisp kernel's perspective - (and especially from the GC's point of view.) - - {CCL}'s runtime system tries to use machine-level - exception mechanisms (conditional traps when available, - illegal instructions, memory access protection in some cases) - to detect and handle exceptional situations. These situations - include some TYPE-ERRORs and PROGRAM-ERRORS (notably - wrong-number-of-args errors), and also include cases like "not - being able to allocate memory without GCing or obtaining more - memory from the OS." The general idea is that it's usually - faster to pay (very occasional) exception-processing overhead - and figure out what's going on in an exception handler than it - is to maintain enough state and context to handle an - exceptional case via a lighter-weight mechanism when that - exceptional case (by definition) rarely occurs. - - Some emulated execution environments (the Rosetta PPC - emulator on x86 versions of Mac OS X) don't provide accurate - exception information to exception handling functions. {CCL} - can't run in such environments.| - (defsection "The Thread Context Record" - #:|When a lisp thread is first created (or when a thread - created by foreign code first calls back to lisp), a data - structure called a Thread Context Record (or TCR) is - allocated and initialized. On modern versions of Linux and - FreeBSD, the allocation actually happens via a set of - thread-local-storage ABI extensions, so a thread's TCR is - created when the thread is created and dies when the thread - dies. (The World's Most Advanced Operating System-as - Apple's marketing literature refers to Darwin-is not - very advanced in this regard, and I know of no reason to - assume that advances will be made in this area anytime - soon.) - - A TCR contains a few dozen fields (and is therefore a - few hundred bytes in size.) The fields are mostly - thread-specific information about the thread's stacks' - locations and sizes, information about the underlying (POSIX) - thread, and information about the thread's dynamic binding - history and pending CATCH/UNWIND-PROTECTs. Some of this - information could be kept in individual machine registers - while the thread is running (and the PPC - which has more - registers available - keeps a few things in registers that the - X86-64 has to access via the TCR), but it's important to - remember that the information is thread-specific and can't - (for instance) be kept in a fixed global memory - location. - - When lisp code is running, the current thread's TCR is - kept in a register. On PPC platforms, a general purpose - register is used; on x86-64, an (otherwise nearly useless) - segment register works well (prevents the expenditure of a - more generally useful general- purpose register for this - purpose.) - - The address of a TCR is aligned in memory in such a way - that a FIXNUM can be used to represent it. The lisp function - CCL::%CURRENT-TCR returns the calling thread's TCR as a - fixnum; actual value of the TCR's address is 4 or 8 times the - value of this fixnum. - - When the lisp kernel initializes a new TCR, it's added - to a global list maintained by the kernel; when a thread - exits, its TCR is removed from this list. - - When a thread calls foreign code, lisp stack pointers - are saved in its TCR, lisp registers (at least those whose - value should be preserved across the call) are saved on the - thread's value stack, and (on x86-64) RSP is switched to the - control stack. A field in the TCR (tcr.valence) is then set - to indicate that the thread is running foreign code, foreign - argument registers are loaded from a frame on the foreign - stack, and the foreign function is called. (That's a little - oversimplified and possibly inaccurate, but the important - things to note are that the thread "stops following lisp - stack and register usage conventions" and that it advertises - the fact that it's done so. Similar transitions in a - thread's state ("valence") occur when it enters or exits an - exception handler (which is sort of an OS/hardware-mandated - foreign function call where the OS thoughtfully saves the - thread's register state for it beforehand.)|) - (defsection "Exception contexts, and exception-handling in general" - #:|Unix-like OSes tend to refer to exceptions as "signals"; - the same general mechanism ("signal handling") is used to - process both asynchronous OS-level events (such as the result - of the keyboard driver noticing that ^C or ^Z has been - pressed) and synchronous hardware-level events (like trying to - execute an illegal instruction or access protected memory.) - It makes some sense to defer ("block") handling of - asynchronous signals so that some critical code sequences - complete without interruption; since it's generally not - possible for a thread to proceed after a synchronous exception - unless and until its state is modified by an exception - handler, it makes no sense to talk about blocking synchronous - signals (though some OSes will let you do so and doing so can - have mysterious effects.) - - On OSX/Darwin, the POSIX signal handling facilities - coexist with lower-level Mach-based exception handling - facilities. Unfortunately, the way that this is implemented - interacts poorly with debugging tools: GDB will generally stop - whenever the target program encounters a Mach-level exception - and offers no way to proceed from that point (and let the - program's POSIX signal handler try to handle the exception); - Apple's CrashReporter program has had a similar issue and, - depending on how it's configured, may bombard the user with - alert dialogs which falsely claim that an application has - crashed (when in fact the application in question has - routinely handled a routine exception.) On Darwin/OSX, - {CCL} uses Mach thread-level exception handling facilities - which run before GDB or CrashReporter get a chance to confuse - themselves; {CCL}'s Mach exception handling tries to force - the thread which received a synchronous exception to invoke a - signal handling function ("as if" signal handling worked more - usefully under Darwin.) Mach exception handlers run in a - dedicated thread (which basically does nothing but wait for - exception messages from the lisp kernel, obtain and modify - information about the state of threads in which exceptions - have occurred, and reply to the exception messages with an - indication that the exception has been handled. The reply - from a thread-level exception handler keeps the exception from - being reported to GDB or CrashReporter and avoids the problems - related to those programs. Since {CCL}'s Mach exception - handler doesn't claim to handle debugging-related exceptions - (from breakpoints or single-step operations), it's possible to - use GDB to debug {CCL}. - - On platforms where signal handling and debugging don't - get in each other's way, a signal handler is entered with - all signals blocked. (This behavior is specified in the - call to the sigaction() function which established the - signal handler.) The signal handler receives three - arguments from the OS kernel; the first is an integer that - identifies the signal, the second is a pointer to an object - of type "siginfo_t", which may or may not contain a few - fields that would help to identify the cause of the - exception, and the third argument is a pointer to a data - structure (called a "ucontext" or something similar), which - contains machine-dependent information about the state of - the thread at the time that the exception/signal occurred. - While asynchronous signals are blocked, the signal handler - stores the pointer to its third argument (the "signal - context") in a field in the current thread's TCR, sets some - bits in another TCR field to indicate that the thread is now - waiting to handle an exception, unblocks asynchronous - signals, and waits for a global exception lock that - serializes exception processing. - - On Darwin, the Mach exception thread creates a signal - context (and maybe a siginfo_t structure), stores the signal - context in the thread's TCR, sets the TCR field which describes - the thread's state, and arranges that the thread resume - execution at its signal handling function (with a signal - handler, possibly NULL siginfo_t, and signal context as - arguments. When the thread resumes, it waits for the global - exception lock. - - On x86-64 platforms where signal handing can be used to - handle synchronous exceptions, there's an additional - complication: the OS kernel ordinarily allocates the signal - context and siginfo structures on the stack of the thread - that received the signal; in practice, that means "wherever - RSP is pointing." {CCL}'s - {section Register and stack usage conventions} - require that the thread's value stack-where RSP is - usually pointing while lisp code is running-contain - only "nodes" (properly tagged lisp objects), and scribbling - a signal context all over the value stack would violate this - requirement. To maintain consistency, the sigaltstack() - mechanism is used to cause the signal to be delivered on - (and the signal context and siginfo to be allocated on) a - special stack area (the last few pages of the thread's - control stack, in practice). When the signal handler runs, - it (carefully) copies the signal context and siginfo to the - thread's control stack and makes RSP point into that stack - before invoking the "real" signal handler. The effect of - this hack is that the "real" signal handler always runs on - the thread's control stack. - - Once the exception handler has obtained the global - exception lock, it uses the values of the signal number, - siginfo_t, and signal context arguments to determine the - (logical) cause of the exception. Some exceptions may be - caused by factors that should generate lisp errors or other - serious conditions (stack overflow); if this is the case, the - kernel code may release the global exception lock and call out - to lisp code. (The lisp code in question may need to repeat - some of the exception decoding process; in particular, it - needs to be able to interpret register values in the signal - context that it receives as an argument.) - - In some cases, the lisp kernel exception handler may not - be able to recover from the exception (this is currently true - of some types of memory-access fault and is also true of traps - or illegal instructions that occur during foreign code - execution. In such cases, the kernel exception handler - reports the exception as "unhandled", and the kernel debugger - is invoked. - - If the kernel exception handler identifies the - exception's cause as being a transient out-of-memory condition - (indicating that the current thread needs more memory to cons - in), it tries to make that memory available. In some cases, - doing so involves invoking the GC.|) - (defsection "Threads, exceptions, and the GC" - #:|{CCL}'s GC is not concurrent: when the GC is invoked in - response to an exception in a particular thread, all other - lisp threads must stop until the GC's work is done. The - thread that triggered the GC iterates over the global TCR - list, sending each other thread a distinguished "suspend" - signal, then iterates over the list again, waiting for a - per-thread semaphore that indicates that the thread has - received the "suspend" signal and responded appropriately. - Once all other threads have acknowledged the request to - suspend themselves, the GC thread can run the GC proper (after - doing any necessary {section PC-lusering}.) Once the - GC's completed its work, the thread that invoked the GC - iterates over the global TCR list, raising a per-thread - "resume" semaphore for each other thread. - - The signal handler for the asynchronous "suspend" signal - is entered with all asynchronous signals blocked. It saves - its signal-context argument in a TCR slot, raises the tcr's - "suspend" semaphore, then waits on the TCR's "resume" - semaphore. - - The GC thread has access to the signal contexts of all - TCRs (including its own) at the time when the thread received - an exception or acknowledged a request to suspend itself. - This information (and information about stack areas in the TCR - itself) allows the GC to identify the "stack locations and - register contents" that are elements of the GC's root - set.|) - (defsection "PC-lusering" - (para "It's not quite accurate to say that {CCL}'s compiler - and runtime follow precise stack and register usage - conventions at all times; there are a few exceptions:") - (listing :bullet - (item "On both PPC and x86-64 platforms, consing isn't - fully atomic.It takes at least a few instructions to - allocate an object in memory(and slap a header on it if - necessary); if a thread is interrupted in the middle of - that instruction sequence, the new object may or may - not have been created or fully initialized at the point in - time that the interrupt occurred. (There are actually a - few different states of partial initialization)") - (item "On the PPC, the common act of building a lisp - control stack frame involves allocating a four-word frame - and storing three register values into that frame. (The - fourth word - the back pointer to the previous frame - is - automatically set when the frame is allocated.) The - previous contents of those three words are unknown (there - might have been a foreign stack frame at the same address a - few instructions earlier),so interrupting a thread that's - in the process of initializing a PPC control stack frame - isn't GC-safe.") - (item "There are similar problems with the initialization - of temp stackframes on the PPC. (Allocation and - initialization doesn't happen atomically, and the newly - allocated stack memory may have undefined contents.)") - (item "{section The ephemeral GC}'s write barrier - has to be implemented atomically (i.e.,both an - intergenerational store and the update of a - corresponding reference bit has to happen without - interruption, or neither of these events can - happen.)") - (item "There are a few more similar cases.")) - "Fortunately, the number of these non-atomic instruction - sequences is small, and fortunately it's fairly easy for the - interrupting thread to recognize when the interrupted thread - is in the middle of such a sequence. When this is detected, - the interrupting thread modifies the state of the interrupted - thread (modifying its PC and other registers) so that it is no - longer in the middle of such a sequence (it's either backed - out of it or the remaining instructions are emulated.) - - This works because (a) many of the troublesome - instruction sequences are PPC-specific and it's relatively - easy to partially disassemble the instructions surrounding the - interrupted thread's PC on the PPC and (b) those instruction - sequences are heavily stylized and intended to be easily - recognized.")) - (defsection "Register usage and tagging" - (defsection "Overview" - #:|Regardless of other details of its implementation, a - garbage collector's job is to partition the set of all - heap-allocated lisp objects (CONSes, STRINGs, INSTANCEs, etc.) - into two subsets. The first subset contains all objects that - are transitively referenced from a small set of "root" objects - (the contents of the stacks and registers of all active - threads at the time the GC occurs and the values of some - global variables.) The second subset contains everything - else: those lisp objects that are not transitively reachable - from the roots are garbage, and the memory occupied by garbage - objects can be reclaimed (since the GC has just proven that - it's impossible to reference them.) - - The set of live, reachable lisp objects basically form - the nodes of a (usually large) graph, with edges from each - node A to any other objects (nodes) that object A - references. - - Some nodes in this graph can never have outgoing edges: - an array with a specialized numeric or character type usually - represents its elements in some (possibly more compact) - specialized way. Some nodes may refer to lisp objects that - are never allocated in memory (FIXNUMs, CHARACTERs, - SINGLE-FLOATs on 64-bit platforms ..) This latter class of - objects are sometimes called "immediates", but that's a little - confusing because the term "immediate" is sometimes used to - refer to things that can never be part of the big connectivity - graph (e.g., the "raw" bits that make up a floating-point - value, foreign address, or numeric value that needs to be used - - at least fleetingly - in compiled code.) - - For the GC to be able to build the connectivity graph - reliably, it's necessary for it to be able to reliably tell - (a) whether or not a "potential root" - the contents of a - machine register or stack location - is in fact a node and (b) - for any node, whether it may have components that refer to - other nodes. - - There's no reliable way to answer the first question on - stock hardware. (If everything was a node, as might be the - case on specially microcoded "lisp machine" hardware, it - wouldn't even need to be asked.) Since there's no way to just - look at a machine word (the contents of a machine register or - stack location) and tell whether or not it's a node or just - some random non-node value, we have to either adopt and - enforce strict conventions on register and stack usage or - tolerate ambiguity. - - "Tolerating ambiguity" is an approach taken by some - ("conservative") GC schemes; by contrast, {CCL}'s GC is - "precise", which in this case means that it believes that the - contents of certain machine registers and stack locations are - always nodes and that other registers and stack locations are - never nodes and that these conventions are never violated by - the compiler or runtime system. The fact that threads are - preemptively scheduled means that a GC could occur (because of - activity in some other thread) on any instruction boundary, - which in turn means that the compiler and runtime system must - follow precise {section Register and stack usage conventions} at all - times. - - Once we've decided that a given machine word is a node, - a {section Tagging scheme} describes how the node's - value and type are encoded in that machine word. - - Most of this discussion-so far-has treated - things from the GC's very low-level perspective. From a much - higher point of view, lisp functions accept nodes as - arguments, return nodes as values, and (usually) perform - some operations on those arguments in order to produce those - results. (In many cases, the operations in question involve - raw non-node values.) Higher-level parts of the lisp type - system (functions like TYPE-OF and CLASS-OF, etc.) depend on - the {section Tagging scheme}.|) - (defsection "pc-locatives on the PPC" - #:|On the PPC, there's a third case (besides "node" and - "immediate" values). As discussed below, a node that denotes - a memory-allocated lisp object is a biased (tagged) pointer - -to- that object; it's not generally possible to point -into- - some composite (multi-element) object (such a pointer would - not be a node, and the GC would have no way to update the - pointer if it were to move the underlying object.) - - Such a pointer ("into" the interior of a heap-allocated - object) is often called a {emphasis locative}; the - cases where locatives are allowed in {CCL} mostly involve - the behavior of function call and return instructions. (To be - technically accurate, the other case also arises on x86-64, but - that case isn't as user-visible.) - - On the PowerPC (both PPC32 and PPC64), all machine - instructions are 32 bits wide and all instruction words are - allocated on 32-bit boundaries. In PPC {CCL}, a CODE-VECTOR - is a specialized type of vector-like object; its elements - are 32-bit PPC machine instructions. A CODE-VECTOR is an - attribute of a FUNCTION object; a function call involves - accessing the function's code-vector and jumping to the - address of its first instruction. - - As each instruction in the code vector sequentially - executes, the hardware program counter (PC) register advances - to the address of the next instruction (a locative into the - code vector); since PPC instructions are always 32 bits wide - and aligned on 32-bit boundaries, the low two bits of the PC - are always 0. If the function executes a call (simple call - instructions have the mnemonic "bl" on the PPC, which stands - for "branch and link"), the address of the next instruction - (also a word-aligned locative into a code-vector) is copied - into the special- purpose PPC "link register" (lr); a function - returns to its caller via a "branch to link register" (blr) - instruction. Some cases of function call and return might - also use the PPC's "count register" (ctr), and if either the - lr or ctr needs to be stored in memory it needs to first be - copied to a general-purpose register. - - {CCL}'s GC understands that certain registers contain - these special "pc-locatives" (locatives that point into - CODE-VECTOR objects); it contains special support for - finding the containing CODE-VECTOR object and for adjusting - all of these "pc-locatives" if the containing object is - moved in memory. The first part of that - operation-finding the containing object-is - possible and practical on the PPC because of architectural - artifacts (fixed-width instructions and arcana of - instruction encoding.) It's not possible on x86-64, but - fortunately not necessary either (though the second part - - adjusting the PC/RIP when the containing object moves) is - both necessary and simple.|) - (defsection "Register and stack usage conventions" - (defsection "Stack conventions" - "On both PPC and X86 platforms, each lisp thread uses 3 - stacks; the ways in which these stacks are used differs - between the PPC and X86. - -Each thread has:" - (listing :bullet - (item #:|A "control stack". On both platforms, this is - "the stack" used by foreign code. On the PPC, it - consists of a linked list of frames where the first word - in each frame points to the first word in the previous - frame (and the outermost frame points to 0.) Some - frames on a PPC control stack are lisp frames; lisp - frames are always 4 words in size and contain (in - addition to the back pointer to the previous frame) the - calling function (a node), the return address (a - "locative" into the calling function's code-vector), and - the value to which the value-stack pointer (see below) - should be restored on function exit. On the PPC, the GC - has to look at control-stack frames, identify which of - those frames are lisp frames, and treat the contents of - the saved function slot as a node (and handle the return - address locative specially.) On x86-64, the control - stack is used for dynamic-extent allocation of immediate - objects. Since the control stack never contains nodes - on x86-64, the GC ignores it on that platform. - Alignment of the control stack follows the ABI - conventions of the platform (at least at any point in - time where foreign code could run.) On PPC, the r1 - register always points to the top of the current - thread's control stack; on x86-64, the RSP register - points to the top of the current thread's control stack - when the thread is running foreign code and the address - of the top of the control stack is kept in the thread's - TCR (see {section The Thread Context Record} - when not running foreign code. The control stack "grows - down."|) - (item #:|A "value stack". On both platforms, all values on - the value stack are nodes (including "tagged return - addresses" on x86-64.) The value stack is always - aligned to the native word size; objects are always - pushed on the value stack using atomic instructions - ("stwu"/"stdu" on PPC, "push" on x86-64), so the - contents of the value stack between its bottom and top - are always unambiguously nodes; the compiler usually - tries to pop or discard nodes from the value stack as - soon as possible after their last use (as soon as they - may have become garbage.) On x86-64, the RSP register - addresses the top of the value stack when running lisp - code; that address is saved in the TCR when running - foreign code. On the PPC, a dedicated register (VSP, - currently r15) is used to address the top of the value - stack when running lisp code, and the VSP value is saved - in the TCR when running foreign code. The value stack - grows down.|) - (item #:|A "temp stack". The temp stack consists of a - linked list of frames, each of which points to the - previous temp stack frame. The number of native - machine words in each temp stack frame is always even, - so the temp stack is aligned on a two-word (64- or - 128-bit) boundary. The temp stack is used for - dynamic-extent objects on both platforms; on the PPC, - it's used for essentially all such objects (regardless - of whether or not the objects contain nodes); on the - x86-64, immediate dynamic-extent objects (strings, - foreign pointers, etc.) are allocated on the control - stack and only node-containing dynamic-extent objects - are allocated on the temp stack. Data structures used - to implement CATCH and UNWIND-PROTECT are stored on - the temp stack on both ppc and x86-64. Temp stack - frames are always doublenode aligned and objects - within a temp stack frame are aligned on doublenode - boundaries. The first word in each frame contains a - back pointer to the previous frame; on the PPC, the - second word is used to indicate to the GC whether the - remaining objects are nodes (if the second word is 0) - or immediate (otherwise.) On x86-64, where temp stack - frames always contain nodes, the second word is always - 0. The temp stack grows down. It usually takes - several instructions to allocate and safely initialize - a temp stack frame that's intended to contain nodes, - and the GC has to recognize the case where a thread is - in the process of allocating and initializing a temp - stack frame and take care not to interpret any - uninitialized words in the frame as nodes. The PPC - keeps the current top of the temp stack in a dedicated - register (TSP, currently r12) when running lisp code - and saves this register's value in the TCR when - running foreign code. The x86-64 keeps the address of - the top of each thread's temp stack in the thread's - TCR.|))) - (defsection "Register conventions" - #:|If there are a "reasonable" (for some value of - "reasonable") number of general-purpose registers and the - instruction set is "reasonably" orthogonal (most - instructions that operate on GPRs can operate on any GPR), - then it's possible to statically partition the GPRs into at - least two sets: "immediate registers" never contain nodes, - and "node registers" always contain nodes. (On the PPC, a - few registers are members of a third set of "PC locatives", - and on both platforms some registers may have dedicated - roles as stack or heap pointers; the latter class is treated - as immediates by the GC proper but may be used to help - determine the bounds of stack and heap memory areas.) - - The ultimate definition of register partitioning is - hardwired into the GC in functions like "mark_xp()" and - "forward_xp()", which process the values of some of the - registers in an exception frame as nodes and may give some - sort of special treatment to other register values they - encounter there.) - -On x86-64, the static register partitioning scheme involves:| - (listing :bullet - (item #:|(only) three "immediate" registers. - - The RAX, RCX, and RDX registers are used as the - implicit operands and results of some extended-precision - multiply and divide instructions which generally involve - non-node values; since their use in these instructions - means that they can't be guaranteed to contain node - values at all times, it's natural to put these registers - in the "immediate" set. RAX is generally given the - symbolic name "imm0", RDX is given the symbolic name - "imm1" and RCX is given the symbolic name "imm2"; you - may see these names in disassembled code, usually in - operations involving type checking, array indexing, and - foreign memory and function access.|) - (item #:|(only) two "dedicated" registers. - - RSP and RBP have - dedicated functionality dictated by the hardware and - calling conventions.|) - (item #:|11 "node" registers. - - All other registers (RBX, RSI, RDI, and R8-R15) - are asserted to contain node values at (almost) all - times; legacy "string" operations that implicitly use RSI - and/or RDI are not used.|)) - (para " - On 32-bit x86, the default register partitioning scheme - involves: - ") - (listing :bullet - (item #:| - A single "immediate" register. - - - - The EAX register is given the symbolic name - "imm0". - |) - (item #:| - There are two "dedicated" registers. - - - - ESP and EBP have dedicated functionality dictated by the - hardware and calling conventions. - |) - (item #:| - 5 "node" registers. - - - - The remaining registers, (EBX, ECX, EDX, ESI, EDI) normally - contain node values. As on x86-64, string instructions - that implicity use ESI and EDI are not used. - |)) - " - There are times when this default partitioning scheme is - inadequate. As mentioned in the x86-64 section, there are - instructions like the extended-precision MUL and DIV which - require the use of EAX and EDX. We therefore need a way to - change this partitioning at run-time. - - - - Two schemes are employed. The first uses a mask in the TCR - that contains a bit for each register. If the bit is set, - the register is interpreted by the GC as a node register; if it's - clear, the register is treated as an immediate register. The - second scheme uses the direction flag in the EFLAGS register. - If DF is set, EDX is treated as an immediate register. - (We don't use the string instructions, so DF isn't otherwise - used.) - - - On the PPC, the static register partitioning scheme - involves:" - (listing :bullet - (item #:|6 "immediate" registers. - - Registers r3-r8 are given - the symbolic names imm0-imm5. As a RISC architecture - with simpler addressing modes, the PPC probably - uses immediate registers a bit more often than the CISC - x86-64 does, but they're generally used for the same sort - of things (type checking, array indexing, FFI, - etc.)|) - (item "9 dedicated registers - " - (listing :bullet - (item "r0 (symbolic name rzero) always contains the - value 0 when running lisp code. Its value is - sometimes read as 0 when it's used as the base - register in a memory address; keeping the value 0 - there is sometimes convenient and avoids - asymmetry.") - (item "r1 (symbolic name sp) is the control stack - pointer, by PPC convention.") - (item "r2 is used to hold the current thread's TCR on - ppc64 systems; it's not used on ppc32.") - (item "r9 and r10 (symbolic names allocptr and - allocbase) are used to do per-thread memory - allocation") - (item "r11 (symbolic name nargs) contains the number - of function arguments on entry and the number of - return values in multiple-value returning - constructs. It's not used more generally as either - a node or immediate register because of the way that - certain trap instruction encodings are - interpreted.") - (item "r12 (symbolic name tsp) holds the top of the - current thread's temp stack.") - (item "r13 is used to hold the TCR on PPC32 systems; - it's not used on PPC64.") - (item #:|r14 (symbolic name loc-pc) is used to copy - "pc-locative" values between main memory and - special-purpose PPC registers (LR and CTR) used in - function-call and return instructions.|) - (item "r15 (symbolic name vsp) addresses the top of - the current thread's value stack.") - (item #:|lr and ctr are PPC branch-unit registers used - in function call and return instructions; they're - always treated as "pc-locatives", which precludes - the use of the ctr in some PPC looping - constructs.|))) - (item #:|17 "node" registers - - r15-r31 are always treated as node - registers|)))) - (defsection "Tagging scheme" - #:|{CCL} always allocates lisp objects on double-node - (64-bit for 32-bit platforms, 128-bit for 64-bit platforms) - boundaries; this mean that the low 3 bits (32-bit lisp) or 4 - bits (64-bit lisp) are always 0 and are therefore redundant - (we only really need to know the upper 29 or 60 bits in order - to identify the aligned object address.) The extra bits in a - lisp node can be used to encode at least some information - about the node's type, and the other 29/60 bits represent - either an immediate value or a doublenode-aligned memory - address. The low 3 or 4 bits of a node are called the node's - "tag bits", and the conventions used to encode type - information in those tag bits are called a "tagging - scheme." - - It might be possible to use the same tagging scheme on - all platforms (at least on all platforms with the same word - size and/or the same number of available tag bits), but there - are often some strong reasons for not doing so. These - arguments tend to be very machine-specific: sometimes, there - are fairly obvious machine-dependent tricks that can be - exploited to make common operations on some types of tagged - objects faster; other times, there are architectural - restrictions that make it impractical to use certain tags for - certain types. (On PPC64, the "ld" (load doubleword) and - "std" (store doubleword) instructions - which load and store a - GPR operand at the effective address formed by adding the - value of another GPR operand and a 16-bit constant operand - - require that the low two bits of that constant operand be 0. - Since such instructions would typically be used to access the - fields of things like CONS cells and structures, it's - desirable that that the tags chosen for CONS cells and - structures allow the use of these instructions as opposed to - more expensive alternatives.) - - One architecture-dependent tagging trick that works well - on all architectures is to use a tag of 0 for FIXNUMs: a - fixnum basically encodes its value shifted left a few bits - and keeps those low bits clear. FIXNUM addition, - subtraction, and binary logical operations can operate - directly on the node operands, addition and subtraction can - exploit hardware-based overflow detection, and (in the - absence of overflow) the hardware result of those operations - is a node (fixnum). Some other slightly-less-common - operations may require a few extra instructions, but - arithmetic operations on FIXNUMs should be as cheap as - possible and using a tag of zero for FIXNUMs helps to ensure - that it will be. - - If we have N available tag bits (N = 3 for 32-bit {CCL} - and N = 4 for 64-bit {CCL}), this way of representing - fixnums with the low M bits forced to 0 works as long as M - <= N. The smaller we make M, the larger the values of - MOST-POSITIVE-FIXNUM and MOST-NEGATIVE become; the larger we - make N, the more distinct non-FIXNUM tags become available. - A reasonable compromise is to choose M = N-1; this basically - yields two distinct FIXNUM tags (one for even fixnums, one - for odd fixnums), gives 30-bit fixnums on 32-bit platforms - and 61-bit fixnums on 64-bit platforms, and leaves us with 6 - or 14 tags to encoded other types. - - Once we get past the assignment of FIXNUM tags, things - quickly devolve into machine-dependencies. We can fairly - easily see that we can't directly tag all other primitive - lisp object types with only 6 or 14 available tag values; - the details of how types are encoded vary between the ppc32, - ppc64, and x86-64 implementations, but there are some - general common principles:| - (listing :bullet - (item #:|CONS cells always contain exactly 2 elements and are - usually fairly common.It therefore makes sense to give - CONS cells their own tag. Unlike the fixnum case - - where a tag value of 0 had positive implications - there - doesn't seem to be any advantage to using any particular - value. (A longtime ago - in the case of 68K MCL - the - CONS tag and the order of CAR and CDR in memory were - chosen to allow smaller, cheaper addressing modes to be - used to "cdr down a list." That's not a factor on ppc - or x86-64, but all versions of {CCL} still store the CDR - of a CONS cell first in memory. It doesn't matter, but - doing it the way that the host system did made - boostrapping to a new target system a little easier.) - |) - (item #:|Any way you look at it, NIL is a bit - ... unusual. NIL is both a SYMBOL and a LIST (as well as - being a canonical truth value and probably a few other - things.) Its role as a LIST is probably much more - important to most programs than its role as a SYMBOL is: - LISTP has to be true of NIL and primitives like CAR and - CDR do LISTP implicitly when safe and want that - operation to be fast. There are several possible - approaches to this problem; {CCL} uses two of them. On - PPC32 and X86-64, NIL is basically a weird CONS cell - that straddles two doublenodes; the tag of NIL is unique - and congruent modulo 4 (modulo 8 on 64-bit) with the tag - used for CONS cells. LISTP is therefore true of any - node whose low 2 (or 3) bits contain the appropriate tag - value (it's not otherwise necessary to special-case - NIL.) SYMBOL accessors (SYMBOL-NAME, SYMBOL-VALUE, - SYMBOL-PLIST ..) -do- have to special-case NIL (and - access the components of an internal proxy symbol.) On - PPC64 (where architectural restrictions dictate the set - of tags that can be used to access fixed components of - an object), that approach wasn't practical. NIL is just - a distinguished SYMBOL,and it just happens to be the - case that its pname slot and values slot are at the same - offsets from a tagged pointer as a CONS cell's CDR and - CAR would be. NIL's pname is set to NIL (SYMBOL-NAME - checks for this and returns the string "NIL"), and LISTP - (and therefore safe CAR and CDR) has to check for (OR - NULL CONSP). At least in the case of CAR and CDR, the - fact that the PPC has multiple condition-code fields - keeps that extra test from being prohibitively - expensive. On IA-32, we can't afford to dedicate a tag to - NIL. NIL is therefore just a distinguished CONS - cell, and we have to explicitly check for a NIL argument - in CONSP/RPLACA/RPLACD. - |) - (item "Some objects are immediate (but not FIXNUMs). This - is true of CHARACTERs and, on 64-bit platforms, - SINGLE-FLOATs. It's also true of some nodes used in the - runtime system (special values used to indicate unbound - variables and slots, for instance.) On 64-bit platforms, - SINGLE-FLOATs have their own unique tag (making them a - little easier to recognize; on all platforms, CHARACTERs - share a tag with other immediate objects (unbound - markers) but are easy to recognize (by looking at - several of their low bits.) The GC treats any node with - an immediate tag (and any node with a fixnum tag) as a - leaf.") - (item #:|There are some advantages to treating everything - else-memory-allocated objects that aren't CONS - cells-uniformly.There are some disadvantages to - that uniform treatment as well, and the treatment of - "memory-allocated non-CONS objects" isn't entirely - uniform across all {CCL} implementations. Let's first - pretend that the treatment is uniform, then discuss the - ways in which it isn't.The "uniform approach" is to - treat all memory-allocated non-CONS objects as if they - were vectors; this use of the term is a little looser - than what's implied by the CL VECTOR type. {CCL} - actually uses the term "uvector" to mean "a - memory-allocated lisp object other than a CONS cell, - whose first word is a header that describes the object's - type and the number of elements that it contains." In - this view, a SYMBOL is a UVECTOR, as is a STRING, a - STANDARD-INSTANCE, a CL array or vector, a FUNCTION, and - even a DOUBLE-FLOAT. In the PPC implementations (where - things are a little more ... uniform), a single tag - value is used to denote any uvector; in order to - determine something more specific about the type of the - object in question, it's necessary to fetch the low byte - of the header word from memory. On the x86-64 platform, - certain types of uvectors - SYMBOLs and FUNCTIONs -are - given their own unique tags. The good news about the - x86-64 approach is that SYMBOLs and FUNCTIONs can be - recognized without referencing memory; the slightly bad - news is that primitive operations that work on - UVECTOR-tagged objects-like the function - CCL:UVREF-don't work on SYMBOLs or FUNCTIONs on - x86-64 (but -do- work on those types of objects in the - PPC ports.) The header word that precedes a UVECTOR's - data in memory contains 8 bits of type information in - the low byte and either 24 or 56 bits of "element-count" - information in the rest of the word. (This is where the - sometimes-limiting value of 2^24 for - ARRAY-TOTAL-SIZE-LIMIT on 32-bit platforms comes from.) - The low byte of the header-sometimes called the - uvector's subtag-is itself tagged (which means - that the header is tagged.) The (3 or 4) tag bits in - the subtag are used to determine whether the uvector's - elements are nodes or immediates. (A UVECTOR whose - elements are nodes is called a GVECTOR; a UVECTOR whose - elements are immediates is called an IVECTOR. This - terminology came from Spice Lisp, which was a - predecessor of CMUCL.) Even though a uvector header is - tagged, a header is not a node. There's no (supported) - way to get your hands on one in lisp and doing so could - be dangerous. (If the value of a header wound up in a - lisp node register and that register wound up getting - pushed on a thread's value stack, the GC might - misinterpret that situation to mean that there was a - stack-allocated UVECTOR on the value stack.)|)))) - (defsection "Heap Allocation" - #:|When the {CCL} kernel first - starts up, a large contiguous chunk of the process's address - space is mapped as "anonymous, no access" memory. ("Large" - means different things in different contexts; on LinuxPPC32, - it means "about 1 gigabyte", on DarwinPPC32, it means "about 2 - gigabytes", and on current 64-bit platforms it ranges from 128 - to 512 gigabytes, depending on OS. These values are both - defaults and upper limits; - the {code --heap-reserve} argument can be used to - try to reserve less than the default.) - - Reserving address space that can't (yet) be read or - written to doesn't cost much; in particular, it doesn't require - that corresponding swap space or physical memory be available. - Marking the address range as being "mapped" helps to ensure that - other things (results from random calls to malloc(), dynamically - loaded shared libraries) won't be allocated in this region that - lisp has reserved for its own heap growth. - - A small portion (around 1/32 on 32-bit platforms and 1/64 - on 64-bit platforms) of that large chunk of address space is - reserved for GC data structures. Memory pages reserved for - these data structures are mapped read-write as pages are made - writable in the main portion of the heap. - - The initial heap image is mapped into this reserved - address space and an additional (LISP-HEAP-GC-THRESHOLD) bytes - are mapped read-write. GC data structures grow to match the - amount of GC-able memory in the initial image plus the gc - threshold, and control is transferred to lisp code. - Inevitably, that code spoils everything and starts consing; - there are basically three layers of memory allocation that can - go on.| - (defsection "Per-thread object allocation" - #:|Each lisp thread has a private "reserved memory - segment"; when a thread starts up, its reserved memory segment - is empty. PPC ports maintain the highest unallocated address - and the lowest allocatable address in the current segment in - registers when running lisp code; on x86-664, these values are - maintained in the current threads's TCR. (An "empty" heap - segment is one whose high pointer and low pointer are equal.) - When a thread is not in the middle of allocating something, the - low 3 or 4 bits of the high and low pointers are clear (the - pointers are doublenode-aligned.) - - A thread tries to allocate an object whose physical size - in bytes is X and whose tag is Y by:| - (listing :number - (item #:|decrementing the "high" pointer by (- X Y)|) - (item "trapping if the high pointer is less than the low - pointer") - (item "using the (tagged) high pointer to initialize the - object, if necessary") - (item "clearing the low bits of the high pointer")) - (para "On PPC32, where the size of a CONS cell is 8 bytes and - the tag of a CONS cell is 1, machine code which sets the arg_z - register to the result of doing (CONS arg_y arg_z) looks - like:") - (code-block " - (SUBI ALLOCPTR ALLOCPTR 7) ; decrement the high pointer by (- 8 1) - (TWLLT ALLOCPTR ALLOCBASE) ; trap if the high pointer is below the base - (STW ARG_Z -1 ALLOCPTR) ; set the CDR of the tagged high pointer - (STW ARG_Y 3 ALLOCPTR) ; set the CAR - (MR ARG_Z ALLOCPTR) ; arg_z is the new CONS cell - (RLWINM ALLOCPTR ALLOCPTR 0 0 28) ; clear tag bits - ") - (para "On x86-64, the idea's similar but the implementation is - different. The high and low pointers to the current thread's - reserved segment are kept in the TCR, which is addressed by - the gs segment register. An x86-64 CONS cell is 16 bytes wide - and has a tag of 3; we canonically use the temp0 register to - initialize the object") - (code-block " - (subq ($ 13) ((% gs) 216)) ; decrement allocptr - (movq ((% gs) 216) (% temp0)) ; load allocptr into temp0 - (cmpq ((% gs) 224) (% temp0)) ; compare to allocabase - (jg L1) ; skip trap - (uuo-alloc) ; uh, don't skip trap -L1 - (andb ($ 240) ((% gs) 216)) ; untag allocptr in the tcr - (movq (% arg_y) (5 (% temp0))) ; set the car - (movq (% arg_z) (-3 (% temp0))); set the cdr - (movq (% temp0) (% arg_z)) ; return the cons - ") - (para "If we don't take the trap (if allocating 8-16 bytes - doesn't exhaust the thread's reserved memory segment), that's - a fairly short and simple instruction sequence. If we do take - the trap, we'll have to do some additional work in order to - get a new segment for the current thread.")) - (defsection "Allocation of reserved heap segments" - #:|After the lisp image is first mapped into memory - and after - each full GC - the lisp kernel ensures that - (LISP-HEAP-GC-TRESHOLD) additional bytes beyond the current - end of the heap are mapped read-write. - - If a thread traps while trying to allocate memory, the - thread goes through the usual exception-handling protocol (to - ensure that any other thread that GCs "sees" the state of the - trapping thread and to serialize exception handling.) When - the exception handler runs, it determines the nature and size - of the failed allocation and tries to complete the allocation - on the thread's behalf (and leave it with a reasonably large - thread-specific memory segment so that the next small - allocation is unlikely to trap. - - Depending on the size of the requested segment - allocation, the number of segment allocations that have - occurred since the last GC, and the EGC and GC thresholds, the - segment allocation trap handler may invoke a full or ephemeral - GC before returning a new segment. It's worth noting that the - [E]GC is triggered based on the number of and size of these - segments that have been allocated since the last GC; it doesn't - have much to do with how "full" each of those per-thread - segments are. It's possible for a large number of threads to - do fairly incidental memory allocation and trigger the GC as a - result; avoiding this involves tuning the per-thread - allocation quantum and the GC/EGC thresholds - appropriately.|) - (defsection "Heap growth" - #:|All OSes on which {CCL} currently runs use an - "overcommit" memory allocation strategy by default (though - some of them provide ways of overriding that default.) What - this means in general is that the OS doesn't necessarily - ensure that backing store is available when asked to map pages - as read-write; it'll often return a success indicator from the - mapping attempt (mapping the pages as "zero-fill, - copy-on-write"), and only try to allocate the backing store - (swap space and/or physical memory) when non-zero contents are - written to the pages. - - It -sounds- like it'd be better to have the mmap() call - fail immediately, but it's actually a complicated issue. - (It's possible that other applications will stop using some - backing store before lisp code actually touches the pages that - need it, for instance.) It's also not guaranteed that lisp - code would be able to "cleanly" signal an out-of-memory - condition if lisp is ... out of memory - - I don't know that I've ever seen an abrupt out-of-memory - failure that wasn't preceded by several minutes of excessive - paging activity. The most expedient course in cases like this - is to either (a) use less memory or (b) get more memory; it's - generally hard to use memory that you don't have.|)) - (defsection "GC details" - "The GC uses a Mark/Compact algorithm; its - execution time is essentially a factor of the amount of live - data in the heap. (The somewhat better-known Mark/Sweep - algorithms don't compact the live data but instead traverse the - garbage to rebuild free-lists; their execution time is therefore - a factor of the total heap size.) - - As mentioned in {section Heap Allocation}, two - auxiliary data structures (proportional to the size of the lisp - heap) are maintained. These are" - (listing :number - (item "the markbits bitvector, which contains a bit for - every doublenode in the dynamic heap (plus a few extra words - for alignment and so that sub-bitvectors can start on word - boundaries.)") - (item "the relocation table, which contains a native word for - every 32 or 64 doublenodes in the dynamic heap, plus an - extra word used to keep track of the end of the heap.")) - "The total GC space overhead is therefore on the order of - 3% (2/64 or 1/32). - -The general algorithm proceeds as follows:" - (defsection "Mark phase" - "Each doublenode in the dynamic heap has a corresponding - bit in the markbits vector. (For any doublenode in the heap, - the index of its mark bit is determined by subtracting the - address of the start of the heap from the address of the - object and dividing the result by 8 or 16.) The GC knows the - markbit index of the free pointer, so determining that the - markbit index of a doubleword address is between the start of - the heap and the free pointer can be done with a single - unsigned comparison. - - The markbits of all doublenodes in the dynamic heap are - zeroed before the mark phase begins. An object is - {emphasis marked} if the markbits of all of its - constituent doublewords are set and unmarked otherwise; - setting an object's markbits involves setting the corresponding - markbits of all constituent doublenodes in the object. - - The mark phase traverses each root. If the tag of the - value of the root indicates that it's a non-immediate node - whose address lies in the lisp heap, then:" - (listing :number - (item "If the object is already marked, do nothing.") - (item "Set the object's markbit(s).") - (item "If the object is an ivector, do nothing further.") - (item "If the object is a cons cell, recursively mark its - car and cdr.") - (item "Otherwise, the object is a gvector. Recursively mark - its elements.")) - "Marking an object thus involves ensuring that its mark - bits are set and then recursively marking any pointers - contained within the object if the object was originally - unmarked. If this recursive step was implemented in the - obvious manner, marking an object would take stack space - proportional to the length of the pointer chain from some root - to that object. Rather than storing that pointer chain - implicitly on the stack (in a series of recursive calls to the - mark subroutine), the {CCL} marker uses mixture of recursion - and a technique called {emphasis link inversion} to - store the pointer chain in the objects themselves. (Recursion - tends to be simpler and faster; if a recursive step notes that - stack space is becoming limited, the link-inversion technique - is used.) - -Certain types of objects are treated a little specially:" - (listing :number - (item #:|To support a feature called {emphasis GCTWA} - (an acronym that I believe comes from MACLISP, - where it stood for "Garbage Collection of Truly - Worthless Atoms"), - the vector that contains the internal - symbols of the current package is marked on entry to the - mark phase, but the symbols themselves are not marked at - this time. Near the end of the mark phase, symbols - referenced from this vector which are not otherwise - marked are marked if and only if they're somehow - distinguishable from newly created symbols (by virtue of - their having function bindings, value bindings, plists, - or other attributes.)|) - (item "Pools have their first element set to NIL before any - other elements are marked.") - (item "All hash tables have certain fields (used to cache - previous results) invalidated.") - (item "Weak Hash Tables and other weak objects are put on a - linkedlist as they're encountered; their contents are only - retained if there are other (non-weak) references to - them.")) - (para "At the end of the mark phase, the markbits of all - objects that are transitively reachable from the roots are - set and all other markbits are clear.")) - (defsection "Relocation phase" - "The {emphasis forwarding address} of a - doublenode in the dynamic heap is ( - - (size_of_doublenode * )) or alternately ( + - (size_of_doublenode * )). Rather than count the number of preceding - markbits each time, the relocation table is used to precompute - an approximation of the forwarding addresses for all - doublewords. Given this approximate address and a pointer into - the markbits vector, it's relatively easy to compute the exact - forwarding address. - - The relocation table contains the forwarding addresses - of each {emphasis pagelet}, where a pagelet is 256 - bytes (or 32 doublenodes). The forwarding address of the first - pagelet is the base of the heap. The forwarding address of the - second pagelet is the sum of the forwarding address of the - first and 8 bytes for each mark bit set in the first 32-bit - word in the markbits table. The last entry in the relocation - table contains the forwarding address that the freepointer - would have, e.g., the new value of the freepointer after - compaction. - - In many programs, old objects rarely become garbage and - new objects often do. When building the relocation table, the - relocation phase notes the address of the first unmarked - object in the dynamic heap. Only the area of the heap between - the first unmarked object and the freepointer needs to be - compacted; only pointers to this area will need to be - forwarded (the forwarding address of all other pointers to the - dynamic heap is the address of that pointer.) Often, the - first unmarked object is much nearer the free pointer than it - is to the base of the heap.") - (defsection "Forwarding phase" - #:|The forwarding phase traverses all roots and the "old" - part of the dynamic heap (the part between the base of the - heap and the first unmarked object.) All references to objects - whose address is between the first unmarked object and the - free pointer are updated to point to the address the object - will have after compaction by using the relocation table and - the markbits vector and interpolating. - - The relocation table entry for the pagelet nearest the - object is found. If the pagelet's address is less than the - object's address, the number of set markbits that precede - the object on the pagelet is used to determine the object's - address; otherwise, the number of set markbits that follow - the object on the pagelet is used. - - Since forwarding views the heap as a set of doublewords, - locatives are (mostly) treated like any other pointers. (The - basic difference is that locatives may appear to be tagged as - fixnums, in which case they're treated as word-aligned - pointers into the object.) - - If the forward phase changes the address of any hash - table key in a hash table that hashes by address (e.g., an EQ - hash table), it sets a bit in the hash table's header. The - hash table code will rehash the hash table's contents if it - tries to do a lookup on a key in such a table. - - Profiling reveals that about half of the total time - spent in the GC is spent in the subroutine which determines a - pointer's forwarding address. Exploiting GCC-specific idioms, - hand-coding the routine, and inlining calls to it could all be - expected to improve GC performance.|) - (defsection "Compact phase" - #:|The compact phase compacts the area between the first - unmarked object and the freepointer so that it contains only - marked objects. While doing so, it forwards any pointers it - finds in the objects it copies. - - When the compact phase is finished, so is the GC (more - or less): the free pointer and some other data structures are - updated and control returns to the exception handler that - invoked the GC. If sufficient memory has been freed to satisfy - any allocation request that may have triggered the GC, the - exception handler returns; otherwise, a "seriously low on - memory" condition is signaled, possibly after releasing a - small emergency pool of memory.|)) - (defsection "The ephemeral GC" - "In the {CCL} memory management scheme, the relative age - of two objects in the dynamic heap can be determined by their - addresses: if addresses X and Y are both addresses in the - dynamic heap, X is younger than Y (X was created more recently - than Y) if it is nearer to the free pointer (and farther from - the base of the heap) than Y. - - Ephemeral (or generational) garbage collectors attempt to - exploit the following assumptions:" - (listing :bullet - (item "most newly created objects become garbage soon after - they'recreated.") - (item "most objects that have already survived several GCs - are unlikely to ever become garbage.") - (item "old objects can only point to newer objects as the - result of a destructive modification (e.g., via - SETF.)")) - #:|By concentrating its efforts on (frequently and quickly) - reclaiming newly created garbage, an ephemeral collector hopes - to postpone the more costly full GC as long as possible. It's - important to note that most programs create some long-lived - garbage, so an EGC can't typically eliminate the need for full - GC. - - An EGC views each object in the heap as belonging to - exactly one {emphasis generation}; generations are - sets of objects that are related to each other by age: some - generation is the youngest, some the oldest, and there's an age - relationship between any intervening generations. Objects are - typically assigned to the youngest generation when first - allocated; any object that has survived some number of GCs in - its current generation is promoted (or - {emphasis tenured}) into an older generation. - - When a generation is GCed, the roots consist of the - stacks, registers, and global variables as always and also of - any pointers to objects in that generation from other - generations. To avoid the need to scan those (often large) other - generations looking for such intergenerational references, the - runtime system must note all such intergenerational references - at the point where they're created (via Setf). (This is - sometimes called "The Write Barrier": all assignments which - might result in intergenerational references must be noted, as - if the other generations were write-protected). The - set of pointers that may contain intergenerational references is - sometimes called {emphasis the remembered set}. - - In {CCL}'s EGC, the heap is organized exactly the same - as otherwise; "generations" are merely structures which contain - pointers to regions of the heap (which is already ordered by - age.) When a generation needs to be GCed, any younger generation - is incorporated into it; all objects which survive a GC of a - given generation are promoted into the next older - generation. The only intergenerational references that can exist - are therefore those where an old object is modified to contain a - pointer to a new object. - - The EGC uses exactly the same code as the full GC. When a - given GC is "ephemeral",| - (listing :bullet - (item #:|the "base of the heap" used to determine an object's - markbit address is the base of the generation - being collected;|) - (item "the markbits vector is actually a pointer into the - middle of the global markbits table; preceding entries in - this table are used to note doubleword addresses in older - generations that (may) contain intergenerational - references;") - (item "some steps (notably GCTWA and the handling of weak - objects) are not performed;") - (item #:|the intergenerational references table is used to - find additional roots for the mark and forward phases. If a - bit is set in the intergenerational references table, that - means that the corresponding doubleword (in some "old" - generation, in some "earlier" part of the heap) may have had - a pointer to an object in a younger generation stored into - it.|)) - "With one exception (the implicit setfs that occur on entry - to and exit from the binding of a special variable), all setfs - that might introduce an intergenerational reference must be - memoized. - Note that the implicit setfs that occur when - initializing an object - as in the case of a call to cons or - vector - can't introduce intergenerational references, since - the newly created object is always younger than the objects - used to initialize it. It's always safe to - push any cons cell or gvector locative onto the memo stack; - it's never safe to push anything else. - - - Typically, the intergenerational references bitvector is - sparse: a relatively small number of old locations are stored - into, although some of them may have been stored into many - times. The routine that scans the memoization buffer does a lot - of work and usually does it fairly often; it uses a simple, - brute-force method but might run faster if it was smarter about - recognizing addresses that it'd already seen. - - - When the EGC mark and forward phases scan the - intergenerational reference bits, they can clear any bits that - denote doublewords that definitely do not contain - intergenerational references. - ") - (defsection "Fasl files" - #:|Saving and loading of Fasl files is implemented in - xdump/faslenv.lisp, level-0/nfasload.lisp, and lib/nfcomp.lisp. - The information here is only an overview, which might help when - reading the source. - - The {CCL} Fasl format is forked from the old MCL Fasl - format; there are a few differences, but they are minor. The - name "nfasload" comes from the fact that this is the so-called - "new" Fasl system, which was true in 1986 or so. - - A Fasl file begins with a "file header", which contains - version information and a count of the following "blocks". - There's typically only one "block" per Fasl file. The blocks - are part of a mechanism for combining multiple logical files - into a single physical file, in order to simplify the - distribution of precompiled programs. - - Each block begins with a header for itself, which just - describes the size of the data that follows. - - The data in each block is treated as a simple stream of - bytes, which define a bytecode program. The actual bytecodes, - "fasl operators", are defined in xdump/faslenv.lisp. The - descriptions in the source file are terse, but, according to - Gary, "probably accurate". - - Some of the operators are used to create a per-block - "object table", which is a vector used to keep track of - previously-loaded objects and simplify references to them. When - the table is created, an index associated with it is set to - zero; this is analogous to an array fill-pointer, and allows the - table to be treated like a stack. - - The low seven bits of each bytecode are used to specify - the fasl operator; currently, about fifty operators are defined. - The high byte, when set, indicates that the result of the - operation should be pushed onto the object table. - - Most bytecodes are followed by operands; the operand data - is byte-aligned. How many operands there are, and their type, - depend on the bytecode. Operands can be indices into the object - table, immediate values, or some combination of these. - - An exception is the bytecode #xFF, which has the symbolic - name ccl::$faslend; it is used to mark the end of the - block.|) - (defsection "The Objective-C Bridge" - (defsection "How {CCL} Recognizes Objective-C Objects" - #:|In most cases, pointers to instances of Objective-C - classes are recognized as such; the recognition is (and - probably always will be) slightly heuristic. Basically, any - pointer that passes basic sanity checks and whose first word - is a pointer to a known ObjC class is considered to be an - instance of that class; the Objective-C runtime system would - reach the same conclusion. - - It's certainly possible that a random pointer to an - arbitrary memory address could look enough like an ObjC - instance to fool the lisp runtime system, and it's possible - that pointers could have their contents change so that - something that had either been a true ObjC instance (or had - looked a lot like one) is changed (possibly by virtue of - having been deallocated.) - - In the first case, we can improve the heuristics - substantially: we can make stronger assertions that a - particular pointer is really "of type :ID" when it's a - parameter to a function declared to take such a pointer as an - argument or a similarly declared function result; we can be - more confident of something we obtained via SLOT-VALUE of a - slot defined to be of type :ID than if we just dug a pointer - out of memory somewhere. - - The second case is a little more subtle: ObjC memory - management is based on a reference-counting scheme, and it's - possible for an object to ... cease to be an object while lisp - is still referencing it. If we don't want to deal with this - possibility (and we don't), we'll basically have to ensure - that the object is not deallocated while lisp is still - thinking of it as a first-class object. There's some support - for this in the case of objects created with MAKE-INSTANCE, - but we may need to give similar treatment to foreign objects - that are introduced to the lisp runtime in other ways (as - function arguments, return values, SLOT-VALUE results, etc. as - well as those instances that are created under lisp - control.) - - This doesn't all work yet (in fact, not much of it works - yet); in practice, this has not yet been as much of a problem - as anticipated, but that may be because existing Cocoa code - deals primarily with relatively long-lived objects such as - windows, views, menus, etc.|) - (defsection "Recommended Reading" - (listing :definition - (item "{link http://developer.apple.com/documentation/Cocoa/ Cocoa Documentation}" ccldoc::=> " - This is the top page for all of Apple's documentation on - Cocoa. If you are unfamiliar with Cocoa, it is a good - place to start. - ") - (item - "{link http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/index.html Foundation Reference for Objective-C}" - ccldoc::=> " - This is one of the two most important Cocoa references; it - covers all of the basics, except for GUI programming. This is - a reference, not a tutorial. - "))))) \ No newline at end of file diff --git a/ccl-documentation/install.ccldoc b/ccl-documentation/install.ccldoc deleted file mode 100644 index 4fb1c3a..0000000 --- a/ccl-documentation/install.ccldoc +++ /dev/null @@ -1,169 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Installing and Running {CCL}" - - (defsection "Installing" - "{CCL} is distributed via the Internet. Please see {link -http://ccl.clozure.com/download.html} for instructions on how to -download it. - -After following the download instructions, you should have a directory -on your system named {system ccl}. This directory is called the {term -ccl directory}." - - (glossentry "ccl directory" "The directory containing {CCL}'s source -code and interface databases. The {code ccl} logical host should refer -to this directory.") - -"{CCL} is made up of two parts: the {term lisp kernel}, and a {term -heap image}. When the lisp kernel starts up, it locates the heap -image, maps it into memory, and starts running the lisp code contained -in the image. In the ccl directory, you will find pre-built lisp -kernel executables and heap images for your platform. - -The names used for the lisp kernel on the various platforms are listed -in the table below. The heap images have the same basename as the -corresponding lisp kernel, but a {system .image} suffix. Thus, the -image name for {system armcl} would be {system armcl.image}." - - (table "Kernel Names by Platform" - (row (item "Platform") (item "Kernel")) - (row (item "Linux x86, x86-64") (item "lx86cl, lx86cl64")) - (row (item "OS X x86, x86-64") (item "dx86cl, dx86cl64")) - (row (item "FreeBSD x86, x86-64") (item "fx86cl, fx86cl64")) - (row (item "Solaris x86, x86-64") (item "sx86cl, sx86cl64")) - (row (item "Windows x86, x86-64") (item "wx86cl, wx86cl64")) - (row (item "Linux PowerPC 32-bit, 64-bit") (item "ppccl, ppccl64")) - (row (item "Linux ARM 32-bit (armv6)") (item "armcl"))) - - "By default, the lisp kernel will look for a heap image with an -appropriate name in the same directory that the lisp kernel itself is -in. Thus, it is possible to start {CCL} simply by running {system -./lx86cl64} (or whatever the appropriate binary is called) directly -from the ccl directory. - - If the lisp kernel binary does not work, you may need to recompile it -on your local system. See {section Building the Kernel}.") - - (defsection "Running {CCL}" - "If you always run {CCL} from Emacs, it is sufficient to use the full pathname -of the lisp kernel binary directly. That is, in your Emacs init file, you could write something -like {code (setq inferior-lisp-program \"/path/to/ccl/lx86cl64\")} or make the equivalent -changes to {code slime-lisp-implementations}. - - It can also be handy to run {CCL} straight from a terminal prompt. -In the {system scripts/} directory of the ccl directory, there are two -files named {system ccl} and {system ccl64}. Copy these files into -{system /usr/local/bin} or some other directory that is on your path, and then -edit them so that the value of {code CCL_DEFAULT_DIRECTORY} is your ccl -directory. You can then start up the lisp by typing {system ccl} or {system ccl64}. - - You may wish to install {system scripts/ccl64} with the name -{system ccl} if you use the 64-bit lisp more. If you want the 32-bit -lisp to be available as well, you can install {system scripts/ccl} as -{system ccl32}. Note that there is nothing magical about these -scripts. You should feel free to edit them as desired." - - (defsection "The Init File" - "By default, {CCL} will look for a file named {system - ccl-init.lisp} in your home directory, and load it upon startup. - On Unix systems, it will also look for {system .ccl-init.lisp}. - - If you wish, you can compile your init file, and {CCL} will load - the compiled version if it is newer than the corresponding - source file. In other words, {CCL} loads your init file with - {code (load \"home:ccl-init\")}. - - Because the init file is loaded the same way as normal Lisp code - is, you can put anything you want in it. For example, you can - change the working directory, and load code that you use - frequently. - - To suppress the loading of this init-file, invoke {CCL} with the - {code --no-init} (or {code -n}) option.") - - (defsection "Command Line Options" - (para "When using {CCL} from the command line, the following - options may be used to modify its behavior. The exact set of - {CCL} command-line arguments may vary per platform and - may change over time. The definitive list of command line - options may be retrieved by using the - {code --help} option.") - (listing :bullet - (item "{code -h} (or - {code --help}). Provides a definitive (if - somewhat terse) summary of the command line options - accepted by the {CCL} implementation and then - exits.") - (item "{code -V} (or {code --version}). Prints the version of - {CCL} then exits. The version string is the same value - that is returned by {function - lisp-implementation-version}.") - (item - (para "{code -K} {param character-encoding-name} (or - {code --terminal-encoding}{param character-encoding-name}). - Specifies the character encoding to use for - {variable *terminal-io*} (see {section Character Encodings}). Specifically, the - {param character-encoding-name} string - is uppercased and interned in the {code keyword} package. If an - encoding named by that keyword exists, - {variable *terminal-character-encoding-name*} is set to the name - of that encoding. The default us {code :utf-8}.")) - (item "{code -n} (or - {code --no-init}). If this option is given, the - init file is not loaded. This is useful if {CCL} is being - invoked by a shell script that should not be affected by - whatever customizations a user might have in place.") - (item "{code -e} {param form} - (or {code --eval}). An expression is read (via - {function read-from-string}) from the string - {param form} and evaluated. If - {param form} contains shell metacharacters, - it may be necessary to escape or quote them to prevent the - shell from interpreting them.") - (item "{code -l} {param path} - (or {code --load} {param path}). Loads file specified by - {param path}.") - (item "{code -T} {param n} (or - {code --set-lisp-heap-gc-threshold} {param n}). Sets the Lisp gc threshold to - {param n}. (see {section GC Page reclamation policy}") - (item "{code -Q} (or - {code --quiet}). Suppresses printing of - heralds and prompts when the {code --batch} - command line option is specified.") - (item "{code -R} {param n} (or - {code --heap-reserve}). Reserves - {param n} bytes for heap expansion. The - default is {code 549755813888}. (see {section Heap space allocation})") - (item "{code -S} {param n} (or - {code --stack-size}{param n}). Sets the size of the - initial control stack to {param n}. (see {section Thread Stack Sizes})") - (item "{code -Z} {param n} (or - {code --thread-stack-size}{param n}). Sets the size of the first - thread's stack to {param n}. (see {section Thread Stack Sizes})") - (item "{code -b} (or {code --batch}). Execute in batch mode. End-of-file - from {variable *standard-input*} causes {CCL} to exit, as do attempts to - enter a break loop.") - (item "{code --no-sigtrap} An obscure option for running under GDB.") - (item "{code -I} {param image-name} (or - {code --image-name} {param image-name}). Specifies the image - name for the kernel to load. Defaults to the kernel name - with the suffix {system .image} appended.")) - - "The {code --load} and {code --eval} options can each be provided - multiple times. They're executed in the order specified on the - command line, after the init file (if there is one) is loaded and - before the toplevel read-eval-print loop is entered. - - Finally, any arguments following the pseudo-argument {code --} are - not processed, and are made available to Lisp as the value of - {code ccl:*unprocessed-command-line-arguments*}.") - - (defsection "Running {CCL} as a Mac Application" - "If you want to run {CCL} as a double-clickable Macintosh application, you can do that. -A version of {CCL} is available from the Mac App Store if you would like to obtain it from -there. Alternatively you can build the IDE yourself: please see {section Building the IDE}. -Currently, it's not possible to use the Mac App Store version of {CCL} as a command-line -program.")) - -) ;chapter diff --git a/ccl-documentation/limits.ccldoc b/ccl-documentation/limits.ccldoc deleted file mode 100644 index c3f7cf5..0000000 --- a/ccl-documentation/limits.ccldoc +++ /dev/null @@ -1,19 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Implementation Limits" - -"Fixnums on 32-bit systems are 30 bits long, and cover the interval - (-536870912, 536870911). Fixnums on 64-bit systems are 61 bits - long, and cover the interval (-1152921504606846976, 1152921504606846975) - (see {section Tagging scheme}). - - Because 64-bit systems have large fixnums, - {variable internal-time-units-per-second} is 1000000 on 64-bit - systems. It remains 1000 on 32-bit systems. This enables much finer - grained timing on 64-bit systems." - - -) ;chapter - - - diff --git a/ccl-documentation/modifying.ccldoc b/ccl-documentation/modifying.ccldoc deleted file mode 100644 index 024e46c..0000000 --- a/ccl-documentation/modifying.ccldoc +++ /dev/null @@ -1,356 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Modifying {CCL}" - (defsection "Contributing Code Back to the {CCL} Project" - (para "This section is a placeholder, added as of August 2004. The - full text is being written, and will be added as soon as it is - available.")) - (defsection "Using {CCL} in \"development\" and in \"user\" mode" - #:|As it's distributed, {CCL} starts up with *PACKAGE* set to - the CL-USER package and with most predefined functions and - methods protected against accidental redefinition. The package - setting is of course a requirement of ANSI CL, and the - protection of predefined functions and methods is intended to - catch certain types of programming errors (accidentally - redefining a CL or CCL function) before those errors have a - chance to do much damage. - - These settings may make using {CCL} to develop {CCL} a bit - awkward, because much of that process assumes you are working in - the CCL package is current, and a primary purpose of {CCL} - development is to redefine some predefined, builtin functions. - The standard, "routine" ways of building {CCL} from sources (see - ) - COMPILE-CCL, XCOMPILE-CCL, and XLOAD-LEVEL-0 - bind - *PACKAGE* to the "CCL" package and enable the redefinition of - predefined functions; the symbols COMPILE-CCL, XCOMPILE-CCL, and - XLOAD-LEVEL-0 are additionally now exported from the "CCL" - package. - - Some other (more ad-hoc) ways of doing development on - {CCL}-compiling and/or loading individual files, - incrementally redefining individual functions-may be - awkward unless one reverts to the mode of operation which was - traditionally offered in {CCL}. Some {CCL} source files - - especially those that comprise the bootstrapping image sources - and the first few files in the "cold load" sequence - are - compiled and loaded in the "CCL" package but don't contain - (IN-PACKAGE "CCL") forms, since IN-PACKAGE doesn't work until - later in the cold load sequence. - - The somewhat bizarre behavior of both SET-USER-ENVIRONMENT - and SET-DEVELOPMENT-ENVIRONMENT with respect to the special - variables they affect is intended to allow those constructs to - take effect when the read-eval-print loop next returns to a - top-level '? ' prompt; the constructs can meaningfully be used - inside LOAD, for instance (recall that LOAD binds *PACKAGE*), - though using both constructs within the same LOAD call would - likely be pretty confusing. - - "user" and "development" are otherwise very generic terms; - here they're intended to enforce the distinction between "using" - {CCL} and "developing" it. - - The initial environment from which {CCL} images are - saved is one where (SET-USER-ENVIRONMENT T) has just been - called; in previous versions, it was effectively as if - (SET-DEVELOPMENT-ENVIRONMENT T) had just been called. - - Hopefully, most users of {CCL} can safely ignore these - issues most of the time. Note that doing (SET-USER-ENVIRONMENT - T) after loading one's own code (or 3rd-party code) into {CCL} - would protect that code (as well as {CCL}'s) from accidental - redefinition; that may be useful in some cases.|) - (defsection "The Kernel Debugger" - (para " In a perfect world, something like this couldn't - happen:") - (code-block " -Welcome to {CCL} Version x.y! -? (defun foo (x) - (declare (cons x)) - (cdr x)) -FOO - -? (foo -1) ;Oops. Too late ... -Unhandled exception 11 at 0x300e90c8, context->regs at #x7ffff6b8 -Continue/Debugger/eXit ? - ") - #:|As you may have noticed, it's not a perfect world; it's rare - that the cause (attempting to reference the CDR of -1, and therefore - accessing unmapped memory near location 0) of this effect (an - "Unhandled exception ..." message) is so obvious. - - The addresses printed in the message above aren't very useful - unless you're debugging the kernel with GDB (and they're often - very useful if you are.) - - Aside from causing an exception that the lisp kernel doesn't - know how to handle, one can also enter the kernel debugger (more) - deliberately:| - (code-block #:| -? (defun classify (n) - (cond ((> n 0) "Greater") - ((< n 0) "Less") - (t - ;; Sheesh ! What else could it be ? - (ccl::bug "I give up. How could this happen ?")))) -CLASSIFY - -? (classify 0) -Bug in {CCL} system code: -I give up. How could this happen ? -? for help -[12345] {CCL} kernel debugger: - |) - "CCL::BUG isn't quite the right tool for this example (a - call to BREAK or PRINT might do a better job of clearing up the - mystery), but it's sometimes helpful when those other tools - can't be used. The lisp error system notices, for instance, if - attempts to signal errors themselves cause errors to be - signaled; this sort of thing can happen if CLOS or the I/O - system are broken or missing. After some small number of - recursive errors, the error system gives up and calls - CCL::BUG. - - If one enters a '?' at the kernel debugger prompt, one - will see output like:" - (code-block " -(S) Find and describe symbol matching specified name -(B) Show backtrace -(X) Exit from this debugger, asserting that any exception was handled -(K) Kill {CCL} process -(?) Show this help - ") - (para #:|CCL::BUG just does an FF-CALL into the lisp kernel. If - the kernel debugger was invoked because of an unhandled - exception (such as an illegal memory reference) the OS kernel - saves the machine state ("context") in a data structure for us, - and in that case some additional options can be used to display - the contents of the registers at the point of the - exception. Another function-CCL::DBG-causes a special - exception to be generated and enters the lisp kernel debugger - with a non-null "context":|) - (code-block #:| -? (defun classify2 (n) - (cond ((> n 0) "Greater") - ((< n 0) "Less") - (t (dbg n)))) -CLASSIFY2 - -? (classify2 0) -Lisp Breakpoint -While executing: # -? for help -[12345] {CCL} kernel debugger: ? -(G) Set specified GPR to new value -(A) Advance the program counter by one instruction (use with caution!) -(D) Describe the current exception in greater detail -(R) Show raw GPR/SPR register values -(L) Show Lisp values of tagged registers -(F) Show FPU registers -(S) Find and describe symbol matching specified name -(B) Show backtrace -(X) Exit from this debugger, asserting that any exception was handled -(P) Propagate the exception to another handler (debugger or OS) -(K) Kill {CCL} process -(?) Show this help - |) - (para "CCL::DBG takes an argument, whose value is copied into the register - that {CCL} uses to return a function's primary value (arg_z, which - is r23 on the PowerPC). If we were to choose the (L) option at this point, - we'd see a dislay like:") - (code-block " -rnil = 0x01836015 -nargs = 0 -r16 (fn) = # -r23 (arg_z) = 0 -r22 (arg_y) = 0 -r21 (arg_x) = 0 -r20 (temp0) = #<26-element vector subtag = 2F @#x303793ee> -r19 (temp1/next_method_context) = 6393788 -r18 (temp2/nfn) = # -r17 (temp3/fname) = CLASSIFY2 -r31 (save0) = 0 -r30 (save1) = *TERMINAL-IO* -r29 (save2) = 0 -r28 (save3) = (# #) -r27 (save4) = () -r26 (save5) = () -r25 (save6) = () -r24 (save7) = () - ") - #:|From this we can conclude that the problematic argument to CLASSIFY2 - was 0 (see r23/arg_z), and that I need to work on a better example. - - The R option shows the values of the ALU (and PPC branch unit) - registers in hex; the F option shows the values of the FPU registers. - - The (B) option shows a raw stack backtrace; it'll try to - identify foreign functions as well as lisp functions. (Foreign function - names are guesses based on the nearest preceding exported symbol.) - - If you ever unexpectedly find yourself in the "lisp kernel - debugger", the output of the (L) and (B) options are often the most - helpful things to include in a bug report.|) - (defsection "Using AltiVec in {CCL} LAP functions" - (defsection "Overview" - "It's now possible to use AltiVec instructions in PPC LAP - (assembler) functions. - - The lisp kernel detects the presence or absence of - AltiVec and preserves AltiVec state on lisp thread switch and - in response to exceptions, but the implementation doesn't - otherwise use vector operations. - - This document doesn't document PPC LAP programming in - general. Ideally, there would be some document that - did. - - This document does explain AltiVec register-usage - conventions in {CCL} and explains the use of some lap macros - that help to enforce those conventions. - - All of the global symbols described below are exported - from the CCL package. Note that lap macro names, ppc - instruction names, and (in most cases) register names are - treated as strings, so this only applies to functions and - global variable names. - - Much of the {CCL} support for AltiVec LAP programming - is based on work contributed to MCL by Shannon Spires.") - (defsection "Register usage conventions" - #:|{CCL} LAP functions that use AltiVec instructions must - interoperate with each other and with C functions; that fact - suggests that they follow C AltiVec register usage - conventions. (vr0-vr1 scratch, vr2-vr13 parameters/return - value, vr14-vr19 temporaries, vr20-vr31 callee-save - non-volatile registers.) - - The EABI (Embedded Application Binary Interface) used in - LinuxPPC doesn't ascribe particular significance to the vrsave - special-purpose register; on other platforms (notably MacOS), - it's used as a bitmap which indicates to system-level code - which vector registers contain meaningful values. - - The WITH-ALTIVEC-REGISTERS lap macro generates code that - saves, updates, and restores VRSAVE on platforms where this is - required (as indicated by the value of the special variable - that controls this behavior) and ignores VRSAVE on platforms - that don't require it to be maintained. - - On all PPC platforms, it's necessary to save any non-volatile - vector registers (vr20 .. vr31) before assigning to them and to restore - such registers before returning to the caller. - - On platforms that require that VRSAVE be maintained, it's - not necessary to mention the "use" of vector registers that - are used as incoming parameters. It's not incorrect to mention - their use in a WITH-ALTIVEC-REGISTERS form, but it may be - unnecessary in many interesting cases. One can likewise assume - that the caller of any function that returns a vector value in - vr2 has already set the appropriate bit in VRSAVE to indicate - that this register is live. One could therefore write a leaf - function that added the bytes in vr3 and vr2 and returned the - result in vr2 as:| - (code-block " -(defppclapfunction vaddubs ((y vr3) (z vr2)) - (vaddubs z y z) - (blr)) - ") - (para "When vector registers that aren't incoming parameters are used - in a LAP function, WITH-ALTIVEC-REGISTERS takes care of maintaining VRSAVE - and of saving/restoring any non-volatile vector registers:") - (code-block " -(defppclapfunction load-array ((n arg_z)) - (check-nargs 1) - (with-altivec-registers (vr1 vr2 vr3 vr27) ; Clobbers imm0 - (li imm0 arch::misc-data-offset) - (lvx vr1 arg_z imm0) ; load MSQ - (lvsl vr27 arg_z imm0) ; set the permute vector - (addi imm0 imm0 16) ; address of LSQ - (lvx vr2 arg_z imm0) ; load LSQ - (vperm vr3 vr1 vr2 vr27) ; aligned result appears in VR3 - (dbg t)) ; Look at result in some debugger - (blr)) - ") - "AltiVec registers are not preserved by CATCH and UNWIND-PROTECT. - Since AltiVec is only accessible from LAP in {CCL} and since LAP - functions rarely use high-level control structures, this should rarely be - a problem in practice. - - LAP functions that use non-volatile vector registers and - that call (Lisp ?) code which may use CATCH or UNWIND-PROTECT - should save those vector registers before such a call and - restore them on return. This is one of the intended uses of - the WITH-VECTOR-BUFFER lap macro.")) - (defsection "Development-Mode Dictionary" - (definition (:variable *warn-if-redefine-kernel*) "*WARN-IF-REDEFINE-KERNEL*" nil - (defsection "Description" - #:|When true, attempts to redefine (via DEFUN or DEFMETHOD) - functions and methods that are marked as being - "predefined" signal continuable errors. - - Note that these are CERRORs, not warnings, and that - no lisp functions or methods have been defined in the kernel - in MCL or {CCL} since 1987 or so.|)) - (definition (:function set-development-environment) - "set-development-environment {code &optional} unmark-builtin-functions" nil - (defsection "Description" - (para #:|Arranges that the outermost special bindings of *PACKAGE* - and *WARN-IF-REDEFINE-KERNEL* restore values of the "CCL" - package and NIL to these variables, respectively. If the optional - argument is true, marks all globally defined functions and methods - as being "not predefined" (this is a fairly expensive - operation.)|))) - (definition (:function set-user-environment) "set-user-environment {code &optional} mark-builtin-functions" nil - (defsection "Description" - (para #:|Arranges that the outermost special bindings of *PACKAGE* - and *WARN-IF-REDEFINE-KERNEL* restore values of the - "CL-USER" package and T to these variables, respectively. - If the optional argument is true, marks all globally defined - functions and methods as being "predefined" (this is a - fairly expensive operation.)|))) - (definition (:variable *altivec-available*) "*ALTIVEC-AVAILABLE*" nil - (defsection "Description" - (para "This variable is initialized each time an {CCL} session - starts based on information provided by the lisp kernel. Its value - is true if AltiVec is present and false otherwise. This variable - shouldn't be set by user code."))) - (definition (:function altivec-available-p) "altivec-available-p" nil - (defsection "Description" (para "Returns non-NIL if AltiVec is available."))) - (definition (:variable *altivec-lapmacros-maintain-vrsave-p*) "*ALTIVEC-LAPMACROS-MAINTAIN-VRSAVE-P*" nil - (defsection "Description" - (para "Intended to control the expansion of certain lap macros. - Initialized to NIL on LinuxPPC; initialized to T on platforms - (such as MacOS X/Darwin) that require that the VRSAVE SPR contain - a bitmask of active vector registers at all times."))) - (definition (:lap-macro ccl::with-altivec-registers) "with-altivec-registers reglist {code &body} body" "Specify the test of Altivec registers used in the body." - (defsection "Arguments and Values" - (listing :definition - (item "{param reglist}" ccldoc::=> "A list of vector register names (vr0 .. vr31).") - (item "{param body}" ccldoc::=> "A sequence of PPC LAP instructions."))) - (defsection "Description" - (para "Specifies the set of AltiVec registers used in body. If - *altivec-lapmacros-maintain-vrsave-p* is true when the macro is - expanded, generates code to save the VRSAVE SPR and updates VRSAVE - to include a bitmask generated from the specified register list. - Generates code which saves any non-volatile vector registers which - appear in the register list, executes body, and restores the saved - non-volatile vector registers (and, if - *altivec-lapmacros-maintain-vrsave-p* is true, restores VRSAVE as - well. Uses the IMM0 register (r3) as a temporary."))) - (definition (:lap-macro ccl::with-vector-buffer) "with-vector-buffer base n {code &body} body" "Make space for saved Altivec registers." - (defsection "Arguments and Values" - (listing :definition - (item "{param base}" ccldoc::=> "Any available general-purpose register.") - (item "{param n}" ccldoc::=> "An integer between 1 and 254, inclusive. (Should - typically be much, much closer to 1.) Specifies the size of - the buffer, in 16-byte units.") - (item "{param body}" ccldoc::=> "A sequence of PPC LAP instructions."))) - (defsection "Description" - (para "Generates code which allocates a 16-byte aligned buffer - large enough to contain N vector registers; the GPR base points to - the lowest address of this buffer. After processing body, the - buffer will be deallocated. The body should preserve the value of - base as long as it needs to reference the buffer. It's - intended that base be used as a base register in stvx and lvx - instructions within the body."))))) diff --git a/ccl-documentation/mop.ccldoc b/ccl-documentation/mop.ccldoc deleted file mode 100644 index f97e444..0000000 --- a/ccl-documentation/mop.ccldoc +++ /dev/null @@ -1,139 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "CLOS Metaobject Protocol" - "{CCL} supports most of the semi-standard - metaobject protocol (MOP) for CLOS, as defined in chapters 5 and 6 - of “The Art Of The Metaobject Protocol”, - (Kiczales et al, MIT Press 1991, ISBN 0-262-61074-4); this - specification is also available online at {link - http://www.alu.org/mop/index.html}. - - Notably absent is support for the generic function invocation protocol. - - The keyword :openmcl-partial-mop is on {code *features*} to - indicate the presence of this functionality. - - All of the symbols defined in the MOP specification - (whether implemented or not) are exported from the {code ccl} - package and from the {code openmcl-mop} package." - - (table "MOP Implementation Status" - (row (item "construct") (item "status")) - (row (item "accessor-method-slot-definition") (item "+")) - (row (item "add-dependent") (item "+")) - (row (item "add-direct-method") (item "+")) - (row (item "add-direct-subclass") (item "+")) - (row (item "add-method") (item "+")) - (row (item "class-default-initargs") (item "+")) - (row (item "class-direct-default-initargs") (item "+")) - (row (item "class-direct-slots") (item "+")) - (row (item "class-direct-subclasses") (item "+")) - (row (item "class-direct-superclasses") (item "+")) - (row (item "class-finalized-p") (item "+")) - (row (item "class-prototype") (item "+")) - (row (item "class-slots") (item "+")) - (row (item "compute-applicable-methods") (item "-")) - (row (item "compute-applicable-methods-using-classes") (item "-")) - (row (item "compute-class-precedence-list") (item "+")) - (row (item "compute-direct-initargs") (item "+")) - (row (item "compute-discriminating-function") (item "-")) - (row (item "compute-effective-method") (item "+")) - (row (item "compute-effective-slot-definition") (item "+")) - (row (item "compute-slots") (item "+")) - (row (item "direct-slot-definition-class") (item "+")) - (row (item "effective-slot-definition-class") (item "+")) - (row (item "ensure-class") (item "+")) - (row (item "ensure-class-using-class") (item "+")) - (row (item "ensure-generic-function-using-class") (item "+")) - (row (item "eql-specializer-object") (item "+")) - (row (item "extract-lambda-list") (item "+")) - (row (item "extract-specializer-names") (item "+")) - (row (item "finalize-inheritance") (item "+")) - (row (item "find-method-combination") (item "+")) - (row (item "funcallable-standard-instance-access") (item "+")) - (row (item "generic-function-argument-precedence-order") (item "+")) - (row (item "generic-function-declarations") (item "+")) - (row (item "generic-function-lambda-list") (item "+")) - (row (item "generic-function-method-class") (item "+")) - (row (item "generic-function-method-combination") (item "+")) - (row (item "generic-function-methods") (item "+")) - (row (item "generic-function-name") (item "+")) - (row (item "intern-eql-specializer") (item "+")) - (row (item "make-method-lambda") (item "-")) - (row (item "map-dependents") (item "+")) - (row (item "method-function") (item "+")) - (row (item "method-generic-function") (item "+")) - (row (item "method-lambda-list") (item "+")) - (row (item "method-qualifiers") (item "+")) - (row (item "method-specializers") (item "+")) - (row (item "reader-method-class") (item "+")) - (row (item "remove-dependent") (item "+")) - (row (item "remove-direct-method") (item "+")) - (row (item "remove-direct-subclass") (item "+")) - (row (item "remove-method") (item "+")) - (row (item "set-funcallable-instance-function") (item "-")) - (row (item "slot-boundp-using-class") (item "+")) - (row (item "slot-definition-allocation") (item "+")) - (row (item "slot-definition-initargs") (item "+")) - (row (item "slot-definition-initform") (item "+")) - (row (item "slot-definition-initfunction") (item "+")) - (row (item "slot-definition-location") (item "+")) - (row (item "slot-definition-name") (item "+")) - (row (item "slot-definition-readers") (item "+")) - (row (item "slot-definition-type") (item "+")) - (row (item "slot-definition-writers") (item "+")) - (row (item "slot-makunbound-using-class") (item "+")) - (row (item "slot-value-using-class") (item "+")) - (row (item "specializer-direct-generic-functions") (item "+")) - (row (item "specializer-direct-methods") (item "+")) - (row (item "standard-instance-access") (item "+")) - (row (item "update-dependent") (item "+")) - (row (item "validate-superclass") (item "+")) - (row (item "writer-method-class") (item "+"))) - - "Note that those generic functions whose status is “-” in - the table above deal with the internals of generic function - dispatch and method invocation (the “generic function invocation - protocol”). Method functions are implemented a bit differently - in {CCL} from what the MOP expects, and it's not yet clear if - or how this subprotocol can be well-supported. - - Those constructs that are marked as “+” in the table above - are nominally implemented as the MOP document specifies - (deviations from the specification should be considered bugs; - please report them as such.) Note that some CLOS implementations - in widespread use (e.g., PCL) implement some things - (ENSURE-CLASS-USING-CLASS comes to mind) a bit differently from - what the MOP specifies." - - (defsection "Concurrency issues" - "The entire CLOS class and generic function hierarchy is - effectively a (large, complicated) shared data structure; it's - not generally practical for a thread to request exclusive access - to all of CLOS, and the effects of volitional modification of - the CLOS hierarchy (via class redefinition, {code change-class}, - etc.) in a multithreaded environment aren't always tractable. - - Native threads exacerbate this problem (in that they - increase the opportunities for concurrent modification and - access.) The implementation should try to ensure that a thread's - view of any subset of the CLOS hierarchy is consistent (to the - extent that that's possible) and should try to ensure that - incidental modifications of the hierarchy (cache updates, etc.) - happen atomically; it's not generally possible for the - implementation to guarantee that a thread's view of things is - correct and current. - - If you are loading code and defining classes in the most - usual way, which is to say, via the compiler, using only a - single thread, these issues are probably not going to affect you - much. - - If, however, you are making finicky changes to the class - hierarchy while you're running multiple threads which manipulate - objects related to each other, more care is required. Before - doing such a thing, you should know what you're doing and - already be aware of what precautions to take, without being - told. That said, if you do it, you should seriously consider - what your application's critical data is, and use locks for - critical code sections.")) diff --git a/ccl-documentation/objc-bridge.ccldoc b/ccl-documentation/objc-bridge.ccldoc deleted file mode 100644 index 611ca80..0000000 --- a/ccl-documentation/objc-bridge.ccldoc +++ /dev/null @@ -1,847 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "The Objective-C Bridge" - "Mac OS X APIs use a language called Objective-C, which is - approximately C with some object-oriented extensions modeled on - Smalltalk. The Objective-C bridge makes it possible to work with - Objective-C objects and classes from Lisp, and to define classes - in Lisp which can be used by Objective-C. - - The ultimate purpose of the Objective-C and Cocoa bridges is - to make Cocoa (the standard user-interface framework on Mac OS X) - as easy as possible to use from {CCL}, in order to support the - development of GUI applications and IDEs on Mac OS X (and on any - platform that supports Objective-C, such as GNUStep). The - eventual goal, which is much closer than it used to be, is - complete integration of Cocoa into CLOS. - - The current release provides Lisp-like syntax and naming - conventions for the basic Objective-C operations, with automatic type - processing and messages checked for validity at compile-time. It - also provides some convenience facilities for working with - Cocoa." - (defsection "Changes in 1.2" - (para "Version 1.2 of {CCL} exports most of the useful symbols - described in this chapter; in previous releases, most of them were - private in the {code CCL} package.") - (para "There are several new reader macros that make it much more - convenient than before to refer to several classes of symbols used - with the Objective-C bridge. For a full description of these - reader-macros, see - the " - (ref (section "The Foreign-Function-Interface Dictionary") "Foreign-Function-Interface Dictionary") - ", especially the entries at the beginning, - describing reader macros.") - "As in previous releases, 32-bit versions of {CCL} use 32-bit - floats and integers in data structures that describe geometry, - font sizes and metrics, and so on. 64-bit versions of {CCL} use - 64-bit values where appropriate. - - The Objective-C bridge defines the - type {code NS:CGFLOAT} as the Lisp type of the preferred - floating-point type on the current platform, and defines the - constant {code NS:+CGFLOAT+}. On DarwinPPC32, the foreign - types {code :cgfloat}, {code :nteger}, - and - {code :nteger} are defined by the Objective-C - bridge (as 32-bit float, 32-bit unsigned integer, and 32-bit - signed integer, respectively); these types are defined as 64-bit - variants in the 64-bit interfaces." - (para #:|Every Objective-C class is now properly named, either with a - name exported from the {code NS} package (in the case of a - predefined class declared in the interface files) or with the - name provided in the {code DEFCLASS} form (with {code :METACLASS}{code NS:+NS-OBJECT}) which defines the class from Lisp. - The class's Lisp name is now proclaimed to be a "static" - variable (as if by {code DEFSTATIC}, as described in the - | - (ref (section "Static Variables") #:|"Static Variables" section|) ") and given the class object as its value. In - other words:") - (code-block " -(send (find-class 'ns:ns-application) 'shared-application) - ") - (para "and") - (code-block " -(send ns:ns-application 'shared-application) - ") - (para #:|are equivalent. (Since it's not legal to bind a "static" - variable, it may be necessary to rename some things so that - unrelated variables whose names coincidentally conflict with - Objective-C class names don't do so.)|)) - (defsection "Using Objective-C Classes" - #:|The class of most standard CLOS classes is named - STANDARD-CLASS. In the Objective-C object model, each class is - an instance of a (usually unique) metaclass, which is itself an - instance of a "base" metaclass (often the metaclass of the class - named "NSObject".) So, the Objective-C class named "NSWindow" - and the Objective-C class "NSArray" are (sole) instances of - their distinct metaclasses whose names are also "NSWindow" and - "NSArray", respectively. (In the Objective-C world, it's much - more common and useful to specialize class behavior such as - instance allocation.) - - When {CCL} first loads foreign libraries containing - Objective-C classes, it identifies the classes they contain. The - foreign class name, such as "NSWindow", is mapped to an external - symbol in the "NS" package via the bridge's translation rules, - such as NS:NS-WINDOW. A similar transformation happens to the - metaclass name, with a "+" prepended, yielding something like - NS:+NS-WINDOW. - - These classes are integrated into CLOS such that the - metaclass is an instance of the class OBJC:OBJC-METACLASS and - the class - is an instance of the metaclass. SLOT-DESCRIPTION metaobjects are - created for each instance variable, and the class and metaclass go - through something very similar to the "standard" CLOS class - initialization protocol (with a difference being that these classes - have already been allocated.) - - Performing all this initialization, which is done when you - (require "COCOA"), currently takes several - seconds; it could conceivably be sped up some, but it's never likely - to be fast. - - When the process is complete, CLOS is aware of several hundred - new Objective-C classes and their metaclasses. {CCL}'s runtime system can - reliably recognize MACPTRs to Objective-C classes as being CLASS objects, and - can (fairly reliably but heuristically) recognize instances of those - classes (though there are complicating factors here; see below.) - SLOT-VALUE can be used to access (and, with care, set) instance - variables in Objective-C instances. To see this, do:| - (code-block #:| - ? (require "COCOA") - |) - (para "and, after waiting a bit longer for a Cocoa listener window to - appear, activate that Cocoa listener and do:") - (code-block "? (describe (ccl::send ccl::*NSApp* 'key-window)) - ") - (para "This sends a message asking for the key window, which is the window - that has the input focus (often the frontmost), and then describes - it. As we can see, NS:NS-WINDOWs have lots of interesting slots.")) - (defsection "Instantiating Objective-C Objects" - "Making an instance of an Objective-C class (whether the class in - question is predefined or defined by the application) involves - calling MAKE-INSTANCE with the class and a set of initargs as - arguments. As with STANDARD-CLASS, making an instance involves - initializing (with INITIALIZE-INSTANCE) an object allocated with - ALLOCATE-INSTANCE. - -For example, you can create an ns:ns-number like this:" - (code-block " - ? (make-instance 'ns:ns-number :init-with-int 42) - # - ") - (para "It's worth looking at how this would be done if you were - writing in Objective C:") - (code-block " - [[NSNumber alloc] initWithInt: 42] - ") - (para #:|Allocating an instance of an Objective-C class involves sending the - class an "alloc" message, and then using those initargs that - {emphasis don't} correspond to slot initargs as the - "init" message to be sent to the newly-allocated instance. So, the - example above could have been done more verbosely as:|) - (code-block " - ? (defvar *n* (ccl::send (find-class 'ns:ns-number) 'alloc)) - *N* - - ? (setq *n* (ccl::send *n* :init-with-int 42)) - # - ") - "That setq is important; this is a case where init - decides to replace the object and return the new one, instead - of modifying the existing one. - In fact, if you leave out the setq and - then try to view the value of *N*, {CCL} will freeze. There's - little reason to ever do it this way; this is just to show - what's going on. - - You've seen that an Objective-C initialization method doesn't have to - return the same object it was passed. In fact, it doesn't have - to return any object at all; in this case, the initialization fails - and make-instance returns nil. - - In some special cases, such as loading an ns:ns-window-controller - from a .nib file, it may be necessary for you to pass the - instance itself as one of the parameters to the initialization - method. It goes like this:" - (code-block #:| - ? (defvar *controller* - (make-instance 'ns:ns-window-controller)) - *CONTROLLER* - - ? (setq *controller* - (ccl::send *controller* - :init-with-window-nib-name #@"DataWindow" - :owner *controller*)) - # (#x1FB520)> - |) - #:|This example calls (make-instance) with no initargs. When you - do this, the object is only allocated, and not initialized. It - then sends the "init" message to do the initialization by hand. - - There is an alternative API for instantiating Objective-C - classes. You can - call {code OBJC:MAKE-OBJC-INSTANCE}, passing it the - name of the Objective-C class as a string. In previous - releases, {code OBJC:MAKE-OBJC-INSTANCE} could be - more efficient than {code OBJC:MAKE-INSTANCE} in - cases where the class did not define any Lisp slots; this is no - longer the case. You can now - regard {code OBJC:MAKE-OBJC-INSTANCE} as completely - equivalent to {code OBJC:MAKE-INSTANCE}, except that - you can pass a string for the classname, which may be convenient - in the case that the classname is in some way unusual.|) - (defsection "Calling Objective-C Methods" - (para #:|In Objective-C, methods are called "messages", and there's - a special syntax to send a message to an object:|) - (code-block " - [w alphaValue] - [w setAlphaValue: 0.5] - [v mouse: p inRect: r] - ") - #:|The first line sends the method "alphaValue" to the object - {code w}, with no parameters. The second line sends - the method "setAlphaValue", with the parameter 0.5. The third - line sends the method "mouse:inRect:" - yes, all one long word - - with the parameters {code p} and - {code r}. - -In Lisp, these same three lines are:| - (code-block " - (send w 'alpha-value) - (send w :set-alpha-value 0.5) - (send v :mouse p :in-rect r) - ") - "Notice that when a method has no parameters, its name is an ordinary - symbol (it doesn't matter what package the symbol is in, as - only its name is checked). When a method has parameters, - each part of its name is a keyword, and the keywords alternate - with the values. - - These two lines break those rules, and both will - result in error messages:" - (code-block " - (send w :alpha-value) - (send w 'set-alpha-value 0.5) - ") - (para "Instead of (send), you can also invoke (send-super), with the - same interface. It has roughly the same purpose as CLOS's - (call-next-method); when you use (send-super), the message is - handled by the superclass. This can be used to get at the - original implementation of a method when it is shadowed by a - method in your subclass.") - (defsection "Type Coercion for Objective-C Method Calls" - "{CCL}'s FFI handles many common conversions between - Lisp and foreign data, such as unboxing floating-point args - and boxing floating-point results. The bridge adds a few more - automatic conversions: - - NIL is equivalent to (%NULL-PTR) for any message - argument that requires a pointer. - -T/NIL are equivalent to #$YES/#$NO for any boolean argument. - - A #$YES/#$NO returned by any method that returns BOOL - will be automatically converted to T/NIL.") - (defsection "Methods which Return Structures" - #:|Some Cocoa methods return small structures, such as - those used to represent points, rects, sizes and ranges. When - writing in Objective C, the compiler hides the implementation - details. Unfortunately, in Lisp we must be slightly more - aware of them. - - Methods which return structures are called in a special - way; the caller allocates space for the result, and passes a - pointer to it as an extra argument to the method. This is - called a Structure Return, or STRET. Don't look at me; I - don't name these things. - - Here's a simple use of this in Objective C. The first line - sends the "bounds" message to v1, which returns a rectangle. - The second line sends the "setBounds" message to v2, passing - that same rectangle as a parameter.| - (code-block " - NSRect r = [v1 bounds]; - [v2 setBounds r]; - ") - (para "In Lisp, we must explicitly allocate the memory, which - is done most easily and safely with " - (ref (definition :macro rlet)) ". - We do it like this:") - (code-block " -(rlet ((r :ect)) - (send/stret r v1 'bounds) - (send v2 :set-bounds r)) - ") - "The rlet allocates the storage (but doesn't initialize - it), and makes sure that it will be deallocated when we're - done. It binds the variable r to refer to it. The call to - {code send/stret} is just like an ordinary call to - {code send}, except that r is passed as an extra, - first parameter. The third line, which calls - {code send}, does not need to do anything special, - because there's nothing complicated about passing a structure - as a parameter. - - In order to make STRETs easier to use, the bridge - provides two conveniences. - - First, you can use the macros {code slet} - and {code slet*} to allocate and initialize local - variables to foreign structures in one step. The example - above could have been written more tersely as:" - (code-block " -(slet ((r (send v1 'bounds))) - (send v2 :set-bounds r)) - ") - (para "Second, when one call to {code send} is made - inside another, the inner one has an implicit - {code slet} around it. So, one could in fact - just write:") - (code-block " -(send v1 :set-bounds (send v2 'bounds)) - ") - "There are also several pseudo-functions provided for convenience - by the Objective-C compiler, to make objects of specific types. The - following are currently supported by the bridge: NS-MAKE-POINT, - NS-MAKE-RANGE, NS-MAKE-RECT, and NS-MAKE-SIZE. - -These pseudo-functions can be used within an SLET initform:" - (code-block " -(slet ((p (ns-make-point 100.0 200.0))) - (send w :set-frame-origin p)) - ") - (para "Or within a call to {code send}:") - (code-block " -(send w :set-origin (ns-make-point 100.0 200.0)) - ") - (para "However, since these aren't real functions, a call like the - following won't work:") - (code-block " -(setq p (ns-make-point 100.0 200.0)) - ") - "To extract fields from these objects, there are also some - convenience macros: NS-MAX-RANGE, NS-MIN-X, - NS-MIN-Y, NS-MAX-X, NS-MAX-Y, NS-MID-X, NS-MID-Y, - NS-HEIGHT, and NS-WIDTH. - - Note that there is also a {code send-super/stret} - for use within methods. Like {code send-super}, - it ignores any shadowing methods in a subclass, and calls the - version of a method which belongs to its superclass.") - (defsection "Variable-Arity Messages" - (para " - There are a few messages in Cocoa which take variable numbers - of arguments. Perhaps the most common examples involve - formatted strings:") - (code-block #:| -[NSClass stringWithFormat: "%f %f" x y] - |) - (para "In Lisp, this would be written:") - (code-block #:| -(send (find-class 'ns:ns-string) - :string-with-format #@"%f %f" - (:double-float x :double-float y)) - |) - #:|Note that it's necessary to specify the foreign types of the - variables (in this example, :double-float), because the - compiler has no general way of knowing these types. (You - might think that it could parse the format string, but this - would only work for format strings which are not determined - at runtime.) - - Because the Objective-C runtime system does not provide any information - on which messages are variable arity, they must be explicitly - declared. The standard variable arity messages in Cocoa are - predeclared by the bridge. If you need to declare a new - variable arity message, use - (DEFINE-VARIABLE-ARITY-MESSAGE "myVariableArityMessage:").|) - (defsection "Optimization" - "The bridge works fairly hard to optimize message sends, - when it has enough information to do so. There are two cases - when it does. In either, a message send should be nearly as - efficient as when writing in Objective C. - - The first case is when both the message and the - receiver's class are known at compile-time. In general, the - only way the receiver's class is known is if you declare it, - which you can do with either a DECLARE or a THE form. For - example:" - (code-block " -(send (the ns:ns-window w) 'center) - ") - (para #:|Note that there is no way in Objective-C to name the class of a - class. Thus the bridge provides a declaration, @METACLASS. - The type of an instance of "NSColor" is ns:ns-color. The type - of the {emphasis class} "NSColor" is (@metaclass - ns:ns-color):|) - (code-block " -(let ((c (find-class 'ns:ns-color))) - (declare ((ccl::@metaclass ns:ns-color) c)) - (send c 'white-color)) - ") - "The other case that allows optimization is when only - the message is known at compile-time, but its type signature - is unique. Of the more-than-6000 messages currently provided - by Cocoa, only about 50 of them have nonunique type - signatures. - - An example of a message with a type signature that is - not unique is SET. It returns VOID for NSColor, but ID for - NSSet. In order to optimize sends of messages with nonunique - type signatures, the class of the receiver must be declared at - compile-time. - - If the type signature is nonunique or the message is - unknown at compile-time, then a slower runtime call must be - used. - - When the receiver's class is unknown, the bridge's - ability to optimize relies on a type-signature table which it - maintains. When first loaded, the bridge initializes this - table by scanning every method of every Objective-C class. When new - methods are defined later, the table must be updated. This - happens automatically when you define methods in Lisp. After - any other major change, such as loading an external framework, - you should rebuild the table:" - (code-block " -? (update-type-signatures) - ") - "Because {code send} and its relatives - {code send-super}, {code send/stret}, - and {code send-super/stret} are macros, they - cannot be {code funcall}ed, - {code apply}ed, or passed as arguments to - functions. - - To work around this, there are function equivalents to - them: {code %send}, - {code %send-super}, - {code %send/stret}, and - {code %send-super/stret}. However, these - functions should be used only when the macros will not do, - because they are unable to optimize.")) - (defsection "Defining Objective-C Classes" - "You can define your own foreign classes, which can then be - passed to foreign functions; the methods which you implement in - Lisp will be made available to the foreign code as - callbacks. - - You can also define subclasses of existing classes, - implementing your subclass in Lisp even though the parent class - was in Objective C. One such subclass is CCL::NS-LISP-STRING. - It is also particularly useful to make subclasses of - NS-WINDOW-CONTROLLER. - - We can use the MOP to define new Objective-C classes, but - we have to do something a little funny: the :METACLASS that we'd - want to use in a DEFCLASS option generally doesn't exist until - we've created the class (recall that Objective-C classes have, for the - sake of argument, unique and private metaclasses.) We can sort - of sleaze our way around this by specifying a known Objective-C - metaclass object name as the value of the DEFCLASS :METACLASS - object; the metaclass of the root class NS:NS-OBJECT, - NS:+NS-OBJECT, makes a good choice. To make a subclass of - NS:NS-WINDOW (that, for simplicity's sake, doesn't define any - new slots), we could do:" - (code-block " -(defclass example-window (ns:ns-window) - () - (:metaclass ns:+ns-object)) - ") - (para "That'll create a new Objective-C class named EXAMPLE-WINDOW whose - metaclass is the class named +EXAMPLE-WINDOW. The class will be - an object of type OBJC:OBJC-CLASS, and the metaclass will be of - type OBJC:OBJC-METACLASS. EXAMPLE-WINDOW will be a subclass of - NS-WINDOW.") - (defsection "Defining classes with foreign slots" - #:|If a slot specification in an Objective-C class - definition contains the keyword :FOREIGN-TYPE, the slot will - be a "foreign slot" (i.e. an Objective-C instance variable). Be aware - that it is an error to redefine an Objective-C class so that its - foreign slots change in any way, and {CCL} doesn't do - anything consistent when you try to. - - The value of the :FOREIGN-TYPE initarg should be a - foreign type specifier. For example, if we wanted (for some - reason) to define a subclass of NS:NS-WINDOW that kept track - of the number of key events it had received (and needed an - instance variable to keep that information in), we could - say:| - (code-block " -(defclass key-event-counting-window (ns:ns-window) - ((key-event-count :foreign-type :int - :initform 0 - :accessor window-key-event-count)) - (:metaclass ns:+ns-object)) - ") - (para "Foreign slots are always SLOT-BOUNDP, and the initform - above is redundant: foreign slots are initialized to binary - 0.")) - (defsection "Defining classes with Lisp slots" - (para #:|A slot specification in an Objective-C class definition that - doesn't contain the :FOREIGN-TYPE initarg defines a - pretty-much normal lisp slot that'll happen to be associated - with "an instance of a foreign class". For instance:|) - (code-block " -(defclass hemlock-buffer-string (ns:ns-string) - ((hemlock-buffer :type hi::hemlock-buffer - :initform hi::%make-hemlock-buffer - :accessor string-hemlock-buffer)) - (:metaclass ns:+ns-object)) - ") - (para #:|As one might expect, this has memory-management - implications: we have to maintain an association between a - MACPTR and a set of lisp objects (its slots) as long as the - Objective-C instance exists, and we have to ensure that the Objective-C - instance exists (does not have its -dealloc method called) - while lisp is trying to think of it as a first-class object - that can't be "deallocated" while it's still possible to - reference it. Associating one or more lisp objects with a - foreign instance is something that's often very useful; if you - were to do this "by hand", you'd have to face many of the same - memory-management issues.|))) - (defsection "Defining Objective-C Methods" - "In Objective-C, unlike in CLOS, every method belongs to some - particular class. This is probably not a strange concept to - you, because C++ and Java do the same thing. When you use Lisp - to define Objective-C methods, it is only possible to define methods - belonging to Objective-C classes which have been defined in - Lisp. - - You can use either of two different macros to define methods - on Objective-C classes. {code define-objc-method} - accepts a two-element list containing a message selector name - and a class name, and a body. {code objc:defmethod} - superficially resembles the normal - CLOS {code defmethod}, but creates methods on - Objective-C classes with the same restrictions as those created - by {code define-objc-method}." - (defsection "Using define-objc-method" - "As described in the - section {section Calling Objective-C Methods}, the names of Objective-C methods - are broken into pieces, each piece followed by a parameter. - The types of all parameters must be explicitly - declared. - - Consider a few examples, meant to illustrate the use - of {code define-objc-method}. Let us define a - class to use in them:" - (code-block " -(defclass data-window-controller (ns:ns-window-controller) - ((window :foreign-type :id :accessor window) - (data :initform nil :accessor data)) - (:metaclass ns:+ns-object)) - ") - "There's nothing special about this class. It inherits from - {code ns:ns-window-controller}. It has two slots: - {code window} is a foreign slot, stored in the Objective-C - world; and {code data} is an ordinary slot, stored - in the Lisp world. - - Here is an example of how to define a method which takes no - arguments:" - (code-block " -(define-objc-method ((:id get-window) - data-window-controller) - (window self)) - ") - "The return type of this method is the foreign type :id, - which is used for all Objective-C objects. The name of the - method is - {code get-window}. The body of the method is the - single line {code (window self)}. The - variable {code self} is bound, within the body, to - the instance that is receiving the message. The call - to {code window} uses the CLOS accessor to get the - value of the window field. - - Here's an example that takes a parameter. Notice that the - name of the method without a parameter was an ordinary symbol, - but with a parameter, it's a keyword:" - (code-block " -(define-objc-method ((:id :init-with-multiplier (:int multiplier)) - data-window-controller) - (setf (data self) (make-array 100)) - (dotimes (i 100) - (setf (aref (data self) i) - (* i multiplier))) - self) - ") - "To Objective-C code that uses the class, the name of this - method is {code initWithMultiplier:}. The name of - the parameter is - {code multiplier}, and its type - is {code :int}. The body of the method does some - meaningless things. Then it returns - {code self}, because this is an initialization - method. - -Here's an example with more than one parameter:" - (code-block " -(define-objc-method ((:id :init-with-multiplier (:int multiplier) - :and-addend (:int addend)) - data-window-controller) - (setf (data self) (make-array size)) - (dotimes (i 100) - (setf (aref (data self) i) - (+ (* i multiplier) - addend))) - self) - ") - #:|To Objective-C, the name of this method is - {code initWithMultiplier:andAddend:}. Both - parameters are of type {code :int}; the first is - named {code multiplier}, and the second - is {code addend}. Again, the method returns - {code self}. - - Here is a method that does not return any value, a so-called - "void method". Where our other methods - said {code :id}, this one - says {code :void} for the return type:| - (code-block " -(define-objc-method ((:void :take-action (:id sender)) - data-window-controller) - (declare (ignore sender)) - (dotimes (i 100) - (setf (aref (data self) i) - (- (aref (data self) i))))) - ") - "This method would be called {code takeAction:} - in Objective-C. The convention for methods that are going to be - used as Cocoa actions is that they take one parameter, which is - the object responsible for triggering the action. However, this - method doesn't actually need to use that parameter, so it - explicitly ignores it to avoid a compiler warning. As promised, - the method doesn't return any value. - - There is also an alternate syntax, illustrated here. The - following two method definitions are equivalent:" - (code-block #:| -(define-objc-method ("applicationShouldTerminate:" - "LispApplicationDelegate") - (:id sender :) - (declare (ignore sender)) - nil) - -(define-objc-method ((: - :application-should-terminate sender) - lisp-application-delegate) - (declare (ignore sender)) - nil) - |)) - (defsection "Using objc:defmethod" - "The macro {code OBJC:DEFMETHOD} can be used to - define Objective-C methods. It looks superficially like - {code CL:DEFMETHOD} in some respects. - -Its syntax is" - (code-block " -(OBC:DEFMETHOD name-and-result-type - ((receiver-arg-and-class) {code &rest} other-args) - {code &body} body) - ") - #:|{code name-and-result-type} is either an - Objective-C message name, for methods that return a value of - type {code :ID}, or a list containing an - Objective-C message name and a foreign type specifier for - methods with a different foreign result type. - - {code receiver-arg-and-class} is a two-element - list whose first element is a variable name and whose second - element is the Lisp name of an Objective-C class or metaclass. - The receiver variable name can be any bindable lisp variable - name, but {code SELF} might be a reasonable - choice. The receiver variable is declared to be "unsettable"; - i.e., it is an error to try to change the value of the - receiver in the body of the method definition. - - {code other-args} are either variable names - (denoting parameters of type {code :ID}) or - 2-element lists whose first element is a variable name and - whose second element is a foreign type specifier. - -Consider this example:| - (code-block " -(objc:defmethod (#/characterAtIndex: :unichar) - ((self hemlock-buffer-string) (index :nteger)) - ...) - ") - #:|The method {code characterAtIndex:}, when - invoked on an object of - class {code HEMLOCK-BUFFER-STRING} with an - additional argument of - type {code :integer} returns a value of - type - {code :unichar}. - - Arguments that wind up as some pointer type other - than {code :ID} (e.g. pointers, records passed by - value) are represented as typed foreign pointers, so that the - higher-level, type-checking accessors can be used on arguments - of - type {code :ns-rect}, {code :ns-point}, - and so on. - - Within the body of methods defined - via {code OBJC:DEFMETHOD}, the local function - {code CL:CALL-NEXT-METHOD} is defined. It isn't - quite as general as {code CL:CALL-NEXT-METHOD} is - when used in a CLOS method, but it has some of the same - semantics. It accepts as many arguments as are present in the - containing method's {code other-args} list and - invokes version of the containing method that would have been - invoked on instances of the receiver's class's superclass with - the receiver and other provided arguments. (The idiom of - passing the current method's arguments to the next method is - common enough that the {code CALL-NEXT-METHOD} in - {code OBJC:DEFMETHODs} should probably do this if - it receives no arguments.) - - A method defined via {code OBJC:DEFMETHOD} - that returns a structure "by value" can do so by returning a - record created via {code MAKE-GCABLE-RECORD}, by - returning the value returned - via {code CALL-NEXT-METHOD}, or by other similar - means. Behind the scenes, there may be a pre-allocated - instance of the record type (used to support native - structure-return conventions), and any value returned by the - method body will be copied to this internal record instance. - Within the body of a method defined - with {code OBJC:DEFMETHOD} that's declared to - return a structure type, the local macro - {code OBJC:RETURNING-FOREIGN-STRUCT} can be used - to access the internal structure. For example:| - (code-block " -(objc:defmethod (#/reallyTinyRectangleAtPoint: :ns-rect) - ((self really-tiny-view) (where :ns-point)) - (objc:returning-foreign-struct (r) - (ns:init-ns-rect r (ns:ns-point-x where) (ns:ns-point-y where) - single-float-epsilon single-float-epsilon) - r)) - ") - (para "If the {code OBJC:DEFMETHOD} creates a new - method, then it displays a message to that effect. These - messages may be helpful in catching errors in the names of - method definitions. In addition, if - a {code OBJC:DEFMETHOD} form redefines a method in - a way that changes its type signature, {CCL} signals a - continuable error.")) - (defsection "Method Redefinition Constraints" - "Objective C was not designed, as Lisp was, with runtime - redefinition in mind. So, there are a few constraints about - how and when you can replace the definition of an Objective C - method. Currently, if you break these rules, nothing will - collapse, but the behavior will be confusing; so - don't. - - Objective C methods can be redefined at runtime, but - their signatures shouldn't change. That is, the types of the - arguments and the return type have to stay the same. The - reason for this is that changing the signature changes the - selector which is used to call the method. - - When a method has already been defined in one class, and - you define it in a subclass, shadowing the original method, - they must both have the same type signature. There is no such - constraint, though, if the two classes aren't related and the - methods just happen to have the same name.")) - (defsection "Loading Frameworks" - "On Mac OS X, a framework is a structured directory - containing one or more shared libraries along with metadata such - as C and Objective-C header files. In some cases, frameworks may - also contain additional items such as executables. - - Loading a framework means opening the shared libraries and - processing any declarations so that {CCL} can subsequently call - its entry points and use its data structures. {CCL} provides the - function {code OBJC:LOAD-FRAMEWORK} for this - purpose." - (code-block " -(OBJC:LOAD-FRAMEWORK framework-name interface-dir) - ") - #:|{code framework-name} is a string that names the - framework (for example, "Foundation", or "Cocoa"), - and {code interface-dir} is a keyword that names the - set of interface databases associated with the named framework - (for example, {code :foundation}, - or {code :cocoa}). - - Assuming that interface databases for the named frameworks - exist on the standard search - path, {code OBJC:LOAD-FRAMEWORK} finds and initializes - the framework bundle by searching OS X's standard framework search - paths. Loading the named framework may create new Objective-C - classes and methods, add foreign type descriptions and entry - points, and adjust {CCL}'s dispatch functions. - - If interface databases don't exist for a framework you want - to use, you will need to create them. For more information about - creating interface databases, - see {section Creating new interface directories}.|) - (defsection "How Objective-C Names are Mapped to Lisp Symbols" - #:|There is a standard set of naming conventions for Cocoa - classes, messages, etc. As long as they are followed, the - bridge is fairly good at automatically translating between Objective-C - and Lisp names. - - For example, "NSOpenGLView" becomes ns:ns-opengl-view; - "NSURLHandleClient" becomes ns:ns-url-handle-client; and - "nextEventMatchingMask:untilDate:inMode:dequeue:" becomes - (:next-event-matching-mask :until-date :in-mode :dequeue). What - a mouthful. - - To see how a given Objective-C or Lisp name will be translated by - the bridge, you can use the following functions:| - (listing :column - (item "(ccl::objc-to-lisp-classname string)") - (item "(ccl::lisp-to-objc-classname symbol)") - (item "(ccl::objc-to-lisp-message string)") - (item "(ccl::lisp-to-objc-message string)") - (item "(ccl::objc-to-lisp-init string)") - (item "(ccl::lisp-to-objc-init keyword-list)")) - "Of course, there will always be exceptions to any naming - convention. Please tell us on the mailing lists if you come - across any name translation problems that seem to be bugs. - Otherwise, the bridge provides two ways of dealing with - exceptions: - - First, you can pass a string as the class name of - MAKE-OBJC-INSTANCE and as the message to SEND. These strings - will be directly interpreted as Objective-C names, with no - translation. This is useful for a one-time exception. For - example:" - (code-block #:| -(ccl::make-objc-instance "WiErDclass") -(ccl::send o "WiErDmEsSaGe:WithARG:" x y) - |) - (para "Alternatively, you can define a special translation rule - for your exception. This is useful for an exceptional name that - you need to use throughout your code. Some examples:") - (code-block #:| -(ccl::define-classname-translation "WiErDclass" wierd-class) -(ccl::define-message-translation "WiErDmEsSaGe:WithARG:" (:weird-message :with-arg)) -(ccl::define-init-translation "WiErDiNiT:WITHOPTION:" (:weird-init :option)) - |) - (para #:|The normal rule in Objective-C names is that each word begins with a - capital letter (except possibly the first). Using this rule - literally, "NSWindow" would be translated as N-S-WINDOW, which - seems wrong. "NS" is a special word in Objective-C that should not be - broken at each capital letter. Likewise "URL", "PDF", "OpenGL", - etc. Most common special words used in Cocoa are already defined - in the bridge, but you can define new ones as follows:|) - (code-block #:| -(ccl::define-special-objc-word "QuickDraw") - |) - #:|Note that message keywords in a SEND such as (SEND V - :MOUSE P :IN-RECT R) may look like the keyword arguments in a - Lisp function call, but they really aren't. All keywords must be - present and the order is significant. Neither (:IN-RECT :MOUSE) - nor (:MOUSE) translate to "mouse:inRect:" - - Also, as a special exception, an "init" prefix is optional - in the initializer keywords, so (MAKE-OBJC-INSTANCE 'NS-NUMBER - :INIT-WITH-FLOAT 2.7) can also be expressed as - (MAKE-OBJC-INSTANCE 'NS-NUMBER :WITH-FLOAT 2.7)|)) \ No newline at end of file diff --git a/ccl-documentation/os.ccldoc b/ccl-documentation/os.ccldoc deleted file mode 100644 index 1aa1476..0000000 --- a/ccl-documentation/os.ccldoc +++ /dev/null @@ -1,44 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Operating System Interface" - (definition (:function getenv) "getenv name" nil - "This function looks up the value of the environment variable - denoted by the string {param name} and returns its value as a - string. If there is no such envionment variable, then {code nil} - is returned.") - - (definition (:function setenv) "setenv name value" nil - "This function sets the operating system environment variable - denoted by the string {param name} to the string {param value}. - If the environment variable is successfully set, 0 is returned. - Otherwise, a platform-specific integer error code is returned.") - - (definition (:function wait-for-signal) "wait-for-signal sig duration" nil - "Wait for the signal with signal number {param sig} to be received, - or until {param duration} seconds have elapsed. If {param - duration} is {code nil}, wait for an indeterminate very long - time (many years). - - If {param sig} is outside the range of valid signals, or reserved - by {CCL} for its own use, an error is signaled. An error is - always signaled on Windows systems.") - - (definition (:function quit) "quit &optional (exit 0) &key error-handler" nil - "Cleanly exit from lisp. If {param exit} is a value of type - {code (signed-byte 32)}, that value will be passed to the C - library function {code _exit()} as the status code. A value of - {code nil} is treated as a zero. - - Alternatively, {param exit} may be a function of no arguments. - This function will be called instead of {code _exit()} to exit - the lisp. - - If the {code :error-handler} keyword argument is supplied, it - must be a function of one argument, the condition, that will be - called if an error occurs when preparing to quit. The - error-handler function should exit the lisp.") - - ) ;chapter - - - diff --git a/ccl-documentation/platform-notes.ccldoc b/ccl-documentation/platform-notes.ccldoc deleted file mode 100644 index b63cf97..0000000 --- a/ccl-documentation/platform-notes.ccldoc +++ /dev/null @@ -1,497 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Platform-specific notes" - (defsection "Overview" - (para " The documentation and whatever experience you may have in - using {CCL} under Linux should also apply to using it under - Darwin/MacOS X and FreeBSD. There are some differences between - the platforms, and these differences are sometimes exposed in - the implementation.") - - (defsection "File-system case" - #:|Darwin and MacOS X use HFS+ file systems by default; - HFS+ file systems are usually case-insensitive. Most of - {CCL}'s filesystem and pathname code assumes that the - underlying filesystem is case-sensitive; this assumption - extends to functions like EQUAL, which assumes that #p"FOO" - and #p"foo" denote different, un-EQUAL filenames. Since - Darwin/MacOS X can also use UFS and NFS filesystems, the - opposite assumption would be no more correct than the one - that's currently made. - - Whatever the best solution to this problem turns out to - be, there are some practical considerations. Doing:| - (code-block #:| -? (save-application "DPPCCL") - |) - #:|on 32-bit DarwinPPC has the unfortunate side-effect of - trying to overwrite the Darwin {CCL} kernel, "dppccl", on a - case-insensitive filesystem. - - To work around this, the Darwin {CCL} kernel expects - the default heap image file name to be the kernel's own - filename with the string ".image" appended, so the idiom would - be:| - (code-block #:| -? (save-application "dppccl.image") - |)) - (defsection "Line Termination Characters" - #:|MacOSX effectively supports two distinct line-termination - conventions. Programs in its Darwin substrate follow the Unix - convention of recognizing #\\LineFeed as a line terminator; traditional - MacOS programs use #\\Return for this purpose. Many modern - GUI programs try to support several different line-termination - conventions (on the theory that the user shouldn't be too concerned - about what conventions are used an that it probably doesn't matter. - Sometimes this is true, other times ... not so much. - - - {CCL} follows the Unix convention on both Darwin and - LinuxPPC, but offers some support for reading and writing - files that use other conventions (including traditional MacOS - conventions) as well. - - This support (and anything like it) is by nature - heuristic: it can successfully hide the distinction between - newline conventions much of the time, but could mistakenly - change the meaning of otherwise correct programs (typically - when files contain both #\\Return and #\\Linefeed characters or - when files contain mixtures of text and binary data.) Because - of this concern, the default settings of some of the variables - that control newline translation and interpretation are - somewhat conservative. - - Although the issue of multiple newline conventions - primarily affects MacOSX users, the functionality described - here is available under LinuxPPC as well (and may occasionally - be useful there.) - - None of this addresses issues - related to the third newline convention ("CRLF") in widespread - use (since that convention isn't native to any platform on - which {CCL} currently runs). If {CCL} is ever ported to - such a platform, that issue might be revisited. - - Note that some MacOS programs (including some versions - of commercial MCL) may use HFS file type information to - recognize TEXT and other file types and so may fail to - recognize files created with {CCL} or other Darwin - applications (regardless of line termination issues.) - - Unless otherwise noted, the symbols mentioned in this - documentation are exported from the CCL package.|) - (defsection "Single-precision trig & transcendental functions" - (para " - Despite what Darwin's man pages say, early versions of its math library - (up to and including at least OSX 10.2 (Jaguar) don't implement - single-precision variants of the transcendental and trig functions - (#_sinf, #_atanf, etc.) {CCL} worked around this by coercing - single-precision args to double-precision, calling the - double-precision version of the math library function, and coercing - the result back to a SINGLE-FLOAT. These steps can introduce rounding - errors (and potentially overflow conditions) that might not be present - or as severe if true 32-bit variants were available.")) - (defsection "Shared libraries" - (para #:|Darwin/MacOS X distinguishes between "shared libraries" - and "bundles" or "extensions"; Linux and FreeBSD don't. In - Darwin, "shared libraries" have the file type "dylib" : the - expectation is that this class of file is linked against when - executable files are created and loaded by the OS when the - executable is launched. The latter class - - "bundles/extensions" - are expected to be loaded into and - unloaded from a running application, via a mechanism like the - one used by {CCL}'s OPEN-SHARED-LIBRARY function.|))) - - (defsection "Cocoa Programming in {CCL}" - "Cocoa is one of Apple's APIs for GUI programming; for most - purposes, development is considerably faster with Cocoa than - with the alternatives. You should have a little familiarity - with it, to better understand this section. - - A small sample Cocoa program can be invoked by evaluating - (REQUIRE 'TINY) and then (CCL::TINY-SETUP). This program - provides a simple example of using several of the bridge's - capabilities. - - The Tiny demo creates Cocoa objects dynamically, at - runtime, which is always an option. However, for large - applications, it is usually more convenient to create your - objects with Apple Interface Builder, and store them in .nib - files to be loaded when needed. Both approaches can be freely - mixed in a single program." - (defsection "The Command Line and the Window System" - "{CCL} is ordinarily a command-line application (it - doesn't have a connection to the OSX Window server, doesn't - have its own menubar or dock icon, etc.) By opening some - libraries and jumping through some hoops, it's able to sort of - transform itself into a full-fledged GUI application (while - retaining its original TTY-based listener.) The general idea - is that this hybrid environment can be used to test and - protoype UI ideas and the resulting application can eventually - be fully transformed into a bundled, double-clickable - application. This is to some degree possible, but there needs - to be a bit more infrastructure in place before many people - would find it easy. - - Cocoa applications use the NSLog function to write - informational/warning/error messages to the application's - standard output stream. When launched by the Finder, a GUI - application's standard output is diverted to a logging - facility that can be monitored with the Console application - (found in /Applications/Utilities/Console.app). In the hybrid - environment, the application's standard output stream is - usually the initial listener's standard output stream. With - two different buffered stream mechanisms trying to write to - the same underlying Unix file descriptor, it's not uncommon to - see NSLog output mixed with lisp output on the initial - listener.") - (defsection "Writing (and reading) Cocoa code" - #:|The - syntax of the constructs used to define Cocoa classes and - methods has changed a bit (it was never documented outside of - the source code and never too well documented at all), largely - as the result of functionality offered by Randall Beer's - bridge; the "standard name-mapping conventions" - referenced below are described in his CocoaBridgeDoc.txt file, - as are the constructs used to invoke ("send messages - to") Cocoa methods. - - All of the symbols described below are currently internal to - the CCL package.| - (listing :column - (item (ref (definition :macro objc:@class))) - (item (ref (definition :macro objc:@selector))) - (item (ref (definition :macro objc:define-objc-method))) - (item (ref (definition :macro objc:define-objc-class-method))))) - (defsection "The Application Kit and Multiple Threads" - #:|The Cocoa API is broken into several pieces. The - Application Kit, affectionately called AppKit, is the one - which deals with window management, drawing, and handling - events. AppKit really wants all these things to be done by a - "distinguished thread". creation, and drawing to take place - on a distinguished thread. - - Apple has published some guidelines which discuss these - issues in some detail; see the Apple Multithreading - Documentation, and in particular the guidelines on Using the - Application Kit from Multiple Threads. The upshot is that - there can sometimes be unexpected behavior when objects are - created in threads other than the distinguished event thread; - eg, the event thread sometimes starts performing operations on - objects that haven't been fully initialized. - - It's - certainly more convenient to do certain types of exploratory - programming by typing things into a listener or evaluating a - "defun" in an Emacs buffer; it may sometimes be - necessary to be aware of this issue while doing so. - - Each thread in the Cocoa runtime system is expected to - maintain a current "autorelease pool" (an instance - of the NSAutoreleasePool class); newly created objects are - often added to the current autorelease pool (via the - -autorelease method), and periodically the current autorelease - pool is sent a "-release" message, which causes it - to send "-release" messages to all of the objects - that have been added to it. - - If the current thread doesn't have a current autorelease - pool, the attempt to autorelease any object will result in a - severe-looking warning being written via NSLog. The event - thread maintains an autorelease pool (it releases the current - pool after each event is processed and creates a new one for - the next event), so code that only runs in that thread should - never provoke any of these severe-looking NSLog - messages. - - To try to suppress these messages (and - still participate in the Cocoa memory management scheme), each - listener thread (the initial listener and any created via the - "New Listener" command in the IDE) is given a - default autorelease pool; there are REPL colon-commands for - manipulating the current listener's "toplevel - autorelease pool". - - In the current scheme, every time that Cocoa calls lisp - code, a lisp error handler is established which maps any lisp - conditions to ObjC exceptions and arranges that this exception - is raised when the callback to lisp returns. Whenever lisp - code invokes a Cocoa method, it does so with an ObjC exception - handler in place; this handler maps ObjC exceptions to lisp - conditions and signals those conditions. - - Any - unhandled lisp error or ObjC exception that occurs during the - execution of the distinguished event thread's event loop - causes a message to be NSLog'ed and the event loop to (try to) - continue execution. Any error that occurs in other threads is - handled at the point of the outermost Cocoa method - invocation. (Note that the error is not necessarily - "handled" in the dynamic context in which it - occurs.) - - Both of these behaviors could possibly be improved; both of them - seem to be substantial improvements over previous behaviors (where, - for instance, a misspelled message name typically terminated the - application.)|) - (defsection "Acknowledgement" - (para "The Cocoa bridge was originally developed, and - generously contributed by, Randall Beer."))) - (defsection "Building an Application Bundle" - (para #:|You may have noticed that (require "COCOA") takes a long - time to load. It is possible to avoid this by saving a Lisp - heap image which has everything already loaded. There is an - example file which allows you to do this, - "ccl/examples/cocoa-application.lisp", by producing a - double-clickable application which runs your program. First, - load your own program. Then, do:|) - (code-block #:| -? (require "COCOA-APPLICATION") - |) - "When it finishes, you should be able to double-click the {CCL} icon - in the ccl directory, to quickly start your program. - - The OS may have already decided that {CCL}.app isn't a valid - executable bundle, and therefore won't let you double-click it. - If this happens to you, to force it to reconsider, just update the - last-modified time of the bundle. In Terminal:" - (code-block "> touch {CCL}.app - ") - (para #:|When an image which had contained ObjC classes (which are also - CLOS classes) is re-launched, those classes are "revived": all - preexisting classes have their addresses updated destructively, so that - existing subclass/superclass/metaclass relationships are maintained. - It's not possible (and may never be) to preserve foreign - instances across SAVE-APPLICATION. (It may be the case that NSArchiver - and NSCoder and related classes offer some approximation of that.)|)) - (defsection "Recommended Reading" - (listing :definition - (item - (clause - "{link http://developer.apple.com/technologies/mac/cocoa.html Mac OS X - Cocoa}, {link http://developer.apple.com/library/mac/#documentation/General/Conceptual/DevPedia-CocoaCore/Cocoa.html - Cocoa Core Competencies - }, {link http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaFundamentals/WhatIsCocoa/WhatIsCocoa.html - Cocoa Fundamentals Guide - }") - ccldoc::=> " - These are top-level pages pertaining to Cocoa in Apple's Mac OS X Developer Library. - If you are unfamiliar with Cocoa, these links are good places to start. - ") - (item - (clause - "{link http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjectiveC/Introduction/introObjectiveC.html - The Objective-C Programming Language - }, {link http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Introduction/Introduction.html - Objective-C Runtime Programming Guide - }") - ccldoc::=> - "These provide a conceptual overview and programming guide to Objective-C the language and runtime, respectively.") - (item - "{link http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html - Objective-C Runtime Reference - }" - ccldoc::=> " - This is one of the two most important Cocoa references; it - covers all of the basics, except for GUI programming. This is - a reference, not a tutorial. - ") - (item - "{link http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/index.html Application Kit Framework Reference}" - ccldoc::=> " - This is the other very important Cocoa reference; it covers GUI programming with Cocoa / Application Kit Framework - in considerable depth. This is a reference, not a tutorial. - ") - (item "{link http://developer.apple.com/library/mac/navigation/ Mac OS X Developer Library}" ccldoc::=> " - This is the top page for Mac OS X developer documentation. - Go here to find the documentation on any other Mac OS X API. - Also go here if you need general guidance about OS X, Carbon, - Cocoa, Core Foundation, or Objective-C. - ") - (item "{link http://developer.apple.com/ Resources for Apple Developers}" ccldoc::=> " - This is the top page for all Apple developer documentation. - "))) - (defsection "Operating-System Dictionary" - - (definition (:macro objc:@class) "@class class-name" nil - (defsection "Arguments and Values" - (listing :definition - (item "{param class-name}" ccldoc::=> "a string which denotes an existing class name, or a - symbol which can be mapped to such a string via the standard - name-mapping conventions for class names"))) - (defsection "Description" - "Used to refer to a known ObjC class by name. (Via the use - LOAD-TIME-VALUE, the results of a class-name -> class lookup - are cached.) - - {function objc:@class} is obsolete as of late 2004, because - find-class now works on ObjC classes. It is described here - only because some old code still uses it. - ")) - - (definition (:macro objc:@selector) "@selector string" nil - (defsection "Arguments and Values" - (listing :definition - (item "{param string}" ccldoc::=> "a string constant, used to canonically refer to an - ObjC method selector"))) - (defsection "Description" - (para "Used to refer to an ObjC method selector (method name). Uses - LOAD-TIME-VALUE to cache the result of a string -> selector - lookup."))) - - (definition (:macro objc:defmethod) - "objc:defmethod name-and-result-type ((receiver-arg-and-class) {code &rest} other-args) {code &body} body" nil - (defsection "Arguments and Values" - (listing :definition - (item "{param name-and-result-type}" ccldoc::=> "either an Objective-C message name, for methods - that return a value of type {code :ID}, or - a list containing an Objective-C message name and a - foreign type specifier for methods with a different - foreign result type.") - (item "{param receiver-arg-and-class}" ccldoc::=> #:|a two-element list whose first element is a - variable name and whose second element is the Lisp - name of an Objective-C class or metaclass. The - receiver variable name can be any bindable lisp - variable name, but {code SELF} might be a - reasonable choice. The receiver variable is declared - to be "unsettable"; i.e., it is an error to try to - change the value of the receiver in the body of the - method definition.|) - (item "{param other-args}" ccldoc::=> "either variable names (denoting parameters of - type {code :ID}) or 2-element lists whose - first element is a variable name and whose second element - is a foreign type specifier."))) - (defsection "Description" - (para "Defines an Objective-C-callable method which implements - the specified message selector for instances of the existing - named Objective-C class.") - (para "For a detailed description of the features and - restrictions of the {code OBJC:DEFMETHOD} macro, - see the - section " - (ref (section "Using objc:defmethod") "Using {code objc:defmethod}") "."))) - - (definition (:macro objc:define-objc-method) "define-objc-method (selector class-name) {code &body} body" nil - (defsection "Arguments and Values" - (listing :definition - (item "{param selector}" ccldoc::=> "either a string which represents the name of the - selector or a list which describes the method's return - type, selector components, and argument types (see below.) - If the first form is used, then the first form in the body - must be a list which describes the selector's argument - types and return value type, as per DEFCALLBACK.") - (item "{param class-name}" ccldoc::=> #:|either a string which names an existing ObjC class - name or a list symbol which can map to such a string via the - standard name-mapping conventions for class names. (Note - that the "canonical" lisp class name is such a - symbol)|))) - (defsection "Description" - (para "Defines an ObjC-callable method which implements the - specified message selector for instances of the existing ObjC - class class-name."))) - - (definition (:macro objc:define-objc-class-method) - "define-objc-class-method (selector class-name) {code &body} body" nil - (defsection "Arguments and Values" (para "As per DEFINE-OBJC-METHOD")) - (defsection "Description" - #:|Like DEFINE-OBJC-METHOD, only used to define methods on the - {emphasis class} named by class-name and on its - subclasses. - - For both DEFINE-OBJC-METHOD and DEFINE-OBJC-CLASS-METHOD, the - "selector" argument can be a list whose first element is a - foreign type specifier for the method's return value type and whose - subsequent elements are either:| - (listing :bullet - (item "a non-keyword symbol, which can be mapped to a selector string - for a parameterless method according to the standard name-mapping - conventions for method selectors.") - (item "a list of alternating keywords and variable/type specifiers, - where the set of keywords can be mapped to a selector string for a - parameterized method according to the standard name-mapping - conventions for method selectors and each variable/type-specifier is - either a variable name (denoting a value of type :ID) or a list whose - CAR is a variable name and whose CADR is the corresponding - argument's foreign type specifier.")))) - - (definition (:variable *alternate-line-terminator*) "CCL:*ALTERNATE-LINE-TERMINATOR*" nil - (defsection "Description" - #:|This variable is currently only used by the standard reader macro - function for #\\; (single-line comments); that function reads successive - characters until EOF, a #\\NewLine is read, or a character EQL to the - value of *alternate-line-terminator* is read. In {CCL} for Darwin, the - value of this variable is initially #\\Return ; in {CCL} for other OSes, - it's initially NIL. - - Their default treatment by the #\\; reader macro is the primary way - in which #\\Return and #\\Linefeed differ syntactically; by extending the - #\\; reader macro to (conditionally) treat #\\Return as a - comment-terminator, that distinction is eliminated. This seems to make - LOAD and COMPILE-FILE insensitive to line-termination issues in many - cases. It could fail in the (hopefully rare) case where a LF-terminated - (Unix) text file contains embedded #\\Return characters, and this - mechanism isn't adequate to handle cases where newlines are embedded - in string constants or other tokens (and presumably should be translated - from an external convention to the external one) : it doesn't change - what READ-CHAR or READ-LINE "see", and that may be necessary to - handle some more complicated cases.|)) - - (definition (:class ccl::ns-lisp-string) "CCL::NS-LISP-STRING" nil - (defsection "Superclasses" (para "NS:NS-STRING")) - (defsection "Initargs" - (listing :definition - (item "{param :string}" ccldoc::=> " - a Lisp string which is to be the content of - the newly-created ns-lisp-string. - "))) - (defsection "Description" - " - This class - implements the interface of an NSString, which means that it can - be passed to any Cocoa or Core Foundation function which expects - one. - - - - The string itself is stored on the Lisp heap, which - means that its memory management is automatic. However, the - ns-lisp-string object itself is a foreign - object (that is, it has an objc metaclass), and resides on the - foreign heap. Therefore, it is necessary to explicitly free - it, by sending a dealloc message. - ") - (defsection "Examples" - (para " - You can create an ns-lisp-string with - {function make-instance}, just like - any normal Lisp class: - ") - (code-block #:|? (defvar *the-string* - (make-instance 'ccl::ns-lisp-string - :string "Hello, Cocoa.")) -|) - (para " - When you are done with the string, you must explicitly - deallocate it: - ") - (code-block "? (ccl::send *the-string* 'dealloc)") - (para " - You may wish to use an {function unwind-protect} - form to ensure that this happens: - ") - (code-block #:|(let (*the-string*) - (unwind-protect (progn (setq *the-string* - (make-instance 'ccl::ns-lisp-string - :string "Hello, Cocoa.")) - (format t "~&The string is ~D characters long.~%" - (ccl::send *the-string* 'length))) - (when *the-string* - (ccl::send *the-string* 'dealloc)))) -|)) - (defsection "Notes" - (para " - Currently, ns-lisp-string is defined in - the file ccl/examples/cocoa-backtrace.lisp, which is a - rather awkward place. It was probably not originally meant - as a public utility at all. It would be good if it were - moved someplace else. Use at your own risk. - "))))) diff --git a/ccl-documentation/profile.ccldoc b/ccl-documentation/profile.ccldoc deleted file mode 100644 index da3cd7e..0000000 --- a/ccl-documentation/profile.ccldoc +++ /dev/null @@ -1,280 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Profiling" - (defsection "Using the Linux oprofile system-level profiler" - "{link http://oprofile.sourceforge.net {code oprofile}} is a - system-level profiler that's available for most modern Linux - distributions. - - Use of oprofile and its companion programs isn't really documented - here; what is described is a way of generating symbolic information that - enables profiling summaries generated by the {code opreport} program - to identify lisp functions meaningfully." - (defsection "Generating a lisp image for use with oprofile" - (para #:|Modern Linux uses the 'ELF" (Executable and Linking Format) object - file format; the oprofile tools can associate symbolic names with - addresses in a memory-mapped file if that file appears to be an ELF - object file and if it contains ELF symbol information that describes - those memory regions. So, the general idea is to make a lisp heap image - that looks enough like an ELF shared library to fool the - {code oprofile} tools (we don't actually load heap images via ELF - dynamic linking technology, but we can make it look like we did.)|)) - (defsection "Prerequisites" - (listing :bullet - (item "{code oprofile} itself, which is almost certainly - available via your distribution's package management system if not - already preinstalled.") - (item "{code libelf}, which provides utilities for reading and - writing ELF files (and is likewise likely preinstalled or readily - installable.) Somewhat confusingly, there are two libelf - implementations in widespread use on Linux, and different - distributions refer to them by different names (they may be - available as part of an 'elfutils' package.) The oprofile insterface - was designed to work with a libelf implementation whose version - number is currently around 147; the other (incompatible) libelf - implementation has a version number around 0.8. It may be necessary - to install the corresponding development package (-dev or -devel, - usuallly) in order to actually be able to use the libelf shared - library."))) - (defsection "Generating ELF symbols for Lisp functions" - (para "In order to create a lisp heap image which can be used for - {code oprofile}- based profiling, we need to:") - (listing :number - (item "load any code that we want to profile") - (item "generate a file that contains ELF symbol information - describing the names and addresses of all lisp functions. - -This step involves doing (from within {CCL})" - (code-block #:| -? (require "ELF") -"ELF" -("ELF") - -? (ccl::write-elf-symbols-to-file "home:elf-symbols") - |) - (para "The argument to CCL::WRITE-ELF-SYMBOLS-TO-FILE can be any - writable pathname. The function will do whatever's necessary to nail - lisp functions down in memory (so that they aren't moved by GC), - then write an ELF object file to the indicated pathname. This - typically takes a few seconds.")) - (item "Generate a lisp heap image in which the ELF symbols generated - in the previous step are prepended. - - The function CCL:SAVE-APPLICATION provides a :PREPEND-KERNEL - argument, which is ordinarily used to save a standalone application - in which the kernel and heap image occupy a single file. - :PREPEND-KERNEL doesn't really care what it's prepending to the - image, and we can just as easily ask it to prepend the ELF symbol - file generated in the previous step." - (code-block #:| -? (save-application "somewhere/image-for-profiling" - :prepend-kernel "home:elf-symbols") - |) - (para "If you then run") - (code-block " -shell> ccl64 somewhare/image-for-profiling - ") - (para #:|any lisp code sampled by oprofile in that image will be - identified "symbolically" by {code opreport}.|)))) - (defsection "Example" - (code-block #:| -;;; Define some lisp functions that we want to profile and save -;;; a profiling-enabled image. In this case, we just want to -;;; define the FACTORIAL funcion, to keep things simple. -? (defun fact (n) (if (zerop n) 1 (* n (fact (1- n))))) -FACT -? (require "ELF") -"ELF" -("ELF") -? (ccl::write-elf-symbols-to-file "home:elf-symbols") -"home:elf-symbols" -? (save-application "home:profiled-ccl" :prepend-kernel "home:elf-symbols") - -;;; Setup oprofile with (mostly) default arguments. This example was -;;; run on a Fedora 8 system where an uncompressed 'vmlinux' kernel -;;; image isn't readily available. - -;;; Note that use of 'opcontrol' generally requires root access, e.g., -;;; 'sudo' or equivalent: - -[~] gb@rinpoche> sudo opcontrol --no-vmlinux --setup - -;;; Start the profiler - -[~] gb@rinpoche> sudo opcontrol --start -Using 2.6+ OProfile kernel interface. -Using log file /var/lib/oprofile/samples/oprofiled.log -Daemon started. -Profiler running. - -;;; Start CCL with the "profiled-ccl" image created above. -;;; Invoke "(FACT 10000)" - -[~] gb@rinpoche> ccl64 profiled-ccl -Welcome to Clozure Common Lisp Version 1.2-r9198M-trunk (LinuxX8664)! -? (null (fact 10000)) -NIL -? (quit) - -;;; We could stop the profiler (opcontrol --stop) here; instead, -;;; we simply flush profiling data to disk, where 'opreport' can -;;; find it. -| - nil " -[~] gb@rinpoche> sudo opcontrol --dump - -;;; Ask opreport to show us where we were spending time in the -;;; 'profiled-ccl' image. - -[~] gb@rinpoche> opreport -l profiled-ccl | head -CPU: Core 2, speed 1596 MHz (estimated) -Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (Unhalted core cycles) count 100000 -samples % symbol name -6417 65.2466 -3211 32.6487 -17 0.1729 -11 0.1118 -10 0.1017 -7 0.0712 -7 0.0712 - ")) - (defsection "Issues" - #:|CCL::WRITE-ELF-SYMBOLS-TO-FILE currently only works on x86-64; it - certainly -could- be made to work on ppc32/ppc64 as well. - - So far, no one has been able to make oprofile/opreport options - that're supposed to generate call-stack info generate meaningful - call-stack info. - - As of a few months ago, there was an attempt to provide symbol - info for oprofile/opreport "on the fly", e.g., for use in JIT - compilation or other incremental compilation scenarios. That's obviously - more nearly The Right Thing, but it might be awhile before that - experimental code makes it into widespread use.|)) - (defsection "Using Apple's CHUD metering tools" - #:|Apple's CHUD package provides libraries, kernel extensions, and a - set of graphical and command-line programs that can be used to measure - many aspects of application and system performance. - - One of these programs is the Shark application (often installed in - "/Developer/Applications/Performance Tools/Shark.app"), which provides a - graphical user interface for exploring and analyzing profiling results and - provides tools for creating "sampling configurations" (see below), among - other things. Use of Shark isn't really documented here (a Shark manual is - available at "Developer/Documentation/CHUD/Shark/ SharkUserGuide.pdf"); - what is described is a way of providing information about Lisp function - names and addresses so that Shark can meaningly identify those functions - in its output.| - (defsection "Prerequisites" - (para "Apple's CHUD tools have been distributed with the last several - XCode releases. One way to determine whether or not the tools are - installed is to run:") - (code-block "$ /usr/bin/shark -v") - (para "in a terminal or Emacs shell buffer. If that returns output - like") - (code-block "shark 4.7.3 (365)") - (para "then the CHUD package is installed. Output like") - (code-block "shark: Command not found.") - (para "strongly suggests that it isn't ...")) - (defsection "Generating a lisp image for use with Shark" - #:|Shark can only properly identify functions that're defined in a - shared library that's loaded by the target application. (Any other - functions will be identified by a hex address described as being in an - "Unknown Library"; the hex address is generally somewhat near the actual - function, but it's determined heuristically and isn't always - accurate.) - - For those reasons, it's desirable to load the code that you wish - to profile in one lisp session, save a native (Mach-O library) image, - and invoke Shark in a new session which uses that native image. (It may - also be useful to load the CHUD-METERING module, which defines - CHUD:METER and friends.| - (para)) - (defsection "Usage synopsis" - (code-block #:|[src/ccl-dev] gb@antinomial> ccl64 -Welcome to Clozure Common Lisp Version 1.7-dev-r14624M-trunk (DarwinX8664)! -? (defun fact(n) (if (zerop n) 1 (* n (fact (1- n))))) -FACT -? (require "CHUD-METERING") -"CHUD-METERING" -("CHUD-METERING") -? (save-application "ccl:dx86cl64.dylib" :native t) -[src/ccl-dev] gb@antinomial> ccl64 -I dx86cl64.dylib -Welcome to Clozure Common Lisp Version 1.7-dev-r14624M-trunk (DarwinX8664)! -? (chud:meter (dotimes (i 1000) (fact 1000))) -;;; Waiting for shark to process samples ...done. -NIL|) - (para #:|and, a few seconds after the result is returned, a file whose name - is of the form "session_nnn.mshark" will open in Shark.app.|) - (para) - (para "The fist time that CHUD:METER is used in a lisp session, it'll do - a few things to prepare subsequent profiling sessions. Those things - include:") - (listing :bullet - (item - (para "creating a directory to store files that are related to using - the CHUD tools in this lisp session. This directory is created in - the user's home directory and has a name of the form:") - (code-block " -profiling-session--_-
-_.. - ")) - (item #:|run the shark program ("/usr/bin/shark") and wait until it's - ready to receive signals that control its operation.|)) - #:|This startup activity typically takes a few seconds; after it's - been completed, subsequent use of CHUD:METER doesn't involve that - overhead. (See the discussion of :RESET below.) - - After any startup activity is complete, CHUD:METER arranges to - send a "start profiling" signal to the running shark program, executes - the form, sends a "stop profiling" signal to the shark program, and - reads its diagnostic output, looking for the name of the ".mshark" file - it produces. If it's able to find this filename, it arranges for - "Shark.app" to open it.|) - (defsection "Profiling \"configurations\"" - (para "By default, a shark profiling session will:") - (listing :bullet - (item #:|use "time based" sampling, to periodically interrupt the lisp - process and note the value of the program counter and at least a few - levels of call history.|) - (item "do this sampling once every millisecond") - (item "run for up to 30 seconds, unless told to stop earlier.")) - #:|This is known as "the default configuration"; it's possible to use - items on the "Config" menu in the Shark application to create alternate - configurations which provide different kinds of profiling parameters and - to save these configurations in files for subsequent reuse. (The set of - things that CHUD knows how to monitor is large and interesting.) - - You use alternate profiling configurations (created and "exported" - via Shark.app) with CHUD:METER, but the interface is a little - awkward.|) - (defsection "Reference" - (definition (:variable chud:*shark-config-file*) "CHUD:*SHARK-CONFIG-FILE*" nil - (defsection "Description" - (para #:|When non-null, this should be the pathname of an alternate - profiling configuration file created by the "Config Editor" in - Shark.app.|))) - (definition (:macro chud:meter) "CHUD:METER form {code &key} (reset nil) (debug-output nil)" nil - (defsection "Description" - "Executes FORM (an arbitrary lisp form) and returns whatever - result(s) it returns, with CHUD profiling enabled during the form's - execution. Tries to determine the name of the session file (*.mshark) to - which the shark program wrote profiling data and opens this file in the - Shark application. - -Arguments:" - (listing :definition - (item "{param debug-output}" ccldoc::=> "when non-nil, causes output generated by the shark program - to be echoed to *TERMINAL-IO*. For debugging.") - (item "{param reset}" ccldoc::=> "when non-nil, terminates any running instance of the shark - program created by previous invocations of CHUD:METER in this lisp - session, generates a new .spatch file (describing the names and - addresses of lisp functions), and starts a new instance of the - shark program; if CHUD:*SHARK-CONFIG-FILE* is non-NIL when this - new instance is started, that instance is told to use the - specified config file for profiling (in lieu of the default - profiling configuration.)"))))) - (defsection "Acknowledgement" - (para "Both Dan Knapp and Hamilton Link have posted similar CHUD - interfaces to openmcl-devel in the past; Hamilton's also reported bugs - in the spatch mechanism to CHUD developers (and gotten those bugs - fixed.)")))) \ No newline at end of file diff --git a/ccl-documentation/q-and-a.ccldoc b/ccl-documentation/q-and-a.ccldoc deleted file mode 100644 index 4e359ee..0000000 --- a/ccl-documentation/q-and-a.ccldoc +++ /dev/null @@ -1,65 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Questions and Answers" - (defsection "How can I do nonblocking (aka \"unbuffered\" and \"raw\") IO?" - (para #:|There's some code for manipulating TTY modes in - "ccl:library;pty.lisp".|) - (code-block #:| -? (require "PTY") - -? (ccl::disable-tty-local-modes 0 #$ICANON) -T - |) - #:|will turn off "input canonicalization" on file descriptor - 0, which is at least part of what you need to do here. This - disables the #$ICANON mode, which tells the OS not to do any - line-buffering or line-editing. Of course, this only has any - effect in situations where the OS ever does that, which means - when stdin is a TTY or PTY. - -If the #$ICANON mode is disabled, you can do things like:| - (code-block " -? (progn (read-char) (read-char)) -a -#\\a - ") - (para "(where the first READ-CHAR consumes the newline, which - isn't really necessary to make the reader happy anymore.) So, - you can do:") - (code-block " -? (read-char) -#\\Space -") - (para "(where there's a space after the close-paren) without - having to type a newline.")) - (defsection "I'm using the graphics demos. Why doesn't the menubar - change?" - "When you interact with text-only {CCL}, you're either - in Terminal or in Emacs, running {CCL} as a subprocess. When - you load Cocoa or the graphical environment, the subprocess does - some tricky things that turn it into a full-fledged Application, - as far as the OS is concerned. - - So, it gets its own icon in the dock, and its own menubar, - and so on. It can be confusing, because standard input and - output will still be connected to Terminal or Emacs, so you can - still type commands to {CCL} from there. To see the menubar - you loaded, or the windows you opened, just click on the {CCL} - icon in the dock.") - (defsection "I'm using Slime and Cocoa. Why doesn't *standard-output* - seem to work? " - "This comes up if you're using the Slime interface - to run {CCL} under Emacs, and you are doing Cocoa programming - which involves printing to *standard-output*. It seems as - though the output goes nowhere; no error is reported, but it - doesn't appear in the *slime-repl* buffer. - - For the most part, this is only relevant when you are - trying to insert debug code into your event handlers. The SLIME - listener runs in a thread where the standard stream variables - (like {code *STANDARD-OUTPUT* and} and - {code *TERMINAL-IO*} are bound to the stream used to - communicate with Emacs; the Cocoa event thread has its own - bindings of these standard stream variables, and output to these - streams goes to the *inferior-lisp* buffer instead. Look for it - there.")) \ No newline at end of file diff --git a/ccl-documentation/sockets.ccldoc b/ccl-documentation/sockets.ccldoc deleted file mode 100644 index 29a9915..0000000 --- a/ccl-documentation/sockets.ccldoc +++ /dev/null @@ -1,450 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Programming with Sockets" - (defsection "Overview" - (para "{CCL} supports the socket abstraction for - interprocess communication. A socket represents a connection to - another process, typically (but not necessarily) a TCP/IP - network connection to a client or server running on some other - machine on the network.") - (para "IPv6 is supported by the :internet6 address family. - Applications should use the " - (ref (definition :function ccl::resolve-address)) " - function to translate host and port specifications to socket - addresses. While host and port numbers can still be dealt with - separately, it is preferable to use " - (ref (definition :class ccl::socket-address)) " instances to specify socket - endpoints for unified parsing of string representations and - printing.") - (para "All symbols mentioned in this chapter are exported from - the CCL package. As of version 0.13, these symbols are - additionally exported from the OPENMCL-SOCKET package.") - (para "{CCL} supports three types of sockets: TCP sockets, UDP - sockets, and Unix-domain sockets. This should be enough for all - but the most esoteric network situations. All sockets are - created by " - (ref (definition :function make-socket)) ". The type of socket - depends on the arguments to it, as follows:") - (listing :definition - (item "tcp-stream" ccldoc::=> "A buffered bi-directional stream over a TCP/IP connection. - tcp-stream is a subclass of stream, and you can read and write to it - using all the usual stream functions. Created by (make-socket - :address-family :internet :type :stream :connect :active ...) or by - (accept-connection ...).") - (item "file-socket-stream" ccldoc::=> #:|A buffered bi-directional stream over a "UNIX domain" - connection. file-socket-stream is a subclass of stream, and you can - read and write to it using all the usual stream functions. Created - by (make-socket :address-family :file :type :stream :connect :active - ...) or by (accept-connection ...),|) - (item "listener-socket" ccldoc::=> "A passive socket used to listen for incoming TCP/IP - connections on a particular port. A listener-socket is not a stream. - It doesn't support I/O. It can only be used to create new - tcp-streams by accept-connection. Created by (make-socket :type - :stream :connect :passive ...)") - (item "file-listener-socket" ccldoc::=> "A passive socket used to listen for incoming UNIX domain - connections named by a file in the local filesystem. A - listener-socket is not a stream. It doesn't support I/O. It can - only be used to create new file-socket-streams by accept-connection. - Created by (make-socket :address-family :file :type :stream :connect - :passive ...)") - (item "udp-socket" ccldoc::=> "A socket representing a packet-based UDP/IP connection. A - udp-socket supports I/O but it is not a stream. Instead, you must - use the special functions send-to and receive-from to read and write - to it. Created by (make-socket :type :datagram ...)"))) - (defsection "Sockets Dictionary" - (definition (:function make-socket) - "make-socket {code &key} address-family type connect eol format remote-address remote-host remote-port local-address local-host local-port local-filename remote-filename keepalive reuse-address nodelay broadcast linger backlog input-timeout output-timeout connect-timeout auto-close deadline" - "Make a socket." - (defsection "Arguments and Values" - (listing :definition - (item "{param address-family}" ccldoc::=> "The address/protocol family of this - socket. Currently, :internet (the default), meaning - IPv4, :internet6, meaning IPv6, and :file, referring - to UNIX domain addresses, are supported.") - (item "{param type}" ccldoc::=> "One of :stream (the default) to request a - connection-oriented socket, or :datagram to request a - connectionless socket. The default is :stream.") - (item "{param connect}" ccldoc::=> "This argument is only relevant to sockets of type - :stream. One of :active (the default) to request a :passive - to request a file or TCP listener socket.") - (item "{param eol}" ccldoc::=> "This argument is currently ignored (it is accepted for - compatibility with Franz Allegro).") - (item "{param format}" ccldoc::=> "One of :text (the default), :binary, or :bivalent. - This argument is ignored for :stream sockets for now, as - :stream sockets are currently always bivalent (i.e. they - support both character and byte I/O). For :datagram sockets, - this argument is ignored (the format of a datagram socket - is always :binary). - ") - (item "{param remote}" ccldoc::=> "For TCP streams, it specifies the socket address - to connect to, specified as socket-address instance. - Ignored for listener sockets. For UDP sockets, it can - be used to specify a default address for subsequent calls - to send-to or receive-from.") - (item "{param remote-host}" ccldoc::=> "For TCP streams, it specifies the host to - connect to (in any format acceptable to resolve-address). - Ignored for listener sockets. For UDP sockets, it can be - used to specify a default host for subsequent calls to - send-to or receive-from.") - (item "{param remote-port}" ccldoc::=> "For TCP streams, it specifies the port to - connect to (in any format acceptable to resolve-address). - Ignored for listener sockets. For UDP sockets, it can be - used to specify a default port for subsequent calls to for - subsequent calls to send-to or receive-from.") - (item "{param remote-filename}" ccldoc::=> "For file-socket streams, it specifies the - name of a file in the local filesystem (e.g., NOT mounted - via NFS, AFP, SMB, ...) which names and controls access to a - UNIX-domain socket.") - (item "{param local-address}" ccldoc::=> "Allows you to specify a local address for a - listener or UDP socket, for the case where you want to - restrict connections to those coming to a specific local - address for security reasons.") - (item "{param local-host}" ccldoc::=> "Allows you to specify a local host address for a - listener or UDP socket, for the case where you want to - restrict connections to those coming to a specific local - address for security reasons.") - (item "{param local-port}" ccldoc::=> "Specify a local port for a socket. Most useful for - listener sockets, where it is the port on which the socket - will listen for connections.") - (item "{param local-filename}" ccldoc::=> "For file-listener-sockets, specifies the name - of a file in the local filesystem which is used to name a - UNIX-domain socket. The actual filesystem file should not - previously exist when the file-listener-socket is created; - its parent directory should exist and be writable by the - caller. The file used to name the socket will be deleted - when the file-listener-socket is closed.") - (item "{param keepalive}" ccldoc::=> #:|If true, enables the periodic transmission of - "keepalive" messages.|) - (item "{param reuse-address}" ccldoc::=> "If true, allows the reuse of local ports in listener - sockets, overriding some TCP/IP protocol specifications. You - will need this if you are debugging a server..") - (item "{param nodelay}" ccldoc::=> "If true, disables Nagle's algorithm, which tries - to minimize TCP packet fragmentation by introducing - transmission delays in the absence of replies. Try setting - this if you are using a protocol which involves sending a - steady stream of data with no replies and are seeing - significant degradations in throughput.") - (item "{param broadcast}" ccldoc::=> "If true, requests permission to broadcast datagrams on - a UDP socket.") - (item "{param linger}" ccldoc::=> "If specified and non-nil, should be the number of - seconds the OS is allowed to wait for data to be pushed - through when a close is done. Only relevant for TCP sockets.") - (item "{param backlog}" ccldoc::=> "For a listener socket, specifies the number of - connections which can be pending but not accepted. The - default is 5, which is also the maximum on some operating - systems.") - (item "{param input-timeout}" ccldoc::=> "The number of seconds before an input operation - times out. Must be a real number between zero and one - million. If an input operation takes longer than the - specified number of seconds, an - {code input-timeout} error is signalled. - (see {section Stream Timeouts and Deadlines})") - (item "{param output-timeout}" ccldoc::=> "The number of seconds before an output operation - times out. Must be a real number between zero and one - million. If an output operation takes longer than the - specified number of seconds, an - {code output-timeout} error is signalled. - (see {section Stream Timeouts and Deadlines})") - (item "{param connect-timeout}" ccldoc::=> "The number of seconds before a connection - attempt times out. [TODO: what are acceptable values?] - If a connection attempt takes longer than the - specified number of seconds, a - {code socket-error} is signalled. This - can be useful if the specified interval is shorter - than the interval that the OS's socket layer imposes, - which is sometimes a minute or two.") - (item "{param auto-close}" ccldoc::=> "When non-nil, any resulting socket stream will - be closed when the GC can prove that the stream is - unreferenced. This is done via CCL's termination - mechanism [TODO add xref].") - (item "{param deadline}" ccldoc::=> "Specifies an absolute time in - internal-time-units. If an I/O operation on the - stream does not complete before the deadline then a - {code COMMUNICATION-DEADLINE-EXPIRED} - error is signalled. A deadline takes precedence over - any input/output timeouts that may be set. (see {section Stream Timeouts and Deadlines})"))) - (defsection "Description" - (para "Creates and returns a new socket. For :passive - sockets, the :local-address, :local-port or :local-filename - arguments are required, depending on the type of the socket. - For :active sockets, either the :remote-address, the - :remote-host and :remote-port, or the :remote-filename - arguments must be present, depending on the socket - type."))) - - (definition (:function accept-connection) "accept-connection (socket listener-socket) code &key (wait t)" nil - (para "Extracts the first connection on the queue of pending - connections for {param socket}, accepts it (i.e. completes - the connection startup protocol), and returns a new - tcp-stream or file-socket-stream representing the newly - established connection. The tcp stream inherits any - properties of the listener socket that are relevant - (e.g. {code :keepalive}, {code :nodelay}, and so forth.) The - original listener socket continues to be open listening for - more connections, so you can call accept-connection on it - again.") - - (para "If {code :wait} is {code t}, and there are no connections - waiting to be accepted, the function wait until one - arrives. Otherwise, {function accept-connection} will - return {code nil} immediately.")) - - (definition (:function ccl::resolve-address) - "resolve-address {code &key} host port socket-type connect address-family numeric-host-p numeric-service-p singlep errorp" - nil - (para "Converts a host and/or port specification to one or more " - (ref (definition :class ccl::socket-address)) " instances. - This function uses the getaddrinfo() system function - underneath which knows how to translate all standard address - and port formats and appropriately orders adresses for hosts - with multiple addresses. It returns the best matching - translation or, if the {code :singlep} is false, all - matching translations for the given parameter - combination.") - (defsection "Arguments and Values" - (listing :definition - (item "{param host}" ccldoc::=> "Specification of the host, as a string. This - can be either a host name such as - “clozure.com” or any of the literal address - forms accepted by getaddrinfo().") - (item "{param port}" ccldoc::=> "Specification of the port. This - can be either a service name such as - “http” or a port number.") - (item "{param socket-type}" ccldoc::=> "Service type for port lookups, can be either - :stream for TCP services or :datagram for UDP. - Defaults to :stream.") - (item "{param connect}" ccldoc::=> "Specifies how the returned " (ref (definition :class ccl::socket-address)) - " instances will be used. - If :active is passed, which is the default, the host - address will default to the address of the loopback - interface of the local host if not specified. When - :passive is used, the host address will default to the - wildcard address for the given address family. This - parameter has no effect if the :host parameter is - used.") - (item "{param address-family}" ccldoc::=> "Specifies the address family that should be - returned, can be specified as either :internet or - :internet6. If it is specified, only addresses of - that family are returned.") - (item "{param numeric-host-p}" ccldoc::=> "If this argument is true, no host name lookups - will be performed for the host address. A numeric - address literal must be passed in this case.") - (item "{param numeric-port-p}" ccldoc::=> "If this argument is true, no service name - lookups will be performed for the port address. A - numeric port number must be passed in this - case.") - (item "{param singlep}" ccldoc::=> "If this argument is set to a true value, which - is the default, only the first matching address is - returned. If it is passed as NIL, all matching - addresses are returned as a list.") - (item "{param errorp}" ccldoc::=> "If this argument is set to a true value, which - is the default, an error is signalled if the given - host and/or port combination did not yield any - matches. If it is passed as NIL, the function returns - NIL if no addresses matched the supplied - arguments.")))) - - (definition (:function dotted-to-ipaddr) "dotted-to-ipaddr dotted &key (errorp t)" nil - "Converts {param dotted}, which should be a dotted quad string such -as “192.168.0.1”, into a integer representation. If {code :errorp} is true, -an error is signaled if {param dotted} is invalid. Otherwise, {code nil} is -returned.") - - (definition (:function ipaddr-to-dotted) "ipaddr-to-dotted ipaddr &key values" nil - "This function converts {param ipaddr}, an integer representing -an IPv4 host, into a dotted quad string. If {code :values} is true, -instead of a dotted quad string, it returns the four octets of the -address as multiple values.") - - (definition (:function ipaddr-to-hostname) "ipaddr-to-hostname ipaddr {code &key} ignore-cache" nil - (para "Converts {param ipaddr}, a 32-bit unsigend integer, into -a host name string. The keyword argument {code :ignore-cache} is -ignored (it is accepted for compatibility with Franz Allegro CL).")) - - (definition (:function lookup-hostname) "lookup-hostname host-spec" nil - (para "Converts {param host-spec} into a 32-bit unsigned IPv4 - address. IPv6-enabled applications should use the " - (ref (definition :function ccl::resolve-address)) " function instead.") - (para "Acceptable formats for {param host-spec} include a host name -string such as “www.clozure.com”, a dotted address string such as “192.168.0.1”, -or a 32-bit unsigned IPv4 address such as 3232235521.")) - - (definition (:function lookup-port) "lookup-port port protocol" nil - "Finds the numeric port number for the specified {param port} and -{param protocol}." - - "{param port} can be a string such as “http”, a symbol such as -{code :http}, or a port number. Note that strings are case-sensitive. -Symbol names are converted to lower-case before lookup. Protocol must -be one of “tcp” or “udp”.") - - (definition (:function receive-from) "receive-from (socket udp-socket) size code &key buffer extract offset want-socket-address-p" nil - "Reads a UDP packet from {param socket}. If no packets are -available, waits for a packet to arrive. - -If :want-socket-address-p is {code nil}, which is the -default, four values are returned:" - (listing :number - (item "The buffer with the data") - (item "The number of bytes read") - (item "The 32-bit unsigned IPv4 address or the 16 byte - IPv6 addresss of the sender of the data") - (item "The port number of the sender of the data")) - - (para "If :want-socket-address-p is true, three values are - returned:") - (listing :number - (item "The buffer with the data") - (item "The number of bytes read") - (item "The " (ref (definition :class ccl::socket-address)) " instance of - the sender of the data.")) - - (defsection "Arguments and Values" - (listing :definition - (item "{param socket}" ccldoc::=> "The socket to read from") - (item "{param size}" ccldoc::=> "Maximum number of bytes to read. If the packet is - larger than this, any extra bytes are discarded.") - (item "{param buffer}" ccldoc::=> "If specified, must be an octet vector - which will be used to read in the data. If not specified, a - new buffer will be created (of type determined by - socket-format).") - (item "{param extract}" ccldoc::=> "If true, the subsequence of the buffer corresponding - only to the data read in is extracted and returned as the - first value. If false (the default) the original buffer is - returned even if it is only partially filled.") - (item "{param offset}" ccldoc::=> "Specifies the start offset into the buffer at which - data is to be stored. The default is 0.") - (item "{param want-socket-address-p}" ccldoc::=> "Indicates that the address of the sender of the - data should be returned as a " - (ref (definition :class ccl::socket-address)) " instance rather than as - separate host and port values.")))) - - (definition (:function send-to) - "send-to (socket udp-socket) buffer size code &key remote remote-host remote-port offset" nil - "This function sends a UDP packet over {param socket}." - (defsection "Arguments and Values" - (listing :definition - (item "{param socket}" ccldoc::=> "The socket to write to") - (item "{param buffer}" ccldoc::=> "A vector containing the data to send. It must be - an octet vector.") - (item "{param size}" ccldoc::=> "Number of octets to send") - (item "{param remote}" ccldoc::=> "The remote address to send the packet to, as a - " - (ref (definition :class ccl::socket-address)) " instance. The - default is the remote address specified in the call to - make-socket.") - (item "{param remote-host}" ccldoc::=> "The host to send the packet to, in any format - acceptable to lookup-hostname. The default is the remote - host specified in the call to make-socket.") - (item "{param remote-port}" ccldoc::=> "The port to send the packet to, in any format - acceptable to lookup-port. The default is the remote port - specified in the call to make-socket.") - (item "{param offset}" ccldoc::=> "The offset in the buffer where the packet data starts")))) - - (definition (:function shutdown) "shutdown socket &key direction" nil - "Shuts down part of a bidirectional connection represented by - {param socket}. Typcially {param socket} will be a tcp-stream. - One situation where this can be useful is when you need to - read responses after sending an end-of-file signal. The - keyword argument {code :direction} may be either - {code :input} (to disallow further input) or - {code :output} (to disallow further output).") - - (definition (:function socket-os-fd) "socket-os-fd socket" nil - (para "Returns the native OS's representation of {param - socket}, or {code nil} if the socket is closed. On Unix, - this will be a file descriptor. Note that it is rather - dangerous to mess around with tcp-stream file descriptors, - as there is all sorts of buffering and asynchronous I/O - going on above the OS level. listener-socket and udp-socket - file descriptors are safer to mess with directly as there is - less magic going on.")) - - (definition (:function remote-host) "remote-host socket" nil - (para "Returns the 32-bit unsigned IPv4 address of the remote host, - or {code nil} if {param socket} is not connected.")) - - (definition (:function remote-port) "remote-port socket" nil - (para "Returns the remote port number of {param socket}, or NIL if -{param socket} is not connected.")) - - (definition (:function local-host) "local-host socket" nil - (para "Returns 32-bit unsigned IPv4 address or the 16 byte - IPv6 address of the local host for {param socket}.")) - - (definition (:function local-port) "local-port socket" nil - "This function returns the local port number of {param socket}.") - - (definition (:function socket-address-family) "socket-address-family thing" nil - "Returns :internet, :internet6 or :file, as appropriate for -{param thing}, which should be a socket or socket-address.") - - (definition (:function ccl::socket-address-host) "socket-address-host socket-address" nil - "Returns the host portion of the given {param socket-address}. - For :internet addresses, this is a 32-bit integer. For - :internet6 addresses, a vector of 16 bytes returned. For - :file addresses, it is the file name string.") - - (definition (:function ccl::socket-address-port) "socket-address-port socket-address" nil - "This function returns the port number of the given {param - socket-address}. This function is available only for - {code :internet} and {code :internet6} socket addresses.") - - (definition (:function socket-connect) "socket-connect socket" nil - "This function examines {param socket} and returns -{code :active} for a tcp-stream, {code :passive} for listener-socket, -and {code nil} for a udp-socket.") - - (definition (:function socket-format) "socket-format socket" nil - "Returns the format of {param socket} as specified by - the :format argument to make-socket.") - - (definition (:function socket-type) "socket-type socket" nil - (para "This function returns :stream if {param socket} is a - tcp-stream or listener-socket. If the socket is a udp-socket, -{function socket-type} will return :datagram.")) - - (definition (:class ccl::socket-address) "socket-address" nil - (para "This class is a representation of a socket endpoint address. - Instances of this class are used to encapsulate the host and - port of an IP socket endpoint or the filename of a file - socket. They can be created by applications from a possibly - symbolic address representation by the " - (ref (definition :function ccl::resolve-address)) " function.")) - - (definition (:class socket-error) "socket-error" nil - "The class of OS errors signaled by socket functions (a subclass -of {code simple-error}.") - - (definition (:function socket-error-code) "socket-error-code socket-error" - nil - "Returns the OS error code contained in {param socket-error}.") - - (definition (:function socket-error-identifier) "socket-error-identifier socket-error" nil - "Returns a symbol representing the socket error code contained - in {param socket-error}. It will be one of - {code :address-in-use}, {code :connection-aborted}, - {code :no-buffer-space}, {code :connection-timed-out}, - {code :connection-refused}, {code :host-unreachable}, - {code :host-down}, {code :network-down}, - {code :address-not-available}, {code :network-reset}, - {code :connection-reset}, {code :shutdown}, - {code :access-denied}, or {code :unknown}.") - - (definition (:function socket-error-situation) "socket-error-situation socket-error" nil - "Returns a string describing the context where the error {param -socket-error} happened. On Linux, this is the name of the system call -which returned the error.") - - (definition (:method close) "close (socket socket) code &key abort" nil - "Close {param socket}, releasing the operating system resources -associated with it. Normally, any pending buffered I/O will be -finished up before closing, but if {code :abort} is {code t}, any -pending I/O will be aborted. Note that for listener and udp sockets, -there is never any buffered I/O to clean up, so the value of -{code :abort} is effectively ignored.") - - (definition (:macro with-open-socket) "with-open-socket (var . make-socket-args) &body body" nil - "Executes {param body} with {param var} bound to the result of - applying {function make-socket} to {param - make-socket-args}. The socket gets closed on exit."))) diff --git a/ccl-documentation/streams.ccldoc b/ccl-documentation/streams.ccldoc deleted file mode 100644 index 2ff26aa..0000000 --- a/ccl-documentation/streams.ccldoc +++ /dev/null @@ -1,540 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Streams" - (defsection "Stream Extensions" - (defsection "Stream External Format" - "{function stream-external-format} can be applied to - (and may return a non-null result for) open streams that are not - {code FILE-STREAM}s. - - {function (setf stream-external-format)} can be used to - change the external format of open streams created with {function open} or {function make-socket}. - ") - - (defsection "Additional keywords for OPEN and MAKE-SOCKET" - (para "{function open} and - {function make-socket} have each been extended to take - the additional keyword arguments: {code :CLASS}, - {code :SHARING}, and - {code :BASIC}.") - (listing :definition - (item "{code :CLASS}" ccldoc::=> "A symbol that names the desired class of the stream. - The specified class must inherit from - {code FILE-STREAM} for - {function open}.") - (item "{code :SHARING}" ccldoc::=> - (para "Specifies how a stream can be used by multiple - threads. The possible values are: - {code :PRIVATE}, {code :LOCK} and - {code :EXTERNAL}. {code :PRIVATE} is - the default. {code NIL} is also accepted as a - synonym for {code :EXTERNAL}.") - (listing :definition - (item "{code :PRIVATE}" ccldoc::=> #:|Specifies that the stream can only be accessed - by the thread that first tries to do I/O to it; that - thread becomes the "owner" of the stream and - is not necessarily the same thread as the one which - created the stream. This is the default. - (There was some discussion on openmcl-devel about the - idea of "transferring ownership" of a stream; this has - not yet been implemented.) Attempts to do I/O on a - stream with :PRIVATE sharing from a thread other than - the stream's owner yield an error.|) - (item "{code :LOCK}" ccldoc::=> #:|Specifies that all access to the stream require - the calling thread to obtain a lock. There are - separate "read" and "write" locks for IO streams. - This makes it possible for instance, for one thread to - read from such a stream while another thread writes to - it. (see also | - (ref (definition :function make-read-write-lock)) (ref (definition :macro with-read-lock)) - (ref (definition :macro with-write-lock)) ")") - (item "{code :EXTERNAL}" ccldoc::=> "Specifies that I/O primitives enforce no access - protocol. This may be appropriate for some types of - application which can control stream access via - application-level protocols. Note that since even the - act of reading from a stream changes its internal - state (and simultaneous access from multiple threads - can therefore lead to corruption of that state), some - care must be taken in the design of such protocols."))) - (item "{code :BASIC}" ccldoc::=> "A boolean that indicates whether or not the stream is - a Gray stream, i.e. whether or not the stream is an instance - of {code FUNDAMENTAL-STREAM} or - {code CCL::BASIC-STREAM}(see {section Basic Versus Fundamental Streams}). Defaults to - {code T}."))) - - (defsection "Basic Versus Fundamental Streams" - #:|Gray streams (see {section Creating Your Own Stream Classes with Gray Streams}) - all inherit from {code FUNDAMENTAL-STREAM} whereas - basic streams inherit from {code CCL::BASIC-STREAM}. - The tradeoff between FUNDAMENTAL and BASIC streams is entirely - between flexibility and performance, potential or actual. I/O - primitives can recognize BASIC-STREAMs and exploit knowledge of - implementation details. FUNDAMENTAL stream classes can be - subclassed and extended in a standard way (the Gray streams - protocol). - - For existing stream classes (FILE-STREAMs, SOCKETs, and - the internal CCL::FD-STREAM classes used to implement file - streams and sockets), a lot of code can be shared between the - FUNDAMENTAL and BASIC implementations. The biggest difference - should be that that code can be reached from I/O primitives like - READ-CHAR without going through some steps that're there to - support generality and extensibility, and skipping those steps - when that support isn't needed can improve I/O performance. - - - The Gray stream method - {function stream-read-char} should work on appropriate - {code BASIC-STREAM}s. (There may still be cases - where such methods are undefined; such cases should be - considered bugs.) It is not guaranteed that Gray stream methods - would ever be called by I/O primitives to read a character from - a {code BASIC-STREAM}, though there are still cases - where this happens. - - A simple loop reading 2M characters from a text file runs - about 10X faster when the file is opened the new defaults - {code (:SHARING :PRIVATE :BASIC T)} than it had - before these changes were made. That sounds good, until one - realizes that the "equivalent" C loop can be about 10X faster - still ...|) - - (defsection "Stream Timeouts and Deadlines" - (para "A stream that is associated with a file descriptor has - attributes and accessors: - {function stream-input-timeout}, - {function stream-output-timeout}, and - {function stream-deadline}. All three accessors have - corresponding {function setf} methods. - {function stream-input-timeout} and - {function stream-output-timeout} are specified in - seconds and can be any positive real number less than one million. - When a timeout is set and the corresponding I/O operation takes - longer than the specified interval, an error is signalled. The - error is {code INPUT-TIMEOUT} for input and - {code OUTPUT-TIMEOUT} for output. - {code STREAM-DEADLINE} specifies an absolute time in - internal-time-units. If an I/O operation on the stream does not - complete before the deadline then a - {code COMMUNICATION-DEADLINE-EXPIRED} error is - signalled. A deadline takes precedence over any - input/output timeouts that may be set.")) - - (defsection "Open File Streams" - (para "{CCL} maintains a list of open file streams. This helps - to ensure that streams get closed in an orderly manner when - the lisp exits. The following thread-safe functions manage - this list.") - - (definition (:function open-file-streams) "open-file-streams" nil - "Returns a fresh list of file streams that are currently open.") - - (definition (:function note-open-file-stream) - "note-open-file-stream file-stream" nil - "Adds {param file-stream} to the internal list of open file - streams that is returned by {function open-file-streams}. - This function is thread-safe. It will usually only be called - from custom stream code when a file-stream is created.") - - (definition (:function remove-open-file-stream) - "remove-open-file-stream file-stream" nil - "Removes {param file-stream} from the internal list of open file - streams that is returned by {function open-file-streams}. - This function is thread-safe. It will usually only be called - from custom stream code when a file-stream is closed.")) - - (defsection "Creating Your Own Stream Classes with Gray Streams" - (defsection "Overview" - "This sect1 is still being written and revised, because - it is woefully incomplete. The dictionary section currently - only lists a couple functions. Caveat lector. - - Gray streams are an extension to Common Lisp. They were - proposed for standardization by David Gray (the astute reader - now understands their name) quite some years ago, but not - accepted, because they had not been tried sufficiently to find - conceptual problems with them. - - They have since been implemented by quite a few modern - Lisp implementations. However, they do indeed have some - inadequacies, and each implementation has addressed these in - different ways. The situation today is that it's difficult to - even find out how to get started using Gray streams. This is - why standards are important. - - Here's a list of some classes which you might wish for - your new stream class to inherit from:" - (listing :column - (item "fundamental-stream") - (item "fundamental-input-stream") - (item "fundamental-output-stream") - (item "fundamental-character-stream") - (item "fundamental-binary-stream") - (item "fundamental-character-input-stream") - (item "fundamental-character-output-stream") - (item "fundamental-binary-input-stream") - (item "fundamental-binary-output-stream") - (item "ccl::buffered-stream-mixin") - (item "ccl::buffered-input-stream-mixin") - (item "ccl::buffered-output-stream-mixin") - (item "ccl::buffered-io-stream-mixin") - (item "ccl::buffered-character-input-stream-mixin") - (item "ccl::buffered-character-output-stream-mixin") - (item "ccl::buffered-character-io-stream-mixin") - (item "ccl::buffered-binary-input-stream-mixin") - (item "ccl::buffered-binary-output-stream-mixin") - (item "ccl::buffered-binary-io-stream-mixin") - (item "file-stream") - (item "file-input-stream") - (item "file-output-stream") - (item "file-io-stream") - (item "file-character-input-stream") - (item "file-character-output-stream") - (item "file-character-io-stream") - (item "file-binary-input-stream") - (item "file-binary-output-stream") - (item "file-binary-io-stream") - (item "ccl::fd-stream") - (item "ccl::fd-input-stream") - (item "ccl::fd-output-stream") - (item "ccl::fd-io-stream") - (item "ccl::fd-character-input-stream") - (item "ccl::fd-character-output-stream") - (item "ccl::fd-character-io-stream") - (item "ccl::fd-binary-input-stream") - (item "ccl::fd-binary-output-stream") - (item "ccl::fd-binary-io-stream")) - #:|All of these are defined in ccl/level-1/l1-streams.lisp, - except for the ccl:file-* ones, which are in - ccl/level-1/l1-sysio.lisp. - - According to the original Gray streams proposal, you - should inherit from the most specific of the fundamental-* - classes which applies. Using {CCL}, though, if you want - buffering for better performance, which, unless you know of some - reason you wouldn't, you do, you should instead inherit from the - appropriate ccl::buffered-* class The buffering you get this way - is exactly the same as the buffering which is used on ordinary, - non-Gray streams, and force-output will work properly on - it. - - Notice that -mixin suffix in the names of all the - ccl::buffered-* classes? The suffix means that this class is - not "complete" by itself; you still need to inherit from a - fundamental-* stream, even if you also inherit from a *-mixin - stream. You might consider making your own class like this. - .... Except that they do inherit from the fundamental-* - streams, that's weird. - - If you want to be able to create an instance of your class - with the :class argument to (open) and (with-open-file), you - should make it inherit from one of the file-* classes. If you - do this, it's not necessary to inherit from any of the other - classes (though it won't hurt anything), since the file-* - classes already do. - - When you inherit from the file-* classes, you can use - (call-next-method) in any of your methods to get the standard - behavior. This is especially useful if you want to create a - class which performs some simple filtering operation, such as - changing everything to uppercase or to a different character - encoding. If you do this, you will definitely need to - specialize ccl::select-stream-class. Your method on - ccl::stream-select-class should accept an instance of the class, - but pay no attention to its contents, and return a symbol naming - the class to actually be instantiated. - - If you need to make your functionality generic across all - the different types of stream, probably the best way to - implement it is to make it a mixin, define classes with all the - variants of input, output, io, character, and binary, which - inherit both from your mixin and from the appropriate other - class, then define a method on ccl::select-stream-class which - chooses from among those classes. - - Note that some of these classes are internal to the CCL - package. If you try to inherit from those ones without the - ccl:: prefix, you'll get an error which may confuse you, calling - them "forward-referenced classes". That just means you used the - wrong symbol, so add the prefix. - - Here's a list of some generic functions which you might - wish to specialize for your new stream class, and which ought to - be documented at some point.| - (listing :column - (item "stream-direction stream =>") - (item "stream-device stream direction =>") - (item "stream-length stream {code &optional} new =>") - (item "stream-position stream {code &optional} new =>") - (item "streamp stream => boolean") - (item "stream-write-char output-stream char =>") - (item "stream-write-entire-string output-stream string =>") - (item "stream-read-char input-stream =>") - (item "stream-unread-char input-stream char =>") - (item "stream-force-output output-stream => nil") - (item "stream-maybe-force-output output-stream => nil") - (item "stream-finish-output output-stream => nil") - (item "stream-clear-output output-stream => nil") - (item "close stream {code &key} abort => boolean") - (item "stream-fresh-line stream => t") - (item "stream-line-length stream => length") - (item "interactive-stream-p stream => boolean") - (item "stream-clear-input input-stream => nil") - (item "stream-listen input-stream => boolean") - (item "stream-filename stream => string") - (item "ccl::select-stream-class instance in-p out-p char-p => - class")) - (para "The following functions are standard parts of Common Lisp, but - behave in special ways with regard to Gray streams.") - (listing :column - (item "open-stream-p stream => generalized-boolean") - (item "input-stream-p stream => generalized-boolean") - (item "output-stream-p stream => generalized-boolean") - (item "stream-element-type stream =>") - (item "stream-error-stream =>") - (item "open") - (item "close") - (item "with-open-file")) - "Specifically, (open) and (with-open-file) accept a new - keyword argument, :class, which may be a symbol naming a class; - the class itself; or an instance of it. The class so given must - be a subtype of 'stream, and an instance of it with no - particular contents will be passed to ccl::select-stream-class - to determine what class to actually instantiate. - - The following are standard, and do not behave specially - with regard to Gray streams, but probably should." - (listing :column (item "stream-external-format"))) - (defsection "Extending READ-SEQUENCE and WRITE-SEQUENCE" - (defsection "Overview" - #:|The "Gray Streams" API is based on an informal proposal that was - made before ANSI CL adopted the READ-SEQUENCE and WRITE-SEQUENCE - functions; as such, there is no "standard" way for the author of a Gray - stream class to improve the performance of these functions by exploiting - knowledge of the stream's internals (e.g., the buffering mechanism it - uses.) - - In the absence of any such knowledge, READ-SEQUENCE and - WRITE-SEQUENCE are effectively just convenient shorthand for a - loop which calls READ-CHAR/READ-BYTE/WRITE-CHAR/WRITE-BYTE as - appropriate. The mechanism described below allows subclasses - of FUNDAMENTAL-STREAM to define more specialized (and - presumably more efficient) behavior.|) - (defsection "Notes" - (para "READ-SEQUENCE and WRITE-SEQUENCE do a certain amount of - sanity-checking and normalization of their arguments before - dispatching to one of the methods above. If an individual - method can't do anything particularly clever, CALL-NEXT-METHOD - can be used to handle the general case.")) - (defsection "Example" - (code-block " -(defclass my-string-input-stream (fundamental-character-input-stream) - ((string :initarg :string :accessor my-string-input-stream-string) - (index :initform 0 :accessor my-string-input-stream-index) - (length))) - -(defmethod stream-read-vector ((stream my-string-input-stream) vector start end) - (if (not (typep vector 'simple-base-string)) - (call-next-method) - (with-slots (string index length) - (do* ((outpos start (1+ outpos))) - ((or (= outpos end) - (= index length)) - outpos)) - (setf (schar vector outpos) - (schar string index)) - (incf index))))) - "))) - (defsection "Multibyte I/O" - #:|All heap-allocated objects in {CCL} that cannot contain - pointers to lisp objects are represented as - {emphasis ivectors}. {CCL} provides low-level - functions, and , to efficiently transfer data between buffered - streams and ivectors. There's some overlap in functionality - between the functions described here and the ANSI CL - READ-SEQUENCE and WRITE-SEQUENCE functions. - - As used here, the term "octet" means roughly the same - thing as the term "8-bit byte". The functions described below - transfer a specified sequence of octets between a buffered - stream and an ivector, and don't really concern themselves with - higher-level issues (like whether that octet sequence is within - bounds or how it relates to the logical contents of the - ivector.) For these reasons, these functions are generally less - safe and more flexible than their ANSI counterparts.|) - (defsection "Gray Streams Dictionary" - - (definition (:generic-function stream-read-list) "stream-read-list stream list count" nil - (para "Should try to read up to count elements from stream - into the list {param list}, returning the number of elements - actually read (which may be less than count in case of - a premature end-of-file.)") - (defsection "Arguments and Values" - (listing :definition - (item "{param stream}" ccldoc::=> "a stream, presumably a fundamental-input-stream.") - (item "{param list}" ccldoc::=> "a list. When a STREAM-READ-LIST method is called by - READ-SEQUENCE, this argument is guaranteed to be a proper - list.") - (item "{param count}" ccldoc::=> "a non-negative integer. When a STREAM-READ-LIST method - is called by READ-SEQUENCE, this argument is guaranteed not - to be greater than the length of the list.")))) - - (definition (:generic-function stream-write-list) "stream-write-list stream list count" nil - (para "Write the first {param count} elements of {param list} to - {param stream}. The return value of this method is ignored.") - (defsection "Arguments and Values" - (listing :definition - (item "{param stream}" ccldoc::=> "a stream, presumably a fundamental-output-stream.") - (item "{param list}" ccldoc::=> "a list. When a STREAM-WRITE-LIST method is called by - WRITE-SEQUENCE, this argument is guaranteed to be a proper - list.") - (item "{param count}" ccldoc::=> "a non-negative integer. When a STREAM-WRITE-LIST - method is called by WRITE-SEQUENCE, this argument is - guaranteed not to be greater than the length of the list.")))) - - (definition (:generic-function stream-read-vector) "stream-read-vector stream vector start end" nil - (para "Read successive elements from stream into {param - vector}, starting at element {param start} (inclusive) - and continuing through element {param - end} (exclusive.) Should return the index of the - vector element beyond the last one stored into, which - may be less than {param end} in case of premature - end-of-file.") - (defsection "Arguments and Values" - (listing :definition - (item "{param stream}" ccldoc::=> "a stream, presumably a fundamental-input-stream") - (item "{param vector}" ccldoc::=> "a vector. When a STREAM-READ-VECTOR method is called - by {code read-sequence}, this argument is guaranteed to be a simple - one-dimensional array.") - (item "{param start}" ccldoc::=> "a non-negative integer. When a STREAM-READ-VECTOR - method is called by READ-SEQUENCE, this argument is - guaranteed to be no greater than end and not greater than - the length of vector.") - (item "{param end}" ccldoc::=> "a non-negative integer. When a STREAM-READ-VECTOR - method is called by READ-SEQUENCE, this argument is - guaranteed to be no less than end and not greater than the - length of vector.")))) - - (definition (:generic-function stream-write-vector) "stream-write-vector stream vector start end" nil - (para "should try to write successive elements of {param - vector} to {param stream}, starting at element {param - start} (inclusive) and continuing through element - {param end} (exclusive.)") - (defsection "Arguments and Values" - (listing :definition - (item "{param stream}" ccldoc::=> "a stream, presumably a fundamental-output-stream") - (item "{param vector}" ccldoc::=> "a vector. When a STREAM-WRITE-VECTOR method is called - by WRITE-SEQUENCE, this argument is guaranteed to be a - simple one-dimensional array.") - (item "{param start}" ccldoc::=> "a non-negative integer. When a STREAM-WRITE-VECTOR - method is called by WRITE-SEQUENCE, this argument is - guaranteed to be no greater than end and not greater than - the length of vector.") - (item "{param end}" ccldoc::=> "a non-negative integer. When a STREAM-WRITE-VECTOR - method is called by WRITE-SEQUENCE, this argument is - guaranteed to be no less than end and not greater than the - length of vector.")))) - - (definition (:generic-function stream-device) "ccl::stream-device s direction" - "Returns the OS file descriptor associated with a - given lisp stream." - (defsection "Method Signatures" - "{code {function stream-device} - (s stream) direction => fd}") - (defsection "Arguments and Values" - (listing :definition - (item "{param s}" ccldoc::=> "a stream.") - (item "{param direction}" ccldoc::=> "either :INPUT or :OUTPUT.") - (item "{param fd}" ccldoc::=> "a file descriptor, which is a non-negative integer - used by the OS to refer to an open file, socket, or similar - I/O connection. NIL if there is no file descriptor associated - with {param s} in the direction given by - {param direction}."))) - (defsection "Description" - (para "Returns the file descriptor associated with - {param s} in the direction given by - {param direction}. It is necessary to specify - {param direction} because the input and output - file descriptors may be different; the most common case is when - one of them has been redirected by the Unix shell."))) - - (definition (:generic-function stream-read-ivector) "stream-read-ivector stream ivector start-octet max-octets" - nil - (defsection "Description" - (para "Reads up to max-octets octets from stream into ivector, - storing them at start-octet. Returns the number of octets actually - read.")) - (defsection "Arguments" - (listing :definition - (item "{param stream}" ccldoc::=> "An input stream. The method defined on - BUFFERED-INPUT-STREAMs requires that the size in octets of - an instance of the stream's element type is 1.") - (item "{param ivector}" ccldoc::=> "Any ivector.") - (item "{param start-octet}" ccldoc::=> "A non-negative integer.") - (item "{param max-octets}" ccldoc::=> "A non-negative integer. The return value may be less - than the value of this parameter if EOF was encountered.")))) - - (definition (:generic-function stream-write-ivector) "stream-write-ivector stream ivector start-octet max-octets" - nil - (defsection "Description" - (para "Writes max-octets octets to stream from ivector, starting at - start-octet. Returns max-octets.")) - (defsection "Arguments" - (listing :definition - (item "{param stream}" ccldoc::=> "An input stream. The method defined on - BUFFERED-OUTPUT-STREAMs requires that the size in octets of - an instance of the stream's element type is 1.") - (item "{param ivector}" ccldoc::=> "Any ivector") - (item "{param start-octet}" ccldoc::=> "A non-negative integer.") - (item "{param max-octet}" ccldoc::=> "A non-negative integer."))) - (defsection "Examples" - (code-block #:| -;;; Write the contents of a (SIMPLE-ARRAY(UNSIGNED-BYTE 16) 3) -;;; to a character file stream. Read back the characters. -(let* ((a (make-array 3 - :element-type '(unsigned-byte 16) - :initial-contents '(26725 27756 28449)))) - (with-open-file (s "junk" - :element-type 'character - :direction :io - :if-does-not-exist :create - :if-exists :supersede) - ;; Write six octets (three elements). - (stream-write-ivector s a 0 6) - ;; Rewind, then read a line - (file-position s 0) - (read-line s))) - -;;; Write a vector of DOUBLE-FLOATs. Note that (to maintain -;;; alignment) there are 4 octets of padding before the 0th -;;; element of a (VECTOR DOUBLE-FLOAT) on 32-bit platforms. -;;; (Note that (= (- target::misc-dfloat-offset -;;; target::misc-data-offset) 4)) -(defun write-double-float-vector - (stream vector &key (start 0) (end (length vector))) - (check-type vector (vector double-float)) - (let* ((start-octet (+ (* start 8) - (- target::misc-dfloat-offset - target::misc-data-offset))) - (num-octets (* 8 (- end start)))) - (stream-write-ivector stream vector start-octet num-octets))) - |))))) - - (defsection "Lisp Standard Streams and OS Standard Streams" - "In normal interactive usage, the input and output sides of the - bidirectional stream {code *terminal-io*} are hooked up to the - the operating system's standard input and standard output. The - lisp streams {code *standard-input*}, {code *standard-output*}, - and {code *error-output*} are synonym streams for {code - *terminal-io*}. - - In batch mode, this arrangement is modified slightly. The lisp - streams {code *standard-input*}, {code *standard-output*}, and - {code *standard-error*} correspond directly to the operating - system's standard input, standard output, and standard error. If - the lisp can determine that it has access to an operating system - tty, then {code *terminal-io*} will be hooked up to that. - Otherwise, the input and output streams of {code *terminal-io*} - will correspond to the operating system's standard input and - standard output.")) -) ;chapter diff --git a/ccl-documentation/threads.ccldoc b/ccl-documentation/threads.ccldoc deleted file mode 100644 index 8d5e149..0000000 --- a/ccl-documentation/threads.ccldoc +++ /dev/null @@ -1,1566 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Programming with Threads" - (defsection "Threads Overview" - #:|{CCL} provides facilities which enable multiple threads - of execution ({emphasis threads}, sometimes called - {emphasis lightweight processes} or just - {emphasis processes}, though the latter term shouldn't - be confused with the OS's notion of a process) within a lisp - session. This document describes those facilities and issues - related to multithreaded programming in {CCL}. - - Wherever possible, I'll try to use the term "thread" to - denote a lisp thread, even though many of the functions in the - API have the word "process" in their name. A - {emphasis lisp-process} is a lisp object (of type - CCL:PROCESS) which is used to control and communicate with an - underlying {emphasis native thread}. Sometimes, the - distinction between these two (quite different) objects can be - blurred; other times, it's important to maintain. - - Lisp threads share the same address space, but maintain - their own execution context (stacks and registers) and their own - dynamic binding context. - - Traditionally, {CCL}'s threads have been - {emphasis cooperatively scheduled}: through a - combination of compiler and runtime support, the currently - executing lisp thread arranged to be interrupted at certain - discrete points in its execution (typically on entry to a - function and at the beginning of any looping construct). This - interrupt occurred several dozen times per second; in response, - a handler function might observe that the current thread had - used up its time slice and another function ({emphasis the lisp - scheduler}) would be called to find some other thread - that was in a runnable state, suspend execution of the current - thread, and resume execution of the newly executed thread. The - process of switching contexts between the outgoing and incoming - threads happened in some mixture of Lisp and assembly language - code; as far as the OS was concerned, there was one native - thread running in the Lisp image and its stack pointer and other - registers just happened to change from time to time. - - Under {CCL}'s cooperative scheduling model, it was - possible (via the use of the CCL:WITHOUT-INTERRUPTS construct) - to defer handling of the periodic interrupt that invoked the - lisp scheduler; it was not uncommon to use WITHOUT-INTERRUPTS to - gain safe, exclusive access to global data structures. In some - code (including much of {CCL} itself) this idiom was very - common: it was (justifiably) believed to be an efficient way of - inhibiting the execution of other threads for a short period of - time. - - The timer interrupt that drove the cooperative scheduler - was only able to (pseudo-)preempt lisp code: if any thread - called a blocking OS I/O function, no other thread could be - scheduled until that thread resumed execution of lisp code. Lisp - library functions were generally attuned to this constraint, and - did a complicated mixture of polling and "timed blocking" in an - attempt to work around it. Needless to say, this code is - complicated and less efficient than it might be; it meant that - the lisp was a little busier than it should have been when it - was "doing nothing" (waiting for I/O to be possible.) - - For a variety of reasons - better utilization of CPU - resources on single and multiprocessor systems and better - integration with the OS in general - threads in {CCL} 0.14 and - later are {emphasis preemptively scheduled. }In this - model, lisp threads are native threads and all scheduling - decisions involving them are made by the OS kernel. (Those - decisions might involve scheduling multiple lisp threads - simultaneously on multiple processors on SMP systems.) This - change has a number of subtle effects:| - (listing :bullet - (item "it is possible for two (or more) lisp threads to be - executing simultaneously, possibly trying to access and/or - modify the same data structures. Such access really should - have been coordinated through the use of synchronization - objects regardless of the scheduling modeling effect; - preemptively scheduled threads increase the chance of things - going wrong at the wrong time and do not offer - lightweight alternatives to the use of those synchronization - objects.") - (item "even on a single-processor system, a context switch - can happen on any instruction boundary. Since (in general) - other threads might allocate memory, this means that a GC can - effectively take place at any instruction boundary. That's - mostly an issue for the compiler and runtime system to be - aware of, but it means that certain practices(such as trying - to pass the address of a lisp object to foreign code)that - were always discouraged are now discouraged - ... vehemently.") - (item #:|there is no simple and efficient way to "inhibit the - scheduler"or otherwise gain exclusive access to the entire - CPU.|) - (item "There are a variety of simple and efficient ways - to synchronize access to particular data - structures.")) - "As a broad generalization: code that's been aggressively - tuned to the constraints of the cooperative scheduler may need - to be redesigned to work well with the preemptive scheduler (and - code written to run under {CCL}'s interface to the native - scheduler may be less portable to other CL implementations, many - of which offer a cooperative scheduler and an API similar to - {CCL} (< 0.14) 's.) At the same time, there's a large - overlap in functionality in the two scheduling models, and it'll - hopefully be possible to write interesting and useful MP code - that's largely independent of the underlying scheduling - details. - - The keyword :OPENMCL-NATIVE-THREADS is on *FEATURES* in - 0.14 and later and can be used for conditionalization where - required.") - (defsection "(Intentionally) Missing Functionality" - (para "Much of the functionality described above is similar to - that provided by {CCL}'s cooperative scheduler, some other - parts of which make no sense in a native threads - implementation.") - (listing :bullet - (item #:|PROCESS-RUN-REASONS and PROCESS-ARREST-REASONS were - SETFable process attributes; each was just a list of - arbitrary tokens. A thread was eligible for scheduling - (roughly equivalent to being "enabled") if its arrest-reasons - list was empty and its run-reasons list was not. I don't - think that it's appropriate to encourage a programming style - in which otherwise runnable threads are enabled and disabled - on a regular basis (it's preferable for threads to wait for - some sort of synchronization event to occur if they can't - occupy their time productively.)|) - (item "There were a number of primitives for maintaining - process queues;that's now the OS's job.") - (item "Cooperative threads were based on coroutining - primitives associated with objects of type - STACK-GROUP. STACK-GROUPs no longerexist."))) - (defsection "Implementation Decisions and Open Questions" - (defsection "Thread Stack Sizes" - #:|When you use MAKE-PROCESS to create a thread, you can - specify a stack size. {CCL} does not impose a limit on the stack - size you choose, but there is some evidence that choosing a - stack size larger than the operating system's limit can cause - excessive paging activity, at least on some operating - systems. - - The maximum stack size is operating-system-dependent. You - can use shell commands to determine what it is on your - platform. In bash, use "ulimit -s -H" to find the limit; in - tcsh, use "limit -h s". - - This issue does not affect programs that create threads - using the default stack size, which you can do either by - specifying no value for the :stack-size argument to - MAKE-PROCESS, or by specifying the value - CCL::*default-control-stack-size*. - - If your program creates threads with a specified stack size, - and that size is larger than the OS-specified limit, you may want - to consider reducing the stack size in order to avoid possible - excessive paging activity.|) - (defsection " As of August 2003:" - (listing :bullet - (item "It's not clear that exposing - PROCESS-SUSPEND/PROCESS-RESUME is a good idea: it's not clear - that they offer ways to win, and it's clear that they offer - ways to lose.") - (item #:|It has traditionally been possible to reset and enable - a process that's "exhausted" . (As used here, the - term "exhausted" means that the process's initial function - has run and returned and the underlying native thread has - been deallocated.) One of the principal uses of PROCESS-RESET - is to "recycle" threads; enabling an exhausted process - involves creating a new native thread (and stacks and - synchronization objects and ...),and this is the sort of - overhead that such a recycling scheme is seeking to avoid. It - might be worth trying to tighten things up and declare that - it's an error to apply PROCESS-ENABLE to an exhausted thread - (and to make PROCESS-ENABLE detect this error.)|) - (item #:|When native threads that aren't created by {CCL} - first call into lisp, a "foreign process" is created, and - that process is given its own set of initial bindings and set - up to look mostly like a process that had been created by - MAKE-PROCESS. The life cycle of a foreign process is - certainly different from that of a lisp-created one: it - doesn't make sense to reset/preset/enable a foreign process, - and attempts to perform these operations should be - detected and treated as errors.|)))) - (defsection "Porting Code from the Old Thread Model" - #:|Older versions of {CCL} used what are often called - "user-mode threads", a less versatile threading model which does - not require specific support from the operating system. This - section discusses how to port code which was written for that - mode. - - It's hard to give step-by-step instructions; there are certainly - a few things that one should look at carefully:| - (listing :bullet - (item "It's wise to be suspicious of most uses - of WITHOUT-INTERRUPTS; there may be exceptions, but - WITHOUT-INTERRUPTS is often used as shorthand for - WITH-APPROPRIATE-LOCKING. Determining what type of locking - is appropriate and writing the code to implement it is - likely to be straightforward and simple most of the - time.") - (item #:|I've only seen one case where a process's "run reasons" - were used to communicate information as well as to control - execution; I don't think that this is a common idiom, but may - be mistaken about that. - |) - (item "It's certainly possible that programs written - for cooperatively scheduled lisps that have run reliably for - a long time have done so by accident: resource-contention - issues tend to be timing-sensitive, and decoupling thread - scheduling from lisp program execution affects timing. I know - that there is or was code in both {CCL} and commercial MCL - that was written under the explicit assumption that certain - sequences of open-coded operations were uninterruptable; it's - certainly possible that the same assumptions have been made - (explicitly or otherwise) by application developers."))) - (defsection "Background Terminal Input" - (defsection "Overview" - #:| - Unless and until {CCL} provides alternatives (via window - streams, telnet streams, or some other mechanism) all lisp - processes share a common *TERMINAL-IO* stream (and therefore - share *DEBUG-IO*, *QUERY-IO*, and other standard and - internal interactive streams.) - - It's anticipated that most lisp processes other than - the "Initial" process run mostly in the background. If a - background process writes to the output side of - *TERMINAL-IO*, that may be a little messy and a little - confusing to the user, but it shouldn't really be - catastrophic. All I/O to {CCL}'s buffered streams goes - thru a locking mechanism that prevents the worst kinds of - resource-contention problems. - - Although the problems associated with terminal output - from multiple processes may be mostly cosmetic, the question - of which process receives input from the terminal is likely - to be a great deal more important. The stream locking - mechanisms can make a confusing situation even worse: - competing processes may "steal" terminal input from each - other unless locks are held longer than they otherwise need - to be, and locks can be held longer than they need to be (as - when a process is merely waiting for input to become - available on an underlying file descriptor). - - Even if background processes rarely need to - intentionally read input from the terminal, they may still - need to do so in response to errors or other unanticipated - situations. There are tradeoffs involved in any solution to - this problem. The protocol described below allows background - processes which follow it to reliably prompt for and receive - terminal input. Background processes which attempt to - receive terminal input without following this protocol will - likely hang indefinitely while attempting to do so. That's - certainly a harsh tradeoff, but since attempts to read - terminal input without following this protocol only worked - some of the time anyway, it doesn't seem to be an - unreasonable one. - - In the solution described here (and introduced in - {CCL} 0.9), the internal stream used to provide terminal - input is always locked by some process (the "owning" - process.) The initial process (the process that typically - runs the read-eval-print loop) owns that stream when it's - first created. By using the macro WITH-TERMINAL-INPUT, - background processes can temporarily obtain ownership of the - terminal and relinquish ownership to the previous owner when - they're done with it. - - In {CCL}, BREAK, ERROR, CERROR, Y-OR-N-P, - YES-OR-NO-P, and CCL:GET-STRING- FROM-USER are all defined - in terms of WITH-TERMINAL-INPUT, as are the :TTY - user-interfaces to STEP and INSPECT.|) - (defsection "An example" - (code-block #:| -? Welcome to {CCL} Version (Beta: linux) 0.9! -? - -? (process-run-function "sleeper" #'(lambda () (sleep 5) (break "broken"))) -# - -? -;; -;; Process sleeper(1) needs access to terminal input. -;; - |) - (para #:|This example was run under ILISP; ILISP often gets confused if one - tries to enter input and "point" doesn't follow a prompt. - Entering a "simple" expression at this point gets it back in - synch; that's otherwise not relevant to this example.|) - (code-block #:| -() -NIL -? (:y 1) -;; -;; process sleeper(1) now controls terminal input -;; -> Break in process sleeper(1): broken -> While executing: # -> Type :GO to continue, :POP to abort. -> If continued: Return from BREAK. -Type :? for other options. -1 > :b -(30C38E30) : 0 "Anonymous Function #x3063B276" 52 -(30C38E40) : 1 "Anonymous Function #x304984A6" 376 -(30C38E90) : 2 "RUN-PROCESS-INITIAL-FORM" 340 -(30C38EE0) : 3 "%RUN-STACK-GROUP-FUNCTION" 768 -1 > :pop -;; -;; control of terminal input restored to process Initial(0) -;; -? - |)) - (defsection "A more elaborate example." - (para #:|If a background process ("A") needs access to the terminal - input stream and that stream is owned by another background process - ("B"), process "A" announces that fact, then waits until - the initial process regains control.|) - (code-block #:| -? Welcome to {CCL} Version (Beta: linux) 0.9! -? - -? (process-run-function "sleep-60" #'(lambda () (sleep 60) (break "Huh?"))) -# - -? (process-run-function "sleep-5" #'(lambda () (sleep 5) (break "quicker"))) -# - -? ;; -;; Process sleep-5(2) needs access to terminal input. -;; -() -NIL - -? (:y 2) -;; -;; process sleep-5(2) now controls terminal input -;; -> Break in process sleep-5(2): quicker -> While executing: #x3063CFDE> -> Type :GO to continue, :POP to abort. -> If continued: Return from BREAK. -Type :? for other options. -1 > ;; Process sleep-60(1) will need terminal access when -;; the initial process regains control of it. -;; -() -NIL -1 > :pop -;; -;; Process sleep-60(1) needs access to terminal input. -;; -;; -;; control of terminal input restored to process Initial(0) -;; - -? (:y 1) -;; -;; process sleep-60(1) now controls terminal input -;; -> Break in process sleep-60(1): Huh? -> While executing: #x3063BE5E> -> Type :GO to continue, :POP to abort. -> If continued: Return from BREAK. -Type :? for other options. -1 > :pop -;; -;; control of terminal input restored to process Initial(0) -;; - -? - |)) - (defsection "Summary" - "This scheme is certainly not bulletproof: imaginative - use of PROCESS-INTERRUPT and similar functions might be able - to defeat it and deadlock the lisp, and any scenario where - several background processes are clamoring for access to the - shared terminal input stream at the same time is likely to be - confusing and chaotic. (An alternate scheme, where the input - focus was magically granted to whatever thread the user was - thinking about, was considered and rejected due to technical - limitations.) - - The longer-term fix would probably involve using network or - window-system streams to give each process unique instances of - *TERMINAL-IO*. - - Existing code that attempts to read from *TERMINAL-IO* - from a background process will need to be changed to use - WITH-TERMINAL-INPUT. Since that code was probably not working - reliably in previous versions of {CCL}, this requirement - doesn't seem to be too onerous. - - Note that WITH-TERMINAL-INPUT both requests ownership of - the terminal input stream and promises to restore that - ownership to the initial process when it's done with it. An ad - hoc use of READ or READ-CHAR doesn't make this promise; this - is the rationale for the restriction on the :Y command.")) - (defsection "The Threads which {CCL} Uses for Its Own Purposes" - (para #:| - In the "tty world", {CCL} starts out with 2 lisp-level threads:|) - (code-block " -? :proc -1 : -> listener [Active] -0 : Initial [Active] - ") - #:|If you look at a running {CCL} with a debugging tool, - such as GDB, or Apple's Thread Viewer.app, you'll see an - additional kernel-level thread on Darwin; this is used by the - Mach exception-handling mechanism. - - The initial thread, conveniently named "initial", is the - one that was created by the operating system when it launched - {CCL}. It maps the heap image into memory, does some - Lisp-level initialization, and, when the Cocoa IDE isn't being - used, creates the thread "listener", which runs the top-level - loop that reads input, evaluates it, and prints the - result. - - After the listener thread is created, the initial thread - does "housekeeping": it sits in a loop, sleeping most of the - time and waking up occasionally to do "periodic tasks". These - tasks include forcing output on specified interactive streams, - checking for and handling control-C interrupts, etc. Currently, - those tasks also include polling for the exit status of external - processes and handling some kinds of I/O to and from those - processes. - - In this environment, the initial thread does these - "housekeeping" activities as necessary, until - {code ccl:quit} is called; - {code quit}ting interrupts the initial thread, which - then ends all other threads in as orderly a fashion as possible - and calls the C function {code #_exit}. - - The short-term plan is to handle each external-process in - a dedicated thread; the worst-case behavior of the current - scheme can involve busy-waiting and excessive CPU utilization - while waiting for an external process to terminate in some - cases. - - The Cocoa features use more threads. Adding a Cocoa - listener creates two threads:| - (code-block " - ? :proc - 3 : -> Listener [Active] - 2 : housekeeping [Active] - 1 : listener [Active] - 0 : Initial [Active] - ") - #:|The Cocoa event loop has to run in the initial thread; - when the event loop starts up, it creates a new thread to do the - "housekeeping" tasks which the initial thread would do in the - terminal-only mode. The initial thread then becomes the one to - receive all Cocoa events from the window server; it's the only - thread which can. - - It also creates one "Listener" (capital-L) thread for each - listener window, with a lifetime that lasts as long as the - thread does. So, if you open a second listener, you'll see five - threads all together:| - (code-block " - ? :proc - 4 : -> Listener-2 [Active] - 3 : Listener [Active] - 2 : housekeeping [Active] - 1 : listener [Active] - 0 : Initial [Active] - ") - #:|Unix signals, such as SIGINT (control-C), invoke a handler - installed by the Lisp kernel. Although the OS doesn't make any - specific guarantee about which thread will receive the signal, - in practice, it seems to be the initial thread. The handler - just sets a flag and returns; the housekeeping thread (which may - be the initial thread, if Cocoa's not being used) will check for - the flag and take whatever action is appropriate to the - signal. - - In the case of SIGINT, the action is to enter a break - loop, by calling on the thread being interrupted. When there's - more than one Lisp listener active, it's not always clear what - thread that should be, since it really depends on the user's - intentions, which there's no way to divine programmatically. To - make its best guess, the handler first checks whether the value - of {code ccl:*interactive-abort-process*} is a - thread, and, if so, uses it. If that fails, it chooses the - thread which currently "owns" the default terminal input stream; - see . - - In the bleeding-edge version of the Cocoa support which is - based on Hemlock, an Emacs-like editor, each editor window has a - dedicated thread associated with it. When a keypress event - comes in which affects that specific window the initial thread - sends it to the window's dedicated thread. The dedicated thread - is responsible for trying to interpret keypresses as Hemlock - commands, applying those commands to the active buffer; it - repeats this in a loop, until the window closes. The initial - thread handles all other events, such as mouse clicks and - drags. - - This thread-per-window scheme makes many things simpler, - including the process of entering a "recursive command loop" in - commands like "Incremental Search Forward", etc. (It might be - possible to handle all Hemlock commands in the Cocoa event - thread, but these "recursive command loops" would have to - maintain a lot of context/state information; threads are a - straightforward way of maintaining that information.) - - Currently (August 2004), when a dedicated thread needs to - alter the contents of the buffer or the selection, it does so by - invoking methods in the initial thread, for synchronization - purposes, but this is probably overkill and will likely be - replaced by a more efficient scheme in the future. - - The per-window thread could probably take more - responsibility for drawing and handling the screen than it - currently does; -something- needs to be done to buffer screen - updates a bit better in some cases: you don't need to see - everything that happens during something like indentation; you - do need to see the results... - - When Hemlock is being used, listener windows are editor - windows, so in addition to each "Listener" thread, you should - also see a thread which handles Hemlock command - processing. - - The Cocoa runtime may make additional threads in certain - special situations; these threads usually don't run lisp code, - and rarely if ever run much of it.|) - - (defsection "Threads Dictionary" - (definition (:function all-processes) "all-processes" nil - "Returns a fresh list of all lisp processes (threads) known to - {CCL} as of the precise instant it's called. Since other - threads can create and kill threads at any time, there's - no way to get a perfectly accurate list of all threads.") - - (definition (:function make-process) - "make-process name &key persistent priority class initargs stack-size vstack-size tstack-size initial-bindings use-standard-initial-bindings" - "Creates and returns a new process." - (defsection "Arguments and Values" - (listing :definition - (item "{param name}" ccldoc::=> "a string, used to identify the process.") - (item "{param persistent}" ccldoc::=> "if true, requests that information about the process - be retained by SAVE-APPLICATION so that an equivalent - process can be restarted when a saved image is run. The - default is nil.") - (item "{param priority}" ccldoc::=> "ignored. It - shouldn't be ignored of course, but there are - complications on some platforms. The default is 0.") - (item "{param class}" ccldoc::=> "the class of process object to create; - should be a subclass of CCL:PROCESS. The default is - CCL:PROCESS.") - (item "{param initargs}" ccldoc::=> "Any additional initargs to pass to MAKE-INSTANCE. The default is ().") - (item "{param stack-size}" ccldoc::=> "the size, in bytes, of the newly-created process's - control stack; used for foreign function calls and to save - function return address context. The default is - CCL:*DEFAULT-CONTROL-STACK-SIZE*.") - (item "{param vstack-size}" ccldoc::=> "the size, in bytes, of the newly-created process's - value stack; used for lisp function arguments, local - variables, and other stack-allocated lisp objects. - The default is CCL:*DEFAULT-VALUE-STACK-SIZE*.") - (item "{param tstack-size}" ccldoc::=> "the size, in bytes, of the newly-created process's - temp stack; used for the allocation of dynamic-extent - objects. The default is CCL:*DEFAULT-TEMP-STACK-SIZE*.") - (item "{param use-standard-initial-bindings}" ccldoc::=> #:|when true, the global "standard initial - bindings" are put into effect in the new thread before. See - DEF-STANDARD-INITIAL-BINDING. "standard" initial bindings - are put into effect before any bindings specified by - :initial-bindings are. The default is t. - - {emphasis This option is deprecated: the correct - behavior of many {CCL} components depends on thread-local - bindings of many special variables being in effect.}|) - (item "{param initial-bindings}" ccldoc::=> "an alist of ({param symbol} . - {param valueform}) pairs, which can be - used to initialize special variable bindings in the new - thread. Each {param valueform} is used to - compute the value of a new binding of - {param symbol} in the execution environment of - the newly-created thread. The default is nil.") - (item "{param process}" ccldoc::=> "the newly-created process."))) - (defsection "Description" - (para "Creates and returns a new lisp process (thread) with the - specified attributes. {param process} will not begin - execution immediately; it will need to be - {emphasis preset} (given - an initial function to run, as by - " - (ref (definition :function process-preset)) ") and - {emphasis enabled} - (allowed to execute, as by " - (ref (definition :function process-enable)) ") - before it's able to actually do anything.") - "If {param valueform} is a function, it is - called, with no arguments, in the execution environment of the - newly-created thread; the primary value it returns is used for - the binding of the corresponding {param symbol}. - - Otherwise, {param valueform} is evaluated in the - execution - environment of the newly-created thread, and the resulting value - is used.") - (defsection "See Also" - (clause (ref (definition :function process-preset)) ", " (ref (definition :function process-enable)) ", " - (ref (definition :function process-run-function))))) - (definition (:function process-suspend) "process-suspend process" "Suspends a specified process." - (defsection "Arguments and Values" - (listing :definition - (item "{param process}" ccldoc::=> "a lisp process (thread).") - (item "{param result}" ccldoc::=> "T if {param process} had been runnable - and is now suspended; NIL otherwise. That is, T if - {param process}'s - " - (ref (definition :function process-suspend-count)) " - transitioned from 0 to 1."))) - (defsection "Description" - (para "Suspends {param process}, preventing it from - running, and stopping it if it was already running. This is a fairly - expensive operation, because it involves a few - calls to the OS. It also risks creating deadlock if used - improperly, for instance, if the process being suspended owns a - lock or other resource which another process will wait for.") - (para " - Each - call to {function process-suspend} must be reversed by - a matching call to " - (ref (definition :function process-resume)) " - before {param process} is able to run. What - {function process-suspend} actually does is increment - the " - (ref (definition :function process-suspend-count)) " of - {param process}. - ") - (para "A process can't suspend itself, though this once - worked and this documentation claimed has claimed that it - did.")) - (defsection "See Also" - (clause (ref (definition :function process-resume)) ", " (ref (definition :function process-suspend-count)))) - (defsection "Notes" - (para "{function process-suspend} was previously called - {code process-disable}. - " - (ref (definition :function process-enable)) " - now names a function for which there is no - obvious inverse, so {code process-disable} - is no longer - defined."))) - (definition (:function process-resume) "process-resume process" - "Resumes a specified process which had previously - been suspended by process-suspend." - (defsection "Arguments and Values" - (listing :definition - (item "{param process}" ccldoc::=> "a lisp process (thread).") - (item "{param result}" ccldoc::=> "T if {param process} had been suspended - and is now runnable; NIL otherwise. That is, T if - {param process}'s - " - (ref (definition :function process-suspend-count)) " - transitioned from to 0. - "))) - (defsection "Description" - (para "Undoes the effect of a previous call to - " - (ref (definition :function process-suspend)) "; if - all such calls are undone, makes the process runnable. Has no - effect if the process is not suspended. What - {function process-resume} actually does is decrement - the " - (ref (definition :function process-suspend-count)) " of - {param process}, to a minimum of 0.")) - (defsection "See Also" - (clause (ref (definition :function process-suspend)) ", " (ref (definition :function process-suspend-count)))) - (defsection "Notes" - (para " - This was previously called PROCESS-ENABLE; - " - (ref (definition :function process-enable)) " now does something slightly - different. - "))) - (definition (:function process-suspend-count) "process-suspend-count process" - "Returns the number of currently-pending suspensions - applicable to a given process." - (defsection "Arguments and Values" - (listing :definition - (item "{param process}" ccldoc::=> "a lisp process (thread).") - (item "{param result}" ccldoc::=> #:|The number of "outstanding" - | - (ref (definition :function process-suspend)) " calls on - {param process}, or NIL if - {param process} has expired. - "))) - (defsection "Description" - (para #:|An "outstanding" | (ref (definition :function process-suspend)) " call - is one which has not yet been reversed by a call to - " - (ref (definition :function process-resume)) ". A process expires when - its initial function returns, although it may later be - reset.") - (para "A process is {emphasis runnable} when it has a - {function process-suspend-count} of 0, has been - preset as by " - (ref (definition :function process-preset)) ", and has been - enabled as by " - (ref (definition :function process-enable)) ". Newly-created - processes have a {function process-suspend-count} of - 0.")) - (defsection "See Also" - (clause (ref (definition :function process-suspend)) ", " (ref (definition :function process-resume))))) - (definition (:function process-preset) "process-preset process function {code &rest} args" - "Sets the initial function and arguments of a specified - process." - (defsection "Arguments and Values" - (listing :definition - (item "{param process}" ccldoc::=> "a lisp process (thread).") - (item "{param function}" ccldoc::=> "a function, designated by itself or by a symbol - which names it. - ") - (item "{param args}" ccldoc::=> "a list of values, appropriate as arguments to - {param function}.") - (item "{param result}" ccldoc::=> "undefined."))) - (defsection "Description" - (para "Typically used to initialize a newly-created or newly-reset - process, setting things up so that when {param process} - becomes enabled, it will begin execution by - applying {param function} to {param args}. - {function process-preset} does not enable - {param process}, - although a process must be {function process-preset} - before it can be enabled. Processes are normally enabled by - " - (ref (definition :function process-enable)) ". - ")) - (defsection "See Also" - (clause (ref (definition :function make-process)) ", " (ref (definition :function process-enable)) ", " - (ref (definition :function process-run-function))))) - (definition (:function process-enable) "process-enable process {code &optional} timeout" - "Begins executing the initial function of a specified - process." - (defsection "Arguments and Values" - (listing :definition - (item "{param process}" ccldoc::=> "a lisp process (thread).") - (item "{param timeout}" ccldoc::=> "a time interval in seconds. May be any - non-negative real number the {function floor} of - which fits in 32 bits. The default is 1.") - (item "{param result}" ccldoc::=> "undefined."))) - (defsection "Description" - (para "Tries to begin the execution of {param process}. - An error is signaled if {param process} has never - been " - (ref (definition :function process-preset)) ". Otherwise, - {param process} invokes its initial function. - ") - "{function process-enable} attempts to - synchronize with {param process}, which is presumed - to be reset or in the act of resetting itself. If this attempt - is not successful within the time interval specified by - {param timeout}, a continuable error is signaled, - which offers the opportunity to continue waiting. - - -A process cannot meaningfully attempt to enable itself.") - (defsection "See Also" - (clause (ref (definition :function make-process)) ", " (ref (definition :function process-preset)) ", " - (ref (definition :function process-run-function)))) - (defsection "Notes" - (para "It would be nice to have more discussion of what it means - to synchronize with the process."))) - (definition (:function process-run-function) - "process-run-function process-specifier function {code &rest} args" - "Creates a process, presets it, and enables it. - " - (defsection "Arguments and Values" - (listing :definition - (item "{param process-specifier}" ccldoc::=> "{param name} | - ({code &key} {param name}{param persistent}{param priority}{param class}{param initargs}{param stack-size}{param vstack-size}{param tstack-size}) - ") - (item "{param name}" ccldoc::=> "a string, used to identify the process. - Passed to {function make-process}.") - (item "{param function}" ccldoc::=> "a function, designated by itself or by a symbol - which names it. Passed to - {function process-preset}. - ") - (item "{param persistent}" ccldoc::=> "a boolean, passed to {function make-process}. - ") - (item "{param priority}" ccldoc::=> "ignored.") - (item "{param class}" ccldoc::=> "a subclass of CCL:PROCESS. Passed to - {function make-process}.") - (item "{param initargs}" ccldoc::=> "a list of any additional initargs to pass to - {function make-process}.") - (item "{param stack-size}" ccldoc::=> "a size, in bytes. Passed to - {function make-process}.") - (item "{param vstack-size}" ccldoc::=> "a size, in bytes. Passed to - {function make-process}.") - (item "{param tstack-size}" ccldoc::=> "a size, in bytes. Passed to - {function make-process}.") - (item "{param process}" ccldoc::=> "the newly-created process."))) - (defsection "Description" - (para "Creates a lisp process (thread) via - " - (ref (definition :function make-process)) ", - presets it via " - (ref (definition :function process-preset)) ", and - enables it via " - (ref (definition :function process-enable)) ". This means - that {param process} will immediately begin to - execute. - {function process-run-function} is - the simplest way to create and run a process. - ")) - (defsection "See Also" - (clause (ref (definition :function make-process)) ", " (ref (definition :function process-preset)) ", " - (ref (definition :function process-enable))))) - (definition (:function process-interrupt) "process-interrupt process function {code &rest} args" - "Arranges for the target process to invoke a - specified function at some point in the near future, and then - return to what it was doing." - (defsection "Arguments and Values" - (listing :definition - (item "{param process}" ccldoc::=> "a lisp process (thread).") - (item "{param function}" ccldoc::=> "a function. - ") - (item "{param args}" ccldoc::=> "a list of values, appropriate as arguments to - {param function}.") - (item "{param result}" ccldoc::=> "the result of applying {param function} - to {param args} if {param process} - is the {variable *current-process*}, otherwise - NIL."))) - (defsection "Description" - "Arranges for {param process} - to apply {param function} to {param args} at - some point in the near future (interrupting whatever - {param process} - was doing.) If {param function} returns normally, - {param process} resumes - execution at the point at which it was interrupted. - - {param process} must be in an enabled state in - order to respond - to a {function process-interrupt} request. It's - perfectly legal for a process to call - {function process-interrupt} on itself. - - {function process-interrupt} - uses asynchronous POSIX signals to interrupt threads. If the - thread being interrupted is executing lisp code, it can - respond to the interrupt almost immediately (as soon as it - has finished pseudo-atomic operations like consing and - stack-frame initialization.) - - If the interrupted thread is - blocking in a system call, that system call is aborted by - the signal and the interrupt is handled on return. - - - It is - still difficult to reliably interrupt arbitrary foreign code - (that may be stateful or otherwise non-reentrant); the - interrupt request is handled when such foreign code returns - to or enters lisp.") - (defsection "See Also" (clause (ref (definition :macro without-interrupts)))) - (defsection "Notes" - "It would probably be better for {param result} - to always be NIL, since the present behavior is inconsistent. - - - {function process-interrupt} works by sending signals - between threads, via the C function - {code #_pthread_signal}. It could be argued - that it should be done in one of several possible other ways - under - Darwin, to make it practical to asynchronously interrupt - things which make heavy use of the Mach nanokernel. - ")) - - (definition (:variable *current-process*) "*current-process*" nil - "Bound separately in each process, to that process itself. - It may be used when lisp code needs to find out what process - it is executing in. It should not be set by user code.") - - (definition (:function process-reset) "process-reset process &optional kill-option" nil - "This function causes {param process} to cleanly exit from any - ongoing computation and enter a state wehre it can be {function - process-preset}. - - This is implemented by signaling a condition of type - PROCESS-RESET; user-defined condition handlers should generally - refrain from attempting to handle conditions of this type. - - The {param kill-option} argument is for internal - use only and should not be specified by user code. - - A process can meaningfully reset itself. - - There is in general no way to know precisely when {param - process} has completed the act of resetting or killing itself; a - process which has either entered the limbo of the reset state or - exited has few ways of communicating either fact. - - The function {function process-enable} can reliably determine - when a process has entered the limbo of the reset state, but - can't predict how long the clean exit from ongoing computation - might take: that depends on the behavior of {function - unwind-protect} cleanup forms, and of the OS scheduler. - - Resetting a process other than {variable *current-process*} - involves the use of the function {function process-interrupt}.") - - (definition (:function process-reset-and-enable) "process-reset-and-enable process" - "Reset and enable the specified process, which - may not be the current process." - (defsection "Arguments and Values" - (listing :definition - (item "{param process}" ccldoc::=> "a lisp process (thread), which - may not be the current process.") - (item "{param result}" ccldoc::=> "undefined."))) - (defsection "Description" - (para " - Equivalent to calling (process-reset process) and - (process-enable process). - ")) - (defsection "See Also" - (clause (ref (definition :function process-reset)) ", " (ref (definition :function process-enable))))) - - (definition (:function process-kill) "process-kill process" nil - "Causes {param process} to cleanly exit from any ongoing - computation, and then exit. Note that {code unwind-protect} - cleanup forms will be run with interrupts disabled.") - - (definition (:function process-abort) "process-abort process &optional condition" - (clause "Causes a specified process to process an abort - condition, as if it had invoked - {function abort}.") - (defsection "Arguments and Values" - (listing :definition - (item "{param process}" ccldoc::=> "a lisp process (thread).") - (item "{param condition}" ccldoc::=> "a lisp condition. The default is NIL."))) - (defsection "Description" - (para "Entirely equivalent to calling - (" - (ref (definition :function process-interrupt)) "{param process} - ({function lambda} () - ({function abort}{param condition}))). - Causes {param process} to transfer control to the - applicable handler or restart for {function abort}.") - (para "If {param condition} is non-NIL, - {function process-abort} does not consider any - handlers which are explicitly bound to conditions other than - {param condition}.")) - (defsection "See Also" - (clause (ref (definition :function process-reset)) ", " (ref (definition :function process-kill))))) - (definition (:variable *ticks-per-second*) "*TICKS-PER-SECOND*" "Bound to the clock resolution of the OS - scheduler." - (defsection "Value Type" (para "A positive integer.")) - (defsection "Initial Value" - (para "The clock resolution of the OS scheduler. Currently, - both LinuxPPC and DarwinPPC yield an initial value of 100. - ")) - (defsection "Description" - (para #:|This value is ordinarily of marginal interest at best, - but, for backward compatibility, some functions accept timeout - values expressed in "ticks". This value gives the number of - ticks per second.|)) - (defsection "See Also" (clause (ref (definition :function process-wait-with-timeout))))) - (definition (:function process-whostate) "process-whostate process" - "Returns a string which describes the status of - a specified process." - (defsection "Description" - (listing :definition - (item "{param process}" ccldoc::=> "a lisp process (thread).") - (item "{param whostate}" ccldoc::=> #:|a string which describes the "state" of - {param process}.|)) - (para "This information is primarily for the benefit of - debugging tools. {param whostate} is a terse report - on what {param process} is doing, or not doing, - and why.") - (para "If the process is currently waiting in a call to - " - (ref (definition :function process-wait)) " or - " - (ref (definition :function process-wait-with-timeout)) ", its - {function process-whostate} will be the value - which was passed to that function as {param whostate}. - ")) - (defsection "See Also" - (clause (ref (definition :function process-wait)) ", " (ref (definition :function process-wait-with-timeout)) - ", " (ref (definition :macro with-terminal-input)))) - (defsection "Notes" - (para "This should arguably be SETFable, but doesn't seem to - ever have been."))) - (definition (:function process-allow-schedule) "process-allow-schedule" - "Used for cooperative multitasking; probably never - necessary." - (defsection "Description" - (para "Advises the OS scheduler that the current thread has nothing - useful to do and that it should try to find some other thread to - schedule in its place. There's almost always a better - alternative, such as waiting for some specific event to - occur. For example, you could use a lock or semaphore.")) - (defsection "See Also" - (clause (ref (definition :function make-lock)) ", " (ref (definition :function make-read-write-lock)) ", " - (ref (definition :function make-semaphore)) ", " (ref (definition :function process-input-wait)) ", " - (ref (definition :function process-output-wait)) ", " (ref (definition :macro with-terminal-input)))) - (defsection "Notes" - (para "This is a holdover from the days of cooperative - multitasking. All modern general-purpose operating systems use - preemptive multitasking."))) - (definition (:function process-wait) "process-wait whostate function {code &rest} args" - "Causes the current lisp process (thread) to wait for - a given - predicate to return true." - (defsection "Arguments and Values" - (listing :definition - (item "{param whostate}" ccldoc::=> "a string, which will be the value of - " - (ref (definition :function process-whostate)) " - while the process is waiting.") - (item "{param function}" ccldoc::=> "a function, designated by itself or by a symbol - which names it. - ") - (item "{param args}" ccldoc::=> "a list of values, appropriate as arguments to - {param function}.") - (item "{param result}" ccldoc::=> "NIL."))) - (defsection "Description" - (para "Causes the current lisp process (thread) to repeatedly - apply {param function} to - {param args} until the call returns a true result, then - returns NIL. After - each failed call, yields the CPU as if by - " - (ref (definition :function process-allow-schedule)) ".") - (para " - As with " - (ref (definition :function process-allow-schedule)) ", it's almost - always more efficient to wait for some - specific event to occur; this isn't exactly busy-waiting, but - the OS scheduler can do a better job of scheduling if it's given - the relevant information. For example, you could use a lock - or semaphore.")) - (defsection "See Also" - (clause (ref (definition :function process-whostate)) ", " - (ref (definition :function process-wait-with-timeout)) ", " (ref (definition :function make-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - (definition (:function process-wait-with-timeout) - "process-wait-with-timeout whostate ticks function args" "Causes the current thread to wait for a given - predicate to return true, or for a timeout to expire." - (defsection "Arguments and Values" - (listing :definition - (item "{param whostate}" ccldoc::=> "a string, which will be the value of - " - (ref (definition :function process-whostate)) " - while the process is waiting.") - (item "{param ticks}" ccldoc::=> #:|either a positive integer expressing a duration - in "ticks" (see | - (ref (definition :variable *ticks-per-second*)) "), - or NIL.") - (item "{param function}" ccldoc::=> "a function, designated by itself or by a symbol - which names it.") - (item "{param args}" ccldoc::=> "a list of values, appropriate as arguments to - {param function}.") - (item "{param result}" ccldoc::=> "T if {function process-wait-with-timeout} - returned because its {param function} returned - true, or NIL if it returned because the duration - {param ticks} has been exceeded."))) - (defsection "Description" - (para "If {param ticks} is NIL, behaves exactly like - " - (ref (definition :function process-wait)) ", except for returning T. - Otherwise, {param function} will be tested repeatedly, - in the same - kind of test/yield loop as in " - (ref (definition :function process-wait)) " - until either {param function} returns true, - or the duration {param ticks} has been exceeded. - ") - (para " Having already read the descriptions of - " - (ref (definition :function process-allow-schedule)) " and - " - (ref (definition :function process-wait)) ", the - astute reader has no doubt anticipated the observation that - better alternatives should be used whenever possible.")) - (defsection "See Also" - (clause (ref (definition :variable *ticks-per-second*)) ", " (ref (definition :function process-whostate)) ", " - (ref (definition :function process-wait)) ", " (ref (definition :function make-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - (definition (:macro without-interrupts) "without-interrupts &body body" - "Evaluates its body in an environment in which - process-interrupt requests are deferred." - (defsection "Arguments and Values" - (listing :definition - (item "{param body}" ccldoc::=> "an implicit progn.") - (item "{param result}" ccldoc::=> "the primary value returned by - {param body}."))) - (defsection "Description" - (para "Executes {param body} - in an environment in which " - (ref (definition :function process-interrupt)) " - requests are - deferred. As noted in the description of - " - (ref (definition :function process-interrupt)) ", this has nothing to do - with the - scheduling of other threads; it may be necessary to inhibit - " - (ref (definition :function process-interrupt)) " handling when - (for instance) modifying some data - structure (for which the current thread holds an appropriate lock) - in some manner that's not reentrant.")) - (defsection "See Also" (clause (ref (definition :function process-interrupt))))) - (definition (:macro with-interrupts-enabled) "with-interrupts-enabled {code &body} body" - "Evaluates its body in an environment in which - process-interrupt requests have immediate effect." - (defsection "Arguments and Values" - (listing :definition - (item "{param body}" ccldoc::=> "an implicit progn.") - (item "{param result}" ccldoc::=> "the primary value returned by - {param body}."))) - (defsection "Description" - (para "Executes {param body} - in an environment in which " - (ref (definition :function process-interrupt)) " - requests have immediate effect. - "))) - (definition (:function make-lock) "make-lock {code &optional} name" - "Creates and returns a lock object, which can - be used for synchronization between threads." - (defsection "Arguments and Values" - (listing :definition - (item "{param name}" ccldoc::=> "any lisp object; saved as part of - {param lock}. Typically a string or symbol - which may appear in the " - (ref (definition :function process-whostate)) "s - of threads which are waiting for {param lock}. - ") - (item "{param lock}" ccldoc::=> "a newly-allocated object of type CCL:LOCK."))) - (defsection "Description" - (para #:|Creates and returns a lock object, which can - be used to synchronize access to some shared resource. - {param lock} is - initially in a "free" state; a lock can also be - "owned" by a - thread.|)) - (defsection "See Also" - (clause (ref (definition :macro with-lock-grabbed)) ", " (ref (definition :function grab-lock)) ", " - (ref (definition :function release-lock)) ", " (ref (definition :function try-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - (definition (:macro with-lock-grabbed) "with-lock-grabbed (lock) {code &body} body" - "Waits until a given lock can be obtained, then - evaluates its body with the lock held." - (defsection "Arguments and Values" - (listing :definition - (item "{param lock}" ccldoc::=> "an object of type CCL:LOCK.") - (item "{param body}" ccldoc::=> "an implicit progn.") - (item "{param result}" ccldoc::=> "the primary value returned by - {param body}."))) - (defsection "Description" - (para "Waits until {param lock} is either free or - owned by the calling - thread, then executes {param body} with the - lock owned by the calling thread. If {param lock} - was free when {function with-lock-grabbed} was called, - it is restored to a free state after {param body} - is executed.")) - (defsection "See Also" - (clause (ref (definition :function make-lock)) ", " (ref (definition :function grab-lock)) ", " - (ref (definition :function release-lock)) ", " (ref (definition :function try-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - (definition (:function grab-lock) "grab-lock lock" "Waits until a given lock can be obtained, then - obtains it." - (defsection "Arguments and Values" - (listing :definition (item "{param lock}" ccldoc::=> "an object of type CCL:LOCK."))) - (defsection "Description" - (para "Blocks until {param lock} is owned by the - calling thread.") - (para "The macro " (ref (definition :macro with-lock-grabbed)) "{emphasis could} be defined in - terms of {function grab-lock} and - " - (ref (definition :function release-lock)) ", but it is actually - implemented at a slightly lower level.")) - (defsection "See Also" - (clause (ref (definition :function make-lock)) ", " (ref (definition :macro with-lock-grabbed)) ", " - (ref (definition :function release-lock)) ", " (ref (definition :function try-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - (definition (:function release-lock) "release-lock lock" "Relinquishes ownership of a given lock." - (defsection "Arguments and Values" - (listing :definition (item "{param lock}" ccldoc::=> "an object of type CCL:LOCK."))) - (defsection "Description" - (para "Signals an error of type CCL:LOCK-NOT-OWNER if - {param lock} - is not already owned by the calling thread; otherwise, undoes the - effect of one previous - " - (ref (definition :function grab-lock)) ". If this means that - {function release-lock} has now been called on - {param lock} the same number of times as - " - (ref (definition :function grab-lock)) " has, {param lock} - becomes free.")) - (defsection "See Also" - (clause (ref (definition :function make-lock)) ", " (ref (definition :macro with-lock-grabbed)) ", " - (ref (definition :function grab-lock)) ", " (ref (definition :function try-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - (definition (:function try-lock) "try-lock lock" "Obtains the given lock, but only if it is not - necessary to wait for it." - (defsection "Arguments and Values" - (listing :definition - (item "{param lock}" ccldoc::=> "an object of type CCL:LOCK.") - (item "{param result}" ccldoc::=> "T if {param lock} has been obtained, - or NIL if it has not."))) - (defsection "Description" - (para "Tests whether {param lock} - can be obtained without blocking - that is, either - {param lock} is already free, or it is already owned - by " - (ref (definition :variable *current-process*)) ". If it can, - causes it to - be owned by the calling lisp process (thread) and returns T. - Otherwise, the lock - is already owned by another thread and cannot be obtained without - blocking; NIL is returned in this case.")) - (defsection "See Also" - (clause (ref (definition :function make-lock)) ", " (ref (definition :macro with-lock-grabbed)) ", " - (ref (definition :function grab-lock)) ", " (ref (definition :function release-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - (definition (:function make-read-write-lock) "make-read-write-lock-write-lock" - "Creates and returns a read-write lock, which can - be used for synchronization between threads." - (defsection "Arguments and Values" - (listing :definition - (item "{param read-write-lock}" ccldoc::=> "a newly-allocated object of type - CCL:READ-WRITE-LOCK."))) - (defsection "Description" - (para #:|Creates and returns an object of type CCL::READ-WRITE-LOCK. - A read-write lock may, at any given time, belong to any number - of lisp processes (threads) which act as "readers"; or, it may - belong to at most one process which acts as a "writer". A - read-write lock may never be held by a reader at the same time as - a writer. Initially, {param read-write-lock} has - no readers and no writers.|)) - (defsection "See Also" - (clause (ref (definition :macro with-read-lock)) ", " (ref (definition :macro with-write-lock)) ", " - (ref (definition :function make-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input)))) - (defsection "Notes" - (para #:|There probably should be some way to - atomically "promote" a reader, making it a writer without - releasing the lock, which could otherwise cause delay.|))) - - (definition (:macro with-read-lock) "with-read-lock (read-write-lock) &body body" - "Waits until a given lock is available for - read-only access, then evaluates its body with the lock - held." - (defsection "Arguments and Values" - (listing :definition - (item "{param read-write-lock}" ccldoc::=> "an object of type - CCL:READ-WRITE-LOCK.") - (item "{param body}" ccldoc::=> "an implicit progn.") - (item "{param result}" ccldoc::=> "the primary value returned by - {param body}."))) - (defsection "Description" - (para "Waits until {param read-write-lock} has no - writer, - ensures that " - (ref (definition :variable *current-process*)) " is a - reader of it, then executes {param body}. - ") - (para "After executing {param body}, if - " - (ref (definition :variable *current-process*)) " was not a reader of - {param read-write-lock} before - {function with-read-lock} was called, the lock is - released. If it was already a reader, it remains one.")) - (defsection "See Also" - (clause (ref (definition :function make-read-write-lock)) ", " (ref (definition :macro with-write-lock)) ", " - (ref (definition :function make-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - - (definition (:macro with-write-lock) "with-write-lock (read-write-lock) &body body" - "Waits until the given lock is available for write - access, then executes its body with the lock held." - (defsection "Arguments and Values" - (listing :definition - (item "{param read-write-lock}" ccldoc::=> "an object of type - CCL:READ-WRITE-LOCK.") - (item "{param body}" ccldoc::=> "an implicit progn.") - (item "{param result}" ccldoc::=> "the primary value returned by - {param body}."))) - (defsection "Description" - (para "Waits until {param read-write-lock} has no - readers and no writer other than " - (ref (definition :variable *current-process*)) ", - then ensures that " - (ref (definition :variable *current-process*)) " is the - writer of it. With the lock held, executes {param body}. - ") - (para "After executing {param body}, if - " - (ref (definition :variable *current-process*)) " was not the writer of - {param read-write-lock} before - {function with-write-lock} was called, the lock is - released. If it was already the writer, it remains the - writer.")) - (defsection "See Also" - (clause (ref (definition :function make-read-write-lock)) ", " (ref (definition :macro with-read-lock)) ", " - (ref (definition :function make-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - - (definition (:function make-semaphore) "make-semaphore" - "Creates and returns a semaphore, which can be used - for synchronization between threads." - (defsection "Arguments and Values" - (listing :definition (item "{param semaphore}" ccldoc::=> "a newly-allocated object of type CCL:SEMAPHORE."))) - (defsection "Description" - (para #:|Creates and returns an object of type CCL:SEMAPHORE. - A semaphore has an associated "count" which may be incremented - and decremented atomically; incrementing it represents sending - a signal, and decrementing it represents handling that signal. - {param semaphore} has an initial count of 0.|)) - (defsection "See Also" - (clause (ref (definition :function signal-semaphore)) ", " (ref (definition :function wait-on-semaphore)) ", " - (ref (definition :function timed-wait-on-semaphore)) ", " (ref (definition :function make-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function process-input-wait)) ", " - (ref (definition :function process-output-wait)) ", " (ref (definition :macro with-terminal-input))))) - (definition (:function signal-semaphore) "signal-semaphore semaphore" - "Atomically increments the count of a given - semaphore." - (defsection "Arguments and Values" - (listing :definition - (item "{param semaphore}" ccldoc::=> "an object of type CCL:SEMAPHORE.") - (item "{param result}" ccldoc::=> "an integer representing an error identifier - which was returned by the underlying OS call."))) - (defsection "Description" - (para #:|Atomically increments {param semaphore}'s - "count" by 1; this - may enable a waiting thread to resume execution.|)) - (defsection "See Also" - (clause (ref (definition :function make-semaphore)) ", " (ref (definition :function wait-on-semaphore)) ", " - (ref (definition :function timed-wait-on-semaphore)) ", " (ref (definition :function make-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function process-input-wait)) ", " - (ref (definition :function process-output-wait)) ", " (ref (definition :macro with-terminal-input)))) - (defsection "Notes" - (para "{param result} should probably be interpreted - and acted on by {function signal-semaphore}, because - it is not likely to be meaningful to a lisp program, and the - most common cause of failure is a type error."))) - (definition (:function wait-on-semaphore) "wait-on-semaphore semaphore" - "Waits until the given semaphore has a positive - count which can be atomically decremented." - (defsection "Arguments and Values" - (listing :definition - (item "{param semaphore}" ccldoc::=> "an object of type CCL:SEMAPHORE.") - (item "{param result}" ccldoc::=> "an integer representing an error identifier - which was returned by the underlying OS call."))) - (defsection "Description" - (para "Waits until {param semaphore} - has a positive count that can be - atomically decremented; this will succeed exactly once for each - corresponding call to SIGNAL-SEMAPHORE.")) - (defsection "See Also" - (clause (ref (definition :function make-semaphore)) ", " (ref (definition :function signal-semaphore)) ", " - (ref (definition :function timed-wait-on-semaphore)) ", " (ref (definition :function make-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function process-input-wait)) ", " - (ref (definition :function process-output-wait)) ", " (ref (definition :macro with-terminal-input)))) - (defsection "Notes" - (para "{param result} should probably be interpreted - and acted on by {function wait-on-semaphore}, because - it is not likely to be meaningful to a lisp program, and the - most common cause of failure is a type error."))) - (definition (:function timed-wait-on-semaphore) "timed-wait-on-semaphore semaphore timeout" - "Waits until the given semaphore has a positive - count which can be atomically decremented, or until a timeout - expires." - (defsection "Arguments and Values" - (listing :definition - (item "{param semaphore}" ccldoc::=> "An object of type CCL:SEMAPHORE.") - (item "{param timeout}" ccldoc::=> "a time interval in seconds. May be any - non-negative real number the {function floor} of - which fits in 32 bits. The default is 1.") - (item "{param result}" ccldoc::=> "T if {function timed-wait-on-semaphore} - returned because it was able to decrement the count of - {param semaphore}; NIL if it returned because - the duration {param timeout} has been - exceeded."))) - (defsection "Description" - (para "Waits until {param semaphore} - has a positive count that can be - atomically decremented, or until the duration - {param timeout} has - elapsed.")) - (defsection "See Also" - (clause (ref (definition :function make-semaphore)) ", " (ref (definition :function wait-on-semaphore)) ", " - (ref (definition :function make-lock)) ", " (ref (definition :function make-read-write-lock)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input))))) - (definition (:function process-input-wait) "process-input-wait fd {code &optional} timeout" - "Waits until input is available on a given - file-descriptor." - (defsection "Arguments and Values" - (listing :definition - (item "{param fd}" ccldoc::=> "a file descriptor, which is a non-negative integer - used by the OS to refer to an open file, socket, or similar - I/O connection. See " - (ref (definition :generic-function stream-device)) ".") - (item "{param timeout}" ccldoc::=> - "either NIL or a time interval in milliseconds. Must be a non-negative integer. The default is NIL."))) - (defsection "Description" - "Wait until input is available on {param fd}. - This uses the {code select()} system call, and is - generally a fairly - efficient way of blocking while waiting for input. More - accurately, {function process-input-wait} - waits until it's possible to read - from fd without blocking, or until {param timeout}, if - it is not NIL, has been exceeded. - - - Note that it's possible to read without blocking if - the file is at its end - although, of course, the read will - return zero bytes.") - (defsection "See Also" - (clause (ref (definition :function make-lock)) ", " (ref (definition :function make-read-write-lock)) ", " - (ref (definition :function make-semaphore)) ", " (ref (definition :function process-output-wait)) ", " - (ref (definition :macro with-terminal-input)))) - (defsection "Notes" - (para "{function process-input-wait} has a timeout parameter, - and - " - (ref (definition :function process-output-wait)) " does not. This - inconsistency should probably be corrected. - "))) - (definition (:function process-output-wait) "process-output-wait fd {code &optional} timeout" - "Waits until output is possible on a given file - descriptor." - (defsection "Arguments and Values" - (listing :definition - (item "{param fd}" ccldoc::=> "a file descriptor, which is a non-negative integer - used by the OS to refer to an open file, socket, or similar - I/O connection. See " - (ref (definition :generic-function stream-device)) ".") - (item "{param timeout}" ccldoc::=> - "either NIL or a time interval in milliseconds. Must be a non-negative integer. The default is NIL."))) - (defsection "Description" - "Wait until output is possible on {param fd} or until {param timeout}, if - it is not NIL, has been exceeded. - This uses the {code select()} system call, and is - generally a fairly - efficient way of blocking while waiting to output. - - If {function process-output-wait} is called on - a network socket which has not yet established a connection, it - will wait until the connection is established. This is an - important use, often overlooked.") - (defsection "See Also" - (clause (ref (definition :function make-lock)) ", " (ref (definition :function make-read-write-lock)) ", " - (ref (definition :function make-semaphore)) ", " (ref (definition :function process-input-wait)) ", " - (ref (definition :macro with-terminal-input)))) - (defsection "Notes" - (para (ref (definition :function process-input-wait)) " has a timeout parameter, - and - {function process-output-wait} does not. This - inconsistency should probably be corrected. - "))) - (definition (:macro with-terminal-input) "with-terminal-input {code &body} body" - "Executes its body in an environment with exclusive - read access to the terminal." - (defsection "Arguments and Values" - (listing :definition - (item "{param body}" ccldoc::=> "an implicit progn.") - (item "{param result}" ccldoc::=> "the primary value returned by - {param body}."))) - (defsection "Description" - (para "Requests exclusive read access to the standard terminal - stream, {variable *terminal-io*}. Executes - {param body} in an environment with that access. - ")) - (defsection "See Also" - (clause (ref (definition :variable *request-terminal-input-via-break*)) ", " - (ref (definition :toplevel-command ":Y")) ", " (ref (definition :function make-lock)) ", " - (ref (definition :function make-read-write-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait))))) - (definition (:variable *request-terminal-input-via-break*) "*REQUEST-TERMINAL-INPUT-VIA-BREAK*" - "Controls how attempts to obtain ownership of - terminal input are made." - (defsection "Value Type" (para "A boolean.")) (defsection "Initial Value" (para "NIL.")) - (defsection "Description" - (para "Controls how attempts to obtain ownership of terminal input - are made. When NIL, a message is printed on *TERMINAL-IO*; - it's expected that the user will later yield - control of the terminal via the :Y toplevel command. When T, a - BREAK condition is signaled in the owning process; continuing from - the break loop will yield the terminal to the requesting process - (unless the :Y command was already used to do so in the break - loop.)")) - (defsection "See Also" - (clause (ref (definition :macro with-terminal-input)) ", " (ref (definition :toplevel-command ":Y")) ", " - (ref (definition :function make-lock)) ", " (ref (definition :function make-read-write-lock)) ", " - (ref (definition :function make-semaphore)) ", " (ref (definition :function process-input-wait)) ", " - (ref (definition :function process-output-wait))))) - (definition (:toplevel-command ":Y") "( :y p)" "Yields control of terminal input to a specified - lisp process (thread)." - (defsection "Arguments and Values" - (listing :definition - (item "{param p}" ccldoc::=> "a lisp process (thread), designated either by - an integer which matches its - {function process-serial-number}, - or by a string which is {function equal} to - its {function process-name}."))) - (defsection "Description" - (para ":Y is a toplevel command, not a function. As such, it - can only be used interactively, and only from the initial - process.") - (para "The command yields control of terminal input to the - process {param p}, which must have used - " - (ref (definition :macro with-terminal-input)) " to request access to the - terminal input stream.")) - (defsection "See Also" - (clause (ref (definition :macro with-terminal-input)) ", " - (ref (definition :variable *request-terminal-input-via-break*)) ", " (ref (definition :function make-lock)) - ", " (ref (definition :function make-read-write-lock)) ", " (ref (definition :function make-semaphore)) ", " - (ref (definition :function process-input-wait)) ", " (ref (definition :function process-output-wait))))) - (definition (:function join-process) "join-process process {code &optional} default" - "Waits for a specified process to complete and - returns the values that that process's initial function - returned." - (defsection "Arguments and Values" - (listing :definition - (item "{param process}" ccldoc::=> "a process, typically created by " - (ref (definition :function process-run-function)) " or by " (ref (definition :function make-process))) - (item "{param default}" ccldoc::=> "A default value to be returned if the specified - process doesn't exit normally.") - (item "{param values}" ccldoc::=> "The values returned by the specified process's - initial function if that function returns, or the value - of the default argument, otherwise."))) - (defsection "Description" - (para #:|Waits for the specified process to terminate. If the - process terminates "normally" (if its initial function - returns), returns the values that that initial function - returnes. If the process does not terminate normally (e.g., - if it's terminated via | - (ref (definition :function process-kill)) " and a - default argument is provided, returns the value of that - default argument. If the process doesn't terminate normally - and no default argument is provided, signals an error.") - (para "A process can't successfully join itself, and only one - process can successfully receive notification of another process's - termination."))))) diff --git a/ccl-documentation/unicode.ccldoc b/ccl-documentation/unicode.ccldoc deleted file mode 100644 index b7ff304..0000000 --- a/ccl-documentation/unicode.ccldoc +++ /dev/null @@ -1,362 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Characters and External Formats" - (para "All characters and strings in {CCL} fully support Unicode by - using UTF-32. There is only one {code character} type and one - {code string} type in {CCL}. There has been a lot of discussion - about this decision which can be found by searching the - openmcl-devel archives at {link - http://clozure.com/pipermail/openmcl-devel/}. Suffice it to say - that we decided that the simplicity and speed advantages of only - supporting UTF-32 outweigh the space disadvantage.") - - (defsection "Characters" - (glossentry "code point" - "A value in the Unicode code space; that is, a - non-negative integer below {variable - char-code-limit} (#x110000).") - "There is one {code character} type in {CCL}. - All {code character}s are {code base-char}s. {variable - char-code-limit} is now {code #x110000}, which means that all - Unicode characters can be directly represented. As of Unicode - 5.0, only about 100,000 of 1,114,112 possible {code char-code}s - are actually defined. The function {function code-char} knows that - certain ranges of code values (notably {code #xd800}-{code - #xddff}) will never be valid character codes and will return {code - nil} for arguments in that range, but may return a non-{code nil} - value (an undefined/non-standard {code character} object) for - other unassigned code values. - - {CCL} supports character names of the form {code u+xxxx}-where - {code x} is a sequence of one or more hex digits. The value of - the hex digits denotes the code of the character. The {code +} - character is optional, so {code #\\u+0020}, {code #\\U0020}, and - {code #\\U+20} all refer to the {code #\\Space} character. - - Characters with codes in the range {code #xa0}-{code #x7ff} also - have symbolic names These are the names from the Unicode standard - with spaces replaced by underscores. So {code - #\\Greek_Capital_Letter_Epsilon} can be used to refer to the - character whose {function char-code} is {code #x395}. To see the - complete list of supported character names, look just below the - definition for {function ccl::register-character-name} in {code - ccl:level-1;l1-reader.lisp}.") - - (defsection "External Formats" - (para "The standard functions {code open}, {code load}, and - {code compile-file} all accept an {code :external-format} keyword - argument. The value of {code :external-format} can be - {code :default} (the default value), a line termination - keyword (see {section Line Termination Keywords}), a character - encoding keyword (see {section Character Encodings}), an - external-format object created using {function - make-external-format}, or a plist with the keys {code :domain}, - {code :character-encoding} and {code :line-termination}. If - {param argument} is a plist, the result of {code (apply - #'make-external-format {param argument})} will be used.") - - "If {code :default} is specified, then the value of {variable - *default-external-format*} is used. If no line-termination is - specified, then the value of {variable *default-line-termination*} - is used, which defaults to {code :unix}. If no character encoding - is specified, then {variable *default-file-character-encoding*} is - used for file streams and {variable - *default-socket-character-encoding*} is used for socket streams. - The default, default character encoding is {code nil} which is a - synonym for {code :iso-8859-1}. - - Note that the set of keywords used to denote {code character-encoding}s - and the set of keywords used to denote line-termination - conventions is disjoint: a keyword denotes at most a character - encoding or a line termination convention, but never both. - - EXTERNAL-FORMATs are objects (structures) with two read-only - fields that can be accessed via the functions: {code - external-format-line-termination} and {code - external-format-character-encoding}." - - (definition (:variable *default-external-format*) "ccl:*default-external-format*" nil - (defsection "Description" - "The value of this variable is used - when {code :external-format} is unspecified or specified - as {code :default}. It can meaningfully be given any value - that can be used as an external-format (except for the - value {code :default}.) - - The initial value of this variable in {CCL} is - {code :unix}, which is equivalent to - {code (:line-termination :unix)}, among other - things.")) - - (definition (:variable *default-line-termination*) "ccl:*default-line-termination*" nil - (defsection "Description" - "The value of this variable is used when an - external-format doesn't specify a line-termination - convention (or specifies it as {code :default}.) It can - meaningfully be given any value that can be used as a - line termination keyword - (see {section Line Termination Keywords}). - - The initial value of this variable - in {CCL} is {code :unix}.")) - - (definition (:function make-external-format) - "make-external-format {code &key} domain character-encoding line-termination" - "Either creates a new external format object, or - return an existing one with the same specified slot - values." - (defsection "Arguments and Values" - (listing :definition - (item "{param domain}" ccldoc::=> "This is used - to indicate where the external format is to be used. - Its value can be almost anything. It defaults to {code - NIL}. There are two domains that have a pre-defined - meaning in {CCL}: {code :file} indicates encoding for a - file in the file system and {code :socket} indicates i/o - to/from a socket. The value of {param domain} affects - the default values for {param character-encoding} and - {param line-termination}.") - (item "{param character-encoding}" ccldoc::=> "A - keyword that specifies the character encoding for the - external format. {section Character Encodings}. - Defaults to {code :default} which means if {param - domain} is {code :file} use the value of the variable - {variable *default-file-character-encoding*} and if - {param domain} is {code :socket}, use the value of the - variable {variable *default-socket-character-encoding*}. - The initial value of both of these variables is {code - NIL}, which means the {code :iso-8859-1} encoding.") - (item "{param line-termination}" ccldoc::=> "A - keyword that indicates a line termination keyword - {section Line Termination Keywords}. Defaults to - {code :default} which means use the value of the - variable {variable *default-line-termination*}.") - (item "{param external-format}" ccldoc::=> "An - external-format object as described above."))) - - (defsection "Description" - (para "Despite the function's name, it doesn't necessarily - create a new, unique {code external-format} object: two calls to - {function make-external-format} with the same arguments made in the same - dynamic environment return the same (eq) object.")))) - - (defsection "Line Termination Keywords" - (para "Line termination keywords indicate which characters are - used to indicate the end of a line. On input, the external line - termination characters are replaced by {code #\\Newline} and on - output, {code #\\Newline}s are converted to the external line - termination characters.") - - (table "Line Termination Keywords" - (row (item "keyword") (item "character(s)")) - (row (item "{code :unix}") (item "{code #\\Linefeed}")) - (row (item "{code :macos}") (item "{code #\\Return}")) - (row (item "{code :cr}") (item "{code #\\Return}")) - (row (item "{code :crlf}") (item "{code #\\Return #\\Linefeed}")) - (row (item "{code :cp/m}") (item "{code #\\Return #\\Linefeed}")) - (row (item "{code :msdos}") (item "{code #\\Return #\\Linefeed}")) - (row (item "{code :dos}") (item "{code #\\Return #\\Linefeed}")) - (row (item "{code :windows}") (item "{code #\\Return #\\Linefeed}")) - (row (item "{code :inferred}") (item "see below")) - (row (item "{code :unicode}") (item "{code #\\Line_Separator}"))) - - (para "{code :inferred} means that a stream's line-termination - convention is determined by looking at the contents of a file. It - is only useful for {code file-stream}s that're open for - {code :input} or {code :io}. The first buffer full of data is - examined, and if a {code #\\Return} character occurs before any - {code #\\Linefeed} character, then the line termination type is set - to {code :windows} if that {code #\\Return} character is immediately - followed by a {code #\\Linefeed} character and to {code :macos} - otherwise. If a {code #\\Return} character isn't found in the - buffer or if {code #\\Return} is preceded by {code #\\Linefeed}, the - file's line terminationt type is set to {code :unix}.")) - - (defsection "Character Encodings" - "Internally, all characters and strings in {CCL} are in - UTF-32. Externally, files or socket streams may encode characters - in a wide variety of ways. The International Organization for - Standardization, widely known as ISO, defines many of these - character encodings. {CCL} implements some of these encodings as - detailed below. These encodings are part of the specification of - external formats (see {section External Formats}). When reading - from a stream, characters are converted from the specified - external character encoding to UTF-32. When writing to a stream, - characters are converted from UTF-32 to the specified character - encoding. - - Internally, {code character-encoding}s are objects (structures) - that are named by character encoding keywords ({code :iso-8859-1}, - {code :utf-8}, etc.). The structures contain attributes of the encoding - and functions used to encode/decode external data, but unless - you are trying to define or debug an encoding, there is little reason - to know much about the {code character-encoding} objects and it is - usually preferable to refer to a character encoding by its name." - - (para "The set of character encodings supported by {CCL} can be - retrieved by calling {function describe-character-encodings}.") - - (definition (:function describe-character-encodings) "describe-character-encodings" nil - (defsection "Description" - (para "Writes descriptions of all defined character encodings - to {variable *terminal-io*}. These descriptions - include the names of the encoding’s aliases and a doc string - which briefly describes each encoding’s properties and - intended use."))) - - (defsection "Encoding Problems" - (para "When a character cannot be encoded or decoded according to a - specified external format, the character in question will be replaced with - an encoding-specific replacement character. This will be - {code #\\Replacement_Character} if the destination external format includes - such a character; otherwise the replacement character will be {code #\\Sub}.") - (para "The presence of a replacement character - typically indicates that something got lost in - translation: either data was not encoded properly or there was a - bug in the decoding process.")) - - (defsection "Byte Order Marks" - "The endianness of a character encoding is sometimes - explicit, and sometimes not. For example, - {code :utf-16be} indicates big-endian, but - {code :utf-16} does not specify endianness. A byte - order mark is a special character that may appear at the - beginning of a stream of encoded characters to specify the - endianness of a multi-byte character encoding. (It may also be - used with UTF-8 character encodings, where it is simply used to - indicate that the encoding is UTF-8.) - - {CCL} writes a byte order mark as the first character - of a file or socket stream when the endianness of the character - encoding is not explicit. {CCL} also expects a byte order - mark on input from streams where the endianness is not - explicit. If a byte order mark is missing from input data, that - data is assumed to be in big-endian order. - - A byte order mark from a UTF-8 encoded input stream is not - treated specially and just appears as a normal character from - the input stream. It is probably a good idea to skip over this - character.") - - - (defsection "Selected Character Encodings" - (para "A few commonly-used encodings are described here. For the - complete list, call {function describe-character-encodings}. Most - encodings have aliases, e.g. the encoding named - {code :iso-8859-1} can also be referred to by the - names {code :latin1} and {code :ibm819}, - among others. Where possible, the keywordized name of an - encoding is equivalent to the preferred MIME charset name (and - the aliases are all registered IANA charset names.)") - (listing :definition - (item "{code :utf-8}" ccldoc::=> "An 8-bit, variable-length character encoding in - which characters with CHAR-CODEs in the range #x00-#x7f can be - encoded in a single octet; characters with larger code values - can be encoded in 2 to 4 bytes. - - {CCL} uses this encoding for {variable *terminal-io*} and for all streams whose - EXTERNAL-FORMAT isn't explicitly specified. The default for - {variable *terminal-io*} can be set via the - {code -K} command-line argument (see {section Command Line Options}).") - - (item "{code :iso-8859-1}" ccldoc::=> "An 8-bit, fixed-width character encoding in - which all character codes map to their Unicode - equivalents. Intended to support most characters used in most - Western European languages. - - ISO-8859-1 just covers the first 256 Unicode code - points, where the first 128 code points are equivalent to - US-ASCII. That should be pretty much equivalent to what - earliers versions of {CCL} did that only supported 8-bit characters, - but it may not be optimal for users working in a particular - locale. - - Aliases: {code :iso_8859-1, :latin1, :l1, - :ibm819, :cp819, :csisolatin1}") - - (item "{code :us-ascii}" ccldoc::=> "An 7-bit, fixed-width character encoding in - which all character codes map to their Unicode - equivalents. - - Aliases: {code :csascii, :cp637, :ibm637, :us, - :iso646-us, :ascii, :iso-ir-6}") - - (item "{code :utf-16}" ccldoc::=> "A 16-bit, variable-length encoding in which - characters with CHAR-CODEs less than #x10000 can be encoded in - a single 16-bit word and characters with larger codes can be - encoded in a pair of 16-bit words. The endianness of the - encoded data is indicated by the endianness of a - byte-order-mark character (#u+feff) prepended to the data; in - the absence of such a character on input, the data is assumed - to be in big-endian order. Output is written in native - byte-order with a leading byte-order mark."))) - - (defsection "Encoding and Decoding Strings" - - "{CCL} provides functions to encode and decode strings to - and from vectors of type (simple-array (unsigned-byte 8))." - - (definition (:function count-characters-in-octet-vector) - "count-characters-in-octet-vector vector {code &key} start end external-format" nil - "Returns the number of characters that would be - produced by decoding {param vector} (or the subsequence thereof - delimited by {param start} and {param end}) according to {param - external-format}.") - - (definition (:function decode-string-from-octets) - "decode-string-from-octets vector {code &key} start end external-format string" nil - (defsection "Description" - "Decodes the octets in {param vector} (or the - subsequence of it delimited by {param start} and {param end}) into - a string according to {param external-format}. - - If {param string} is supplied, output will be written into it. It - must be large enough to hold the decoded characters. If {param - string} is not supplied, a new string will be allocated to hold - the decoded characters. - - Returns, as multiple values, the decoded string and the position - in {param vector} where the decoding ended. - - Sequences of octets in {param vector} that cannot be decoded into - characters according to {param external-format} will be decoded as - {code #\\Replacement_Character}.")) - - (definition (:function encode-string-to-octets) - "encode-string-to-octets string &key start end external-format use-byte-order-mark vector vector-offset" nil - "Encodes {param string} (or the substring of it delimited by - {param start} and {param end}) into {param vector} according to - {param external-format}. - It returns, as multiple values, the vector of octets - containing the encoded data and an integer that specifies - the offset into the vector where the encoded data ends. - - When {param use-byte-order-mark} is true, a byte-order mark - will be included in the encoded data. - - If {param vector} is supplied, output will be written to it. - It must be of type {code (simple-array (unsigned-byte 8))} - and be large enough to hold the encoded data. If it is not - supplied, the function will allocate a new vector to hold - the output. - - If {param vector-offset} is supplied, data will be written - into the output vector starting at that offset. - - Characters in {param string} that cannot be encoded into - {param external-format} will be replaced with an - encoding-dependent replacement character - (either {code #\\Replacement_Character} or {code #\\Sub)} before - being encoded and written into the output vector.") - - (definition (:function string-size-in-octets) - "string-size-in-octets string &key start end external-format use-byte-order-mark" nil - "Returns the number of octets required to encode {param - string} (or the substring delimited by {code :start} and - {code :end}) according to {code :external-format}. - - When {param use-byte-order-mark} is true, the returned size - will include the space needed for a byte-order marker."))) - -) ;chapter - diff --git a/ccl-documentation/using.ccldoc b/ccl-documentation/using.ccldoc deleted file mode 100644 index 5a5d041..0000000 --- a/ccl-documentation/using.ccldoc +++ /dev/null @@ -1,866 +0,0 @@ -;;; -*- Mode: Lisp; Package: CCL; Coding: utf-8; -*- - -(chapter "Using {CCL}" - (defsection "Introduction" - (para "The Common Lisp standard allows considerable latitude in the - details of an implementation, and each particular Common Lisp - system has some idiosyncrasies. This chapter describes ordinary - user-level features of {CCL}, including features that may be - part of the Common Lisp standard, but which may have quirks or - details in the {CCL} implementation that are not described by - the standard. It also describes extensions to the standard; that - is, features of {CCL} that are not part of the Common Lisp - standard at all.")) - - - (defsection "Memory-mapped Files" - (para "In release 1.2 and later, {CCL} - supports " - (ref (glossentry "memory-mapped file") "memory-mapped files") ". On operating systems that support memory-mapped - files (including Mac OS X, Linux, and FreeBSD), the operating - system can arrange for a range of virtual memory addresses to - refer to the contents of an open file. As long as the file remains - open, programs can read values from the file by reading addresses - in the mapped range.") - "Using memory-mapped files may in some cases be more - efficient than reading the contents of a file into a data - structure in memory. - - {CCL} provides the - functions {function map-file-to-ivector} - and {function map-file-to-octet-vector} to support - memory-mapping. These functions return vectors whose contents are - the contents of memory-mapped files. Reading an element of such a - vector returns data from the corresponding position in the - file. - - Without memory-mapped files, a common idiom for reading the - contents of files might be something like this:" - (code-block "(let* ((stream (open pathname :direction :input :element-type '(unsigned-byte 8))) - (vector (make-array (file-size-to-vector-size stream) - :element-type '(unsigned-byte 8)))) - (read-sequence vector stream)) - ") - "Using a memory-mapped files has a result that is the same in - that, like the above example, it returns a vector whose contents are - the same as the contents of the file. It differs in that the above - example creates a new vector in memory and copies the file's - contents into it; using a memory-mapped file instead arranges for - the vector's elements to point to the file's contents on disk - directly, without copying them into memory first. - - The vectors returned by {function map-file-to-ivector} - and {function map-file-to-octet-vector} are read-only; any - attempt to change an element of a vector returned by these - functions results in a memory-access error. {CCL} does not - currently support writing data to memory-mapped files. - - Vectors created by {function map-file-to-ivector} - and {function map-file-to-octet-vector} are required to - respect {CCL}'s limit on the total size of an array. That means - that you cannot use these functions to create a vector longer - than {variable array-total-size-limit}, even if the filesystem - supports file sizes that are larger. The value - of {variable array-total-size-limit} is {code (expt 2 24)} - on 32-but platforms; and {code (expt 2 56)} on 64-bit - platforms." - - (definition (:function map-file-to-ivector) "map-file-to-ivector pathname element-type" nil - (para " - The {function map-file-to-ivector} function tries to - open the file at {param pathname} for reading. If - successful, the function maps the file's contents to a range of - virtual addresses. If successful, it returns a read-only vector - whose element-type is given - by {param element-type}, and whose contents are - the contents of the memory-mapped file. - ") - (defsection "Description" - (listing :definition - (item "{param pathname}" ccldoc::=> "The pathname of the file to be memory-mapped.") - (item "{param element-type}" ccldoc::=> "The element-type of the vector to be - created. Specified as - a " - (term "type-specifier") " - that names a subtype of either {code signed-byte} - or {code unsigned-byte}.")) - - (para "The returned vector is - a " - (ref (glossentry "displaced array") "displaced-array") " - whose element-type is {code (UPGRADED-ARRAY-ELEMENT-TYPE - element-type)}. The target of the displaced array is a - vector of type {code (SIMPLE-ARRAY element-type (*))} whose - elements are the contents of the memory-mapped file.") - "Because of alignment issues, the mapped file's contents - start a few bytes (4 bytes on 32-bit platforms, 8 bytes on - 64-bit platforms) into the vector. The displaced array returned - by {function map-file-to-ivector} hides this overhead, but - it's usually more efficient to operate on the underlying simple - 1-dimensional array. Given a displaced array (like the value - returned by {function map-file-to-ivector}), the function - {function array-displacement} returns the underlying array and - the displacement index in elements. - - - Currently, {CCL} supports only read operations on - memory-mapped files. If you try to change the contents of an array - returned by {function map-file-to-ivector}, {CCL} signals - a memory error.")) - - (definition (:function unmap-ivector) "unmap-ivector displaced-array" nil - (defsection "Description" - (para "If the argument is a displaced-array returned - by {function map-file-to-ivector}, and if it has not yet - been unmapped by this function, - then {function unmap-ivector} undoes the memory mapping, - closes the mapped file, and changes the displaced-array so that its - target is an empty vector (of length zero)."))) - - (definition (:function map-file-to-octet-vector) "map-file-to-octet-vector displaced-array" nil - (defsection "Description" - (para "This function is a synonym for {code (map-file-to-ivector - pathname '(unsigned-byte 8))} It is provided as a convenience - for the common case of memory-mapping a file as a vector of - bytes."))) - - (definition (:function unmap-octet-vector) "unmap-octet-vector displaced-array" nil - (defsection "Description" - (para "This function is a synonym for {function unmap-ivector}")))) - - (defsection "Static Variables" - (para "{CCL} supports the definition - of " - (ref (glossentry "static variable") "static variables") ", whose values are the same across threads, - and which may not be dynamically bound. The value of a static - variable is thus the same across all threads; changing the value - in one thread changes it for all threads.") - "Attempting to dynamically rebind a static variable (for - instance, by using {code LET}, or using the variable name as - a parameter in a {code LAMBDA} form) signals an - error. Static variables are shared global resources; a dynamic - binding is private to a single thread. - - Static variables therefore provide a simple way to share - mutable state across threads. They also provide a simple way to - introduce race conditions and obscure bugs into your code, since - every thread reads and writes the same instance of a given static - variable. You must take care, therefore, in how you change the - values of static variables, and use normal multithreaded - programming techniques, such as locks or semaphores, to protect - against race conditions. - - In {CCL}, access to a static variable is usually faster than - access to a special variable that has not been declared - static." - (definition (:macro defstatic) "defstatic var value &key docstring" nil - (para "Proclaims the - variable " - (ref (glossentry "special variable") "special") ", - assigns the variable the supplied {param value}, and assigns - the {param docstring} to the - variable's {code variable} documentation. Marks the - variable static, preventing any attempt to dynamically rebind - it. Any attempt to dynamically rebind {param var} - signals an error."))) - - (defsection "Saving Applications" - nil - (para "{CCL} provides the - function {function save-application}, which creates a file - containing an archived Lisp memory image.") - (para "{CCL} consists of a small executable called the - {term lisp kernel}, which - implements the very lowest level features of the Lisp system, and - a {term heap image}, which - contains the in-memory representation of most of the Lisp system, - including functions, data structures, variables, and so on. When - you start {CCL}, you are launching the kernel, which then locates - and reads an image file, restoring the archived image in - memory. Once the image is fully restored, the Lisp system is - running.") - "Using {function save-application}, you can create a - file that contains a modified image, one that includes any changes - you've made to the running Lisp system. If you later pass your - image file to the {CCL} kernel as a command-line parameter, it - then loads your image file instead of its default one, and {CCL} - starts up with your modifications. - - If this scenario seems to you like a convenient way to - create an application, that's just as intended. You can create an - application by modifying the running Lisp until it does what you - want, then use {function save-application} to preserve your - changes and later load them for use." - (para "In fact, you can go further than that. You can replace - {CCL}'s " - (term "toplevel function") " with your own, and then, when the image is - loaded, the Lisp system immediately performs your tasks rather - than the default tasks that make it a Lisp development system. If - you save an image in which you have done this, the resulting Lisp - system is your tool rather than a Lisp development system.") - "You can go a step further still. You can - tell {function save-application} to prepend the Lisp kernel - to the image file. Doing this makes the resulting image into a - self-contained executable binary. When you run the resulting file, - the Lisp kernel immediately loads the attached image file and runs - your saved system. The Lisp system that starts up can have any - behavior you choose. It can be a Lisp development system, but with - your customizations; or it can immediately perform some task of - your design, making it a specialized tool rather than a general - development system. - - In other words, you can develop any application you like by - interactively modifying {CCL} until it does what you want, then - using {function save-application} to preserve your changes - in an executable image." - (para "On Mac OS X, - the " - (ref (section "The Application Builder") "application builder") " - uses {function save-application} to create the executable - portion of the " - (term "application bundle") ". Double-clicking the application bundle runs - the executable image created - by {function save-application}.") - "Also on Mac OS X, {CCL} supports an object type - called {code macptr}, which is the type of pointers into the - foreign (Mac OS) heap. Examples of - commonly-user {code macptr} objects are Cocoa windows and - other dynamically-allocated Mac OS system objects. - - Because a {code macptr} object is a pointer into a - foreign heap that exists for the lifetime of the running Lisp - process, and because a saved image is used by loading it into a - brand new Lisp process, saved {code macptr} objects cannot - be relied on to point to the same things when reconstituted from a - saved image. In fact, a restored {code macptr} object might - point to anything at all-for example an arbitrary location - in the middle of a block of code, or a completely nonexistent - virtual address. - - For that reason, {code save-application} converts - all {code macptr} objects to {code dead-macptr} - objects when writing them to an image - file. A {code dead-macptr} is functionally identical to - a {code macptr}, except that code that operates - on {code macptr} objects distinguishes them - from {code dead-macptr} objects and can handle them - appropriately-signaling errors, for example. - - Tthere is one exception to the conversion - of {code macptr} to {code dead-macptr} objects: - a {code macptr} object that points to the address 0 is not - converted, because address 0 can always be relied upon to refer to - the same thing." - - "The constant {code +null-ptr+} - refers to a {code macptr} object that points to address 0. - - On all supported platforms, you can - use {function save-application} to create a command-line - tool that runs very like any other command-line program - does. Alternatively, if you choose not to prepend the kernel, you - can save an image and then later run it by passing it as a - command-line parameter to the {code ccl} - or {code ccl64} script." - - (definition (:function save-application) - "save-application filename {code &key} toplevel-function init-file error-handler application-class clear-clos-caches (purify t) impurify (mode #o644) prepend-kernel native" - "Saves a heap image." - - (defsection "Description" - (listing :definition - (item "{param filename}" ccldoc::=> "The pathname of the file to be created when {CCL} - saves the application.") - (item "{param toplevel-function}" ccldoc::=> - (para "The function to be executed after startup is - complete. The toplevel is a function of no arguments that - performs whatever actions the lisp system should perform - when launched with this image.") - (para "If this parameter is not supplied, {CCL} uses its - default toplevel. The default toplevel runs - the " - (ref (glossentry "REPL") "read-eval-print loop") ".")) - (item "{param init-file}" ccldoc::=> "The pathname of a Lisp file to be loaded when the - image starts up. You can place initialization expressions in - this file, and use it to customize the behavior of the Lisp - system when it starts up.") - (item "{param error-handler}" ccldoc::=> "The error-handling mode for the saved image. The - supplied value determines what happens when an error is not - handled by the saved image. Valid values - are {code :quit} (Lisp exits with an error - message); {code :quit-quietly} (Lisp exits without an - error message); or {code :listener} (Lisp enters a - break loop, enabling you to debug the problem by interacting - in a listener). If you don't supply this parameter, the - saved image uses the default error handler - ({code :listener}).") - (item "{param application-class}" ccldoc::=> "The CLOS class that represents the saved Lisp - application. Normally you don't need to supply this - parameter; {function save-application} uses the - class {code ccl:lisp-development-system}. In some - cases you may choose to create a custom application class; - in that case, pass the name of the class as the value for - this parameter.") - (item "{param clear-clos-caches}" ccldoc::=> "If true, ensures that CLOS caches are emptied before - saving the image. Normally you don't need to supply this - parameter, but if for some reason you want to ensure the - CLOS caches are clear when the image starts up, you can pass - any true value.") - (item "{param purify}" ccldoc::=> " - When true, calls (in effect) {code purify} before - saving the heap image. This moves certain objects that - are unlikely to become garbage to a special memory area - that is not scanned by the GC (since it is expected that - the GC wouldn't find anything to collect). - ") - (item "{param impurify}" ccldoc::=> " - If true, calls (in effect) {code impurify} before - saving the heap image. (If both {code :impurify} - and {code :purify} are true, first - {code impurify} is done, and then {code purify}.) - - - {code impurify} moves objects in certain special memory - areas into the regular dynamic heap, where they will be scanned - by the GC. - ") - (item "{param mode}" ccldoc::=> " - A number specifying the mode (permission bits) of the output file. - ") - (item "{param prepend-kernel}" ccldoc::=> "Specifies the file to prepend to the saved heap - image. A value of {code t} means to prepend - the lisp kernel binary that the lisp started with. - Otherwise, the value of {code :prepend-kernel} - should be a pathname designator for the file to be - prepended. - - If the prepended file is execuatable, its execute - mode bits will be copied to the output file. - - This argument can be used to prepend any kind of file to - the saved heap image. This can be useful in some special - cases. - ") - (item "{param native}" ccldoc::=> "If true, saves the image as a native (ELF, Mach-O, PE) - shared library. (On platforms where this isn't yet supported, - a warning is issued and the option is ignored.) - ")))) - (para)) - - (defsection "Concatenating FASL Files" - (para "Multiple fasl files can be concatenated into a single file. - The single file might be easier to distribute or install, and - loading it may be slightly faster than loading the individual - files (since it avoids the overhead of opening and closing each - file in succession).") - - (definition (:function fasl-concatenate) "fasl-concatenate output-file fasl-files &key (:if-exists :error)" nil - "This function reads the fasl files specified by the list {param - fasl-files} and combines them into a single fasl file named - {param output-file}. The {code :if-exists} keyword argument is - interpreted as in the standard function {code open}. - - Loading the concatenated fasl file has the same effect as - loading the invidual input fasl files in the specified order." - - (para - "The {code pathname-type} of the output file and of each input - file defaults to the current platform's fasl file type (see " - (ref (table "Platform-specific filename conventions")) "). - If any of the input files has a different type an error will - be signaled, but {function fasl-concatenate} doesn't otherwise - try too hard to verify that the input files are real fasl files - for the current platform."))) - - (defsection "Floating Point Numbers" - "In {CCL}, the Common Lisp types short-float and single-float are - implemented as IEEE single precision values; double-float and - long-float are IEEE double precision values. On 64-bit - platforms, single-floats are immediate values (like fixnums and - characters). - - Floating-point exceptions are generally enabled and detected. By - default, threads start up with overflow, division-by-zero, and - invalid enabled, and the rounding mode is set to nearest. The - functions {function set-fpu-mode} and - {function get-fpu-mode} provide user control over - floating-point behavior." - - (definition (:function get-fpu-mode) "get-fpu-mode &optional mode" - "Return the state of exception-enable and rounding-mode control - flags for the current thread." - - "When called without the optional {param mode} argument, this - function returns a plist of keyword/value pairs which describe - the floating point exception-enable and rounding-mode flags for - the current thread. - - If {param mode} is supplied, it should be one of the keywords - {code :rounding-mode}, {code :overflow}, {code :underflow}, - {code :division-by-zero}, {code :invalid}, or {code :inexact}. - The value of corresponding control flag is returned." - - (listing :definition - (item "rounding-mode" ccldoc::=> "One of {code :nearest}, {code :zero}, -{code :positive}, or {code :negative}") - (item "overflow, underflow, division-by-zero, invalid, inexact" - ccldoc::=> " - If {code t}, the floating-point exception is signaled. - If {code nil}, it is masked. - "))) - - (definition (:function set-fpu-mode) - "set-fpu-mode {code &key} rounding-mode overflow underflow division-by-zero invalid inexact" "Set the state of exception-enable and rounding-mode control - flags for the current thread." - (defsection "Arguments and Values" - (listing :definition - (item "{param rounding-mode}" ccldoc::=> " - If supplied, must be one of :nearest, :zero, :positive, or - :negative. - ") - (item "{param overflow}, {param underflow}, {param division-by-zero}, {param invalid}, {param inexact}" - ccldoc::=> "NIL to mask the exception, T to signal it."))) - (defsection "Description" - (para " - Sets the current thread's exception-enable and rounding-mode - control flags to the indicated values for arguments that are - supplied, and preserves the values assoicated with those - that aren't supplied. - ")))) - - (defsection "Code Coverage" - (defsection "Overview" - (para " - In Clozure CL 1.4 and later, code coverage provides information - about which paths through generated code have been executed and - which haven't. For each source form, it can report one of three - possible outcomes: -") - (listing :bullet - (item " - Not covered: this form was never entered. - ") - (item " - Partly covered: This form was entered, and some parts were - executed and some weren't. - ") - (item " - Fully covered: Every bit of code generated from this form was - executed. - "))) - (defsection "Limitations" - " - While the information gathered for coverage of generated code is - complete and precise, the mapping back to source forms is of - necessity heuristic, and depends a great deal on the behavior of - macros and the path of the source forms through compiler - transforms. Source information is not recorded for variables, which - further limits the source mapping. In practice, there is often - enough information scattered about a partially covered function to - figure out which logical path through the code was taken and which - wasn't. If that doesn't work, you can try disassembling to see which - parts of the compiled code were not executed: in the disassembled - code there will be references to # where xxx - is NIL if the code that follows was never executed and non-NIL if it - was. - - - - Sometimes the situation can be improved by modifying macros to try - to preserve more of the input forms, rather than destructuring and - rebuilding them. -" - (para " - Because the code coverage information is associated with compiled - functions, code coverage information is not available for load-time toplevel - expressions. You can work around this by creating a function and calling - it. I.e. instead of - " - (code-block "(progn - (do-this) - (setq that ...) ...))") - "do: " - (code-block "(defun init-this-and-that () - (do-this) - (setq that ...) ...) -(init-this-and-that)") - " - -Then you can see the coverage information in the definition of -{code init-this-and-that}. -")) - - (defsection "Usage" - (para "In order to gather code coverage information, you first have to - recompile all your code to include code coverage - instrumentation. Compiling files will generate code coverage - instrumentation if {code ccl:*compile-code-coverage*} - is true: " - (code-block " -(setq ccl:*compile-code-coverage* t) -(recompile-all-your-files)")) - - "The compilation process will be many times slower than normal, and - the fasl files will be many times bigger. - - When you execute functions loaded from instrumented fasl files, they - will record coverage information every time they are executed. - You can examine that information by calling {code ccl:report-coverage} - or {code ccl:coverage-statistics}." - - (para "While recording coverage, you can collect incremental - coverage deltas between any two points in time. You might do this - while running a test suite, to record the coverage for each test, - for example: " - (code-block " -(ccl:reset-incremental-coverage) -(loop with coverage = (make-hash-table) - for test in (tests-to-run) - do (run-test test) - do (setf (gethash test coverage) (ccl:get-incremental-coverage)) - finally (return coverage))") - "creates a hash table mapping a test to a representation of all coverage recorded while running the - test. This hash table can then be passed to {code ccl:report-coverage}, {code ccl:incremental-coverage-svn-matches} - or {code ccl:incremental-coverage-source-matches}. -")) - (defsection "Functions and Variables" - (para " - The following functions can be used to manage the coverage data: -") - (definition (:function report-coverage) - "report-coverage output-file {code &key} (tags nil) (external-format :default) (statistics t) (html t)" - "Generate a code coverage report" - (defsection "Arguments and Values" - (listing :definition - (item "{param output-file}" ccldoc::=> " - Pathname for the output index file. - ") - (item "{param html}" ccldoc::=> " - If non-nil (the default), this will generate an HTML report, consisting of - an index file in {param output-file} and, in the same directory, - one html file for each instrumented source file that has been loaded in the - current session. - ") - (item "{param tags}" ccldoc::=> " - If non-nil, this should be a hash table mapping arbitrary keys (tags) to incremental coverage deltas. The - HTML report will show a list of tags, and allow selection of an arbitrary subset of them to show the - coloring and statistics for coverage by that subset. - ") - (item "{param external-format}" ccldoc::=> " - Controls the external format of the html files. - ") - (item "{param statistics}" ccldoc::=> - "If non-nil (the default), a comma-separated file is - generated with the summary of statistics. You can specify a - filename for the statistics argument, otherwise - {code statistics.csv} is created in the directory of {param output-file}. - See documentation of coverage-statistics below for a - description of the values in the statistics file."))) - (defsection "Example" - (para " - If you've loaded {system foo.lx64fsl} and - {system bar.lx64fsl}, and have run some tests, you could - do - " - (code-block "(report-coverage \"/my/dir/coverage/report.html\")") - " - and this would generate {system report.html}, - {system foo_lisp.html} and - {system bar_lisp.html}, and - {system statistics.csv} all in - {system /my/dir/coverage/}. - "))) - (definition (:function reset-coverage) "reset-coverage" - "Resets all coverage data back to the “Not Executed” state" - (defsection "Description" - (para "Resets all coverage data back to the “Not Executed” state"))) - - (definition (:function clear-coverage) "clear-coverage" "Forget about all instrumented files that have been loaded." - (defsection "Description" - (para "Gets rid of the information about which instrumented - files have been loaded, so {code ccl:report-coverage} will not - report any files, and {code ccl:save-coverage-in-file} will not - save any info, until more instrumented files are loaded."))) - (definition (:function save-coverage-in-file) "save-coverage-in-file pathname" " - Save all coverage into to a file so you can restore it later." - (defsection "Description" - (para " - Saves all coverage info in a file, so you can restore the - coverage state later. This allows you to combine multiple runs - or continue in a later session. Equivalent to - {code (ccl:write-coverage-to-file (ccl:get-coverage) pathname)}. - "))) - (definition (:function restore-coverage-from-file) "restore-coverage-from-file pathname" " - Load coverage state from a file. - " - (defsection "Description" - (para #:| - Restores the coverage data previously saved with - ccl:save-coverage-in-file, for the set of instrumented fasls - that were loaded both at save and restore time. I.e. coverage - info is only restored for files that have been loaded in this - session. For example if in a previous session you had loaded - {system "foo.lx86fsl"} and then saved the coverage info, in this session - you must load the same {system "foo.lx86fsl"} before calling - {code restore-coverage-from-file} in order to retrieve the stored - coverage info for "foo". Equivalent to {code (ccl:restore-coverage - (ccl:read-coverage-from-file pathname))}. - |))) - (definition (:function get-coverage) "GET-COVERAGE" " - Returns a snapshot of the current coverage data. - " - (defsection "Description" - (para " - Returns a snapshot of the current coverage data. A snapshot is a - copy of the current coverage state. It can be saved in a file - with {code ccl:write-coverage-to-file}, reinstated back as the current - state with {code ccl:restore-coverage}, or combined with other - snapshots with {code ccl:combine-coverage}. - "))) - (definition (:function restore-coverage) "restore-coverage snapshot" " - Reinstalls a coverage snapshot as the current coverage state. - " - (defsection "Description" - (para " - Reinstalls a coverage snapshot as the current coverage state. - "))) - (definition (:function combine-coverage) "combine-coverage snapshots" " - Combines multiple coverage snapshots into one. - " - (defsection "Description" - (para " - Takes a list of coverage snapshots and returns a new coverage snapshot - representing a union of all the coverage data. - "))) - (definition (:function write-coverage-to-file) "write-coverage-to-file snapshot pathname" " - Save a coverage snapshot in a file. - " - (defsection "Description" - (para " - Saves the coverage snapshot in a file. The snapshot can be - loaded back with {code ccl:read-coverage-from-file} or loaded and - restored with {code ccl:restore-coverage-from-file}. Note that the file - created is actually a lisp source file and can be compiled for - faster loading. - "))) - (definition (:function read-coverage-from-file) "read-coverage-from-file pathname" " - Return the coverage snapshot saved in a file. - " - (defsection "Description" - (para " - Returns the snapshot saved in pathname. Doesn't affect the - current coverage state. pathname can be the file previously - created with {code ccl:write-coverage-to-file} or - {code ccl:save-coverage-in-file}, or it can be the name of the fasl - created from compiling such a file. - "))) - (definition (:function coverage-statistics) "coverage-statistics" - (clause " - Returns a sequence of {code ccl:coverage-statistics} objects, one per source file. - ") - (defsection "Description" - (para " - Returns a sequence of {code ccl:coverage-statistics} objects, one for each - source file, containing the same information as that written to - the statistics file by {function report-coverage}. The following - accessors are defined for {code ccl:coverage-statistics} objects: - " - (listing :definition - (item "{function coverage-source-file}" ccldoc::=> " - the name of the source file corresponding to this information - ") - (item "{function coverage-expressions-total}" ccldoc::=> " - the total number of expressions - ") - (item "{function coverage-expressions-entered}" ccldoc::=> " - the number of source expressions that have been entered - (i.e. at least partially covered) - ") - (item "{function coverage-expressions-covered}" ccldoc::=> " - the number of source expressions that were fully covered - ") - (item "{function coverage-unreached-branches}" ccldoc::=> " - the number of conditionals with one branch taken and one not taken - ") - (item "{function coverage-code-forms-total}" ccldoc::=> " - the total number of code forms. A code form is an - expression in the final stage of compilation, after all - macroexpansion and compiler transforms and simplification - ") - (item "{function coverage-code-forms-covered}" ccldoc::=> " - the number of code forms that have been entered - ") - (item "{function coverage-functions-total}" ccldoc::=> " - the total number of functions - ") - (item "{function coverage-functions-fully-covered}" ccldoc::=> " - the number of functions that were fully covered - ") - (item "{function coverage-functions-partly-covered}" ccldoc::=> " - the number of functions that were partly covered - ") - (item "{function coverage-functions-not-entered}" ccldoc::=> " - the number of functions never entered - "))))) - (definition (:function reset-incremental-coverage) "reset-incremental-coverage" " - Reset incremental coverage. - " - (defsection "Description" - (para " - Marks a starting point for recording incremental coverage. - Note that calling - this function does not affect regular coverage data (whereas calling - {code ccl:reset-coverage} resets incremental coverage as well). - "))) - (definition (:function get-incremental-coverage) "get-incremental-coverage {code &key} (reset t)" " - Returns the delta of coverage since the last incremental reset. - " - (defsection "Description" - " - Returns the delta of coverage since the last reset of incremental coverage. - If {code reset} is true (the default), it also resets incremental coverage - now, so that the next call to {code get-incremental-coverage} will return - the delta from this point. - - - - Incremental coverage deltas are represented differently than the full coverage snapshots - returned by functions such as {code ccl:get-coverage}. Incremental - coverage uses an abbreviated format - and is missing some of the information in a full snapshot, and therefore cannot be passed to - functions documented to accept a {param snapshot}, only to functions - specifically documented to accept incremental coverage deltas. - ")) - (definition (:function incremental-coverage-source-matches) - "incremental-coverage-source-matches collection sources" " - Find incremental coverage deltas intersecting source regions. - " - (defsection "Arguments and Values" - (listing :definition - (item "{param collection}" ccldoc::=> " - A hash table mapping arbitrary keys to incremental coverage deltas, or a sequence of - incremental coverage deltas. - ") - (item "{param sources}" ccldoc::=> " - A list of pathnames and/or source-notes, the latter representing a range within a file. - "))) - (defsection "Description" - " - Given a hash table {code collection} whose values are incremental coverage - deltas, return a list of all keys corresponding to those deltas that intersect any region - in {code sources}. - - - - For example if the deltas represent tests, then the returned value is a list of all tests - that cover some part of the source regions. - - - {code collection} can also be a sequence of deltas, in which case a subsequence - of matching deltas is returned. In particular you can test whether any particular delta - intersects the sources by passing it in as a single-element list. - ")) - (definition (:function incremental-coverage-svn-matches) - "incremental-coverage-svn-matches collection {code &key} (directory (current-directory)) (revision :base)" " - Find incremental coverage deltas matching changes from a particular subversion revision. - " - (defsection "Arguments and Values" - (listing :definition - (item "{param collection}" ccldoc::=> " - A hash table mapping arbitrary keys to incremental coverage deltas, or a sequence of - incremental coverage deltas. - ") - (item "{param directory}" ccldoc::=> " - The pathname of a subversion working directory. - ") - (item "{param revision}" ccldoc::=> " - The revision to compare to the working directory, an integer or another - value whose printed representation is suitable for passing as the - {code --revision} argument - to {system svn}. - "))) - (defsection "Description" - " - Given a hash table {code collection} whose values are incremental coverage - deltas, return a list of all keys corresponding to those deltas that intersect any changed - source in {code directory} since revision {code revision} in subversion. - - - - For example if the deltas represent tests, then the returned value is a list of all tests - that might be affected by the changes. - - - {code collection} can also be a sequence of deltas, in which case a subsequence - of matching deltas is returned. In particular you can test whether any particular delta - is affected by the changes by passing it in as a single-element list. - ")) - (definition (:variable *compile-code-coverage*) "*compile-code-coverage*" " - When true, instrument functions being compiled to collect code coverage information. - " - (defsection "Description" - (para " - This variable controls whether functions are instrumented for - code coverage. Files compiled while this variable is true will - contain code coverage instrumentation. - "))) - (definition (:macro without-compiling-code-coverage) "without-compiling-code-coverage" " - Don't record code coverage for forms within the body. - " - (defsection "Description" - (para " - This macro arranges so that body doesn't record internal details - of code coverage. It will be considered totally covered if it's - entered at all. The Common Lisp macros {code ASSERT} and {code CHECK-TYPE} use - this macro. - ")))) - (defsection "Interpreting Code Coloring" - (para " - - The output of ccl:report-coverage consists of formatted source code, with coverage indicated by - coloring. Four colors are used: dark green for forms that compiled to code in which every single - instruction was executed, light green for forms that have been entered but weren't totally covered, red - for forms that were never entered, and the page background color for toplevel forms that weren't - instrumented. - -") - (para " - The source coloring is applied from outside in. So for example if you have - - " - (code-block " -(outer-form ... (inner-form ...) ...) - ") - " - - first the whole outer form is painted with whatever color expresses the outer form coverage, and then the - inner form color is replaced with whatever color expresses the inner form coverage. One consequence of - this approach is that every part of the outer form that is not specifically inside some executable inner - form will have the outer form's coverage color. If the syntax of outer form involves some non-executable - forms, or forms that do not have coverage info of their own for whatever reason, then they will just - inherit the color of the outer form, because they don't get repainted with a color of their own. -") - (para " - One case in which this approach can be confusing is in the case of symbols. As noted in the Limitations - section, coverage information is not recorded for variables; hence the coloring of a variable does not - convey information about whether the variable was evaluated or not -- that information is not available, - and the variable just inherits the color of the form that contains it. -"))) - (defsection "Other Extensions" - - - - (definition (:macro unwind-protect) "unwind-protect protected-form {lbrace}cleanup-form{rbrace}*" " - Ensure cleanup-forms are executed. - " - (defsection "Summary" - (para " - In {CCL}, the cleanup forms are always executed as if they were - wrapped with " - (ref (definition :macro without-interrupts)) ". - To allow interrupts, use - " - (ref (definition :macro with-interrupts-enabled)) ". - "))) - -)) diff --git a/ccl-documentation/ccl.css b/ccl.css similarity index 100% rename from ccl-documentation/ccl.css rename to ccl.css diff --git a/ccl-documentation/defun.tex b/defun.tex similarity index 100% rename from ccl-documentation/defun.tex rename to defun.tex diff --git a/source/ccldoc.asd b/source/ccldoc.asd index c245521..d9195ce 100644 --- a/source/ccldoc.asd +++ b/source/ccldoc.asd @@ -26,4 +26,5 @@ (:file "output-docbook") (:file "output-tracwiki") (:file "output-html") + (:file "output-latex") (:file "output-ccldoc"))) diff --git a/source/output-html.lisp b/source/output-html.lisp index bce93b2..ae009fd 100644 --- a/source/output-html.lisp +++ b/source/output-html.lisp @@ -1,6 +1,7 @@ (in-package :ccldoc) -(defun output-html (doc filename &key external-format (if-exists :supersede)) +(defun output-html (doc filename &key external-format (if-exists :supersede) + style) (with-open-file (s filename :direction :output :if-exists if-exists :external-format external-format) (format s "~%") diff --git a/source/output-latex.lisp b/source/output-latex.lisp index 11f0946..adccaae 100644 --- a/source/output-latex.lisp +++ b/source/output-latex.lisp @@ -94,13 +94,15 @@ (not (typep (ancestor-of-type clause 'named-clause) 'definition))) (format stream "\\label{~a}~%" (clause-external-id clause)))) -(defmethod write-latex ((clause index-section) stream)) +(defmethod write-latex ((clause index-section) stream) + (declare (ignore stream))) (defmethod write-latex ((clause indexed-clause) stream) (write-latex (clause-body clause) stream) (format stream "\\index{~a} " (clause-body clause))) -(defmethod write-latex ((clause glossary-section) stream)) +(defmethod write-latex ((clause glossary-section) stream) + (declare (ignore stream))) (defmethod write-latex ((clause glossentry) stream) (write-latex (clause-body clause) stream) @@ -152,7 +154,8 @@ (write-latex (clause-body clause) stream) (format stream "~&~%")) -(defmethod write-latex ((clause docerror) stream)) +(defmethod write-latex ((clause docerror) stream) + (declare (ignore stream))) (defmethod write-latex ((clause link) stream) (format stream "\\href{~a}" (link-url clause))