The Nearly Complete Scheme48 1.3 Reference Manual Taylor Campbell First Edition This manual is for Scheme48 version 1.3. Copyright c 2004, 2005, 2006 Taylor Campbell. All rights reserved. This manual includes material derived from works bearing the following notice: Copyright c 1993-2005 Richard Kelsey, Jonathan Rees, and Mike Sperber. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. The name of the authors may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE AUTHORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. i Table of Contents 1 Introduction ............................... 1 1.1 This manual ............................................ 1 1.2 Acknowledgements ...................................... 2 2 User environment .......................... 3 2.1 Running Scheme48 ...................................... 3 2.1.1 Command processor introduction ................ 4 2.2 Emacs integration ....................................... 5 2.3 Using the module system ................................ 7 2.3.1 Configuration mutation ......................... 8 2.3.2 Listing interfaces ............................... 9 2.4 Command processor .................................... 10 2.4.1 Basic commands............................... 10 2.4.2 Switches ...................................... 11 2.4.3 Emacs integration commands ................... 12 2.4.4 Focus value ................................... 12 2.4.5 Command levels ............................... 13 2.4.6 Module commands............................. 15 2.4.7 SRFI 7 ....................................... 16 2.4.8 Debugging commands .......................... 16 2.4.9 Inspector ..................................... 18 2.4.10 Command programs .......................... 19 2.4.11 Image-building commands ..................... 20 2.4.12 Resource statistics and control................. 20 3 Module system ........................... 23 3.1 Module system architecture ............................. 23 3.2 Module configuration language .......................... 24 3.3 Macros in concert with modules ......................... 28 3.4 Static type system ..................................... 30 3.4.1 Types in the configuration language ............. 33 4 System facilities .......................... 35 4.1 System features ........................................ 35 4.1.1 Miscellaneous features ......................... 35 4.1.2 Various utilities ............................... 36 4.1.3 Filenames ..................................... 39 4.1.3.1 Filename translations.................. 40 4.1.4 Fluid/dynamic bindings ........................ 41 4.1.5 ASCII character encoding ...................... 43 4.1.6 Integer enumerations........................... 43 4.1.7 Cells.......................................... 45 ii 4.1.8 Queues ....................................... 45 4.1.9 Hash tables ................................... 46 4.1.10 Weak references .............................. 47 4.1.10.1 Weak pointers ....................... 47 4.1.10.2 Populations (weak sets) .............. 48 4.1.11 Type annotations ............................. 48 4.1.12 Explicit renaming macros ..................... 48 4.2 Condition system ...................................... 51 4.2.1 Signalling, handling, and representing conditions ................................................ 52 4.2.2 Displaying conditions .......................... 55 4.3 Bitwise manipulation ................................... 55 4.3.1 Bitwise integer operations ...................... 56 4.3.2 Byte vectors................................... 56 4.4 Generic dispatch system ................................ 56 4.5 I/O system ............................................ 58 4.5.1 Ports ......................................... 58 4.5.1.1 Port operations ....................... 58 4.5.1.2 Current ports ......................... 59 4.5.2 Programmatic ports ........................... 60 4.5.2.1 Port data type ........................ 60 4.5.2.2 Port handlers ......................... 62 4.5.2.3 Buffered ports & handlers ............. 64 4.5.3 Miscellaneous I/O internals..................... 66 4.5.4 Channels...................................... 66 4.5.4.1 Low-level channel operations ........... 67 4.5.4.2 Higher-level channel operations......... 68 4.5.5 Channel ports ................................. 69 4.6 Reader & writer........................................ 70 4.6.1 Reader........................................ 70 4.6.2 Writer ........................................ 71 4.6.2.1 Object disclosure...................... 72 4.7 Records ............................................... 73 4.7.1 Jonathan Rees’s define-record-type macro .... 73 4.7.2 Richard Kelsey’s define-record-type macro.... 74 4.7.3 Record types .................................. 75 4.7.4 Low-level record manipulation .................. 76 4.8 Suspending and resuming heap images ................... 77 4.8.1 System initialization ........................... 77 4.8.2 Manual system initialization .................... 78 iii 5 Multithreading ........................... 79 5.1 Basic thread operations ................................. 79 5.2 Optimistic concurrency ................................. 79 5.2.1 High-level optimistic concurrency ............... 80 5.2.2 Logging variants of Scheme procedures .......... 81 5.2.3 Synchronized records........................... 81 5.2.4 Optimistic concurrency example ................ 82 5.2.5 Low-level optimistic concurrency ................ 84 5.3 Higher-level synchronization............................. 85 5.3.1 Condition variables ............................ 85 5.3.2 Placeholders................................... 86 5.3.3 Value pipes ................................... 86 5.4 Concurrent ML ........................................ 87 5.4.1 Rendezvous concepts........................... 87 5.4.2 Delayed rendezvous ............................ 88 5.4.2.1 Negative acknowledgements ............ 88 5.4.3 Rendezvous combinators ....................... 88 5.4.3.1 Timing rendezvous .................... 89 5.4.4 Rendezvous communication channels ............ 90 5.4.4.1 Synchronous channels ................. 90 5.4.4.2 Asynchronous channels ................ 90 5.4.5 Rendezvous-synchronized cells .................. 91 5.4.5.1 Placeholders: single-assignment cells .... 91 5.4.5.2 Jars: multiple-assignment cells ......... 92 5.4.6 Concurrent ML to Scheme correspondence ....... 92 5.5 Pessimistic concurrency ................................. 94 5.6 Custom thread synchronization.......................... 94 6 Libraries ................................. 97 6.1 Boxed bitwise-integer masks............................. 97 6.1.1 Mask types.................................... 97 6.1.2 Masks ........................................ 97 6.2 Enumerated/finite types and sets ........................ 98 6.2.1 Enumerated/finite types ....................... 98 6.2.2 Sets over enumerated types.................... 100 6.3 Macros for writing loops ............................... 101 6.3.1 Main looping macros.......................... 101 6.3.2 Sequence types ............................... 102 6.3.3 Synchronous sequences ........................ 103 6.3.4 Examples .................................... 104 6.3.5 Defining sequence types ....................... 105 6.3.6 Loop macro expansion ........................ 105 6.4 Library data structures ................................ 106 6.4.1 Multi-dimensional arrays ...................... 106 6.4.2 Red/black search trees ........................ 107 6.4.3 Sparse vectors ................................ 108 6.5 I/O extensions ........................................ 108 6.6 TCP & UDP sockets .................................. 109 iv 6.6.1 TCP sockets ................................. 109 6.6.2 UDP sockets ................................. 110 6.7 Common-Lisp-style formatting ......................... 110 6.8 Library utilities ....................................... 112 6.8.1 Destructuring ................................ 112 6.8.2 Pretty-printing ............................... 112 6.8.3 Strongly connected graph components .......... 113 6.8.4 Nondeterminism .............................. 113 6.8.5 Miscellaneous utilities ......................... 113 6.8.6 Multiple value binding ........................ 115 6.8.7 Object dumper ............................... 116 6.8.8 Simple time access ...........................