Aa!:|  HH $ d H6$$ff@  d#  Footnote TableFootnote**. . / - :;,.!?3`p9aTOCHeading.AlpernBaderC's CritchlowDemasDylanGwydionHaible Implementors InstantiableRatnerRogoffShen Strassman accessorsbytecharacterdo(rcurry(checkdsteltentrancyeof filestreamfilename forceoutput getinputinputavailablelimited(sunicodeunion(   ?   @   A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   S    T    U    V    W    X    Y   Z   [   \   ]   ^   _   `   a   b   c   d   e   f   g   h   *.   )/   +0   R1   S2   T3   U4   V5  W6  d:   |?   }@   C   D   F    G    H    I    J    K    L    M    N    O   ( [  Hello, World \ "41728: 1Heading: 4. Multiple Files ]  Return Codes ` C19995: 1Heading: 6. Command Line Switches and Environment Variables a  Command Line Switches b  Environment Variables e  BYTES_CONSED_BETWEEN_GCS k  Syntax Errors l  Runtime ErrorsF m Warnings n  Dylan vs. Mindy o Mindy vs. Dylan p  for loop extensions r load t  Debugger Customizations s  keyword default syntax u .20437: 2Heading: 11.2. Debugger Customizations w Debugger-format module x  fd-open z *debug-output*[debug-output] }  macrosg ~ limited collections   collections, limited  sealing open  primary  next-method  #next[next] /31798: 1Heading: 9. Using Libraries and Modules  MINDYPATH Extensions Module  main  one-of ,load +15429: 2Heading: 10.4. Exiting Applications non-exit 9 Weak Pointers6Co i\[weak-pointer]le  weak-pointer-objecti &41731: 1Heading: 12. The System Module  _ System ModuleG  &*print-GC-messages*[print-GC-messages]rs  collect-garbage ypurifynd  getcwdy  aIntrospection Module n abstract?lo  class-name C a$\[slot-descriptor]  slot-descriptors . slot-nameuom sslot-allocationu a slot-type x  d slot-getter g slot-setterg  slot-valueos  slot-value-settercon  init-keyword tkeyword-required?n( File-descriptor Module) fd-exect+  fd-close, fd-read- efd-write. rfd-input-available? / Ifd-sync-output0 sfd-seekl1  fd-error-string2 fSEEK_SET3 SEEK_CUR4 eSEEK_END5 gO_RDONLY6  O_WRONLY7  O_RDWR P8 6O_APPEND9 kO_CREAT>: nO_TRUNC ; eO_EXCL-o< ENOENT41= eEIO:> SENXIOole?  EACCESem@ GEFAULT A tEEXISTesB -ENOTDIReC  EISDIRecD gEINVALyE yENFILE F dEMFILEaG sENOSPCduH  EROFSbraI o ENAMETOOLONGJ CEBADFa\[thread]tZ  r spawn-thread[  kill-threadp\ ecurrent-threadxe]  \[lock] ^ d\[spinlock]_ r\[multilock]`  d\[semaphore]a  locked?b  s grab-lock fc  S grab-lockSEd   release-locke   \[event]f  _wait-for-eventO_g  P signal-eventh   broadcast-event . _unicode / _ Copyright  0 T Bug reports 1 2 oSection The Extensions ModuleGEF 3  Section The Extensions ModuleNDI 4 *34437: 1Heading: 11. The Extensions ModuleEN : 325560: 1Heading: 8. Dylan vs. Mindy Language IssuesF  8METLO @CEB ?  = 9 R\^3  I+15429: 2Heading: 10.4. Exiting Applications ^3  I"41728: 1Heading: 4. Multiple Files ^3  Ig&41731: 1Heading: 12. The System Module ^3 Ie/31798: 1Heading: 9. Using Libraries and Modules-^3 ! Fut.20437: 2Heading: 11.2. Debugger Customizations[l^3 " I<*34437: 1Heading: 11. The Extensions Modulelt^3= # I<*34437: 1Heading: 11. The Extensions Modules^3 $ Iu 510528: 1Heading: 9. Extensions to the Streams Libraryv>[^3 % Kua"37402: Heading: Gwydion Extensions ^3 & Kun"37402: Heading: Gwydion Extensionst ^3= ' Ie/31798: 1Heading: 9. Using Libraries and Moduless^3H ( Kve"22222: Heading: The Mindy Debugger34^3= ) IT&41731: 1Heading: 12. The System Modulein^3= *  Id*34437: 1Heading: 11. The Extensions Module^3= +  I "41728: 1Heading: 4. Multiple Files 2^3= ,  Ii"41728: 1Heading: 4. Multiple Files"^3= -  I "41728: 1Heading: 4. Multiple Files&^3= .  I./31798: 1Heading: 9. Using Libraries and Modules9^3H /  Kvi"22222: Heading: The Mindy Debuggert^3 0  Ku:"37402: Heading: Gwydion Extensions ^3 1  Ku3"37402: Heading: Gwydion Extensionslt^3Y 2 Kw<#42007: Heading: The Streams Library ^3 3 Ku "37402: Heading: Gwydion Extensions t^3Y 4 Lwr#42007: Heading: The Streams LibraryH^3 5 Lxo!11977: Heading: The Print Library:di^3(L6 Lyo"17863: Heading: The Format Libraryad^3 7  Kur"37402: Heading: Gwydion Extensions"^3(L8  Ky "17863: Heading: The Format Library5UM 15<$lastpagenum>6*<$daynum01> <$shortmonthname> <$shortyear>7"<$monthnum>/<$daynum>/<$shortyear>8)<$daynum> <$shortmonthname> <$shortyear> 9"<$monthnum>/<$daynum>/<$shortyear>:<$monthname> <$daynum>, <$year> ";"<$monthnum>/<$daynum>/<$shortyear>< <$fullfilename>9 1= <$filename>iar> <$paratext[Title]>? <$paratext[Heading]>: @ <$curpagenum>A <$marker1>B <$marker2>C (Continued) D+ (Sheet <$tblsheetnum> of <$tblsheetcount>)eioEPagepage<$pagenum><#FHeading & Page <$paratext> on page<$pagenum>GSee Heading & Page%See <$paratext> on page<$pagenum>.rH Table & Page7Table<$paranumonly>, <$paratext>, on page<$pagenum>HdiIHeading section <$paratext>JFunctionfunction <$paratext>KDocument"the document <$paratext>LRaw<$paratext>7uzulibrariesextensions.fmv debug.fm>wlibrariesstreams.fmmexlibrariesprint.fmylibrariesformat.fm) Y 3 um) * + , - Area. A1 / 0 1 Agum2 A l l od) t  u<$ nio $p He ear ppa  He1 e<  eE H abl o< ge H1. ! tmp a i sar  u' r si) t- u2. r. oS b3 >ieZ .5 rc>6 c>7 >.f8 m3. 9 : ; 4. l = > ? @ C 5.  / 6. 0   gZ U  1 o9 = u<$: nio; < Q ear p7.1. D eE <F G H lJ <7.2. K L tQ a 7.3.  sar  u r  t u2.  } 7.4. T V 8. w >X fY .Z  7.  . 11.4.  S a d n 7.5.  o! 6." #  13.1. $  %  &  '  ( ( ) * ) + * , f- h. / 0 1 j2 k3 l4 05 n6  9. o7 8 9 .: ; < = > ? @ A B C 4.D E + F >, G f- H .. I EJ {K |L ~M  10. N O P Q R S T U V 1W X Y Z [ \  11. \ ] I^  11.1. ;_ 0 ` a a 2 b f c ed e f 0g 1h  ,i k j q k .qm 17. tn ; s t < u v w = x I y J z K { ~       ; @  A B C D E   11.2.  { 1| } ~     11.3.  .1         +  12. , : ; .< 17= > ? @ A B C  D E F G H  I !J "K #L $M %N e  13. r s ;t <u =v >w ?x @y  1       3             h i .x 17y z { | } ~ j k l m n o p q r s t u v 13w !                                     14.                  13           ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 148 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g h i j k l m n o p q r  s  t  u v @w 15. L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g         16.  D 16.1. ?                                                !    "  # $ 6  .1 %  & '    (  ) *     + ! , - " # $ . % / 0 & ' ( 1 ) 2 3 * + , 4 - 5 6 . / 0 7 1 8 9 : ; 2 3 4 5 < 6 = > 7 8 9 ? : @ A ; < = B > C E! 16.2. F" G# H$ I% J& K' L( M) N* O+ P, Q- R. ir ds kt 18. lu mv nw ox py qz { A`dAdBH$ CA H$ UUd  Hw DA Hw  UUd  H$ EA H$ UUd  Hw FA Hw N* UUd  HH GA HH 18UUd  HH HA HH `UUd  l" IB l" $UUn  U30 May 97  V H JB H wUUn ! ZRunning H/F 2 Y W# X $HKB $H  UUd  dLMX H#* MNL H#* HR HR FootnoteHr7 NMOL Hr7 HzHz Single LineH'ONQLPPFootnote  PO    HR< QORL HR< HH Double LineH RQULST Double Line$STRH&TSRH URWLW VV Single Line)VUHZWUXL TableFootnoteϸE]G'E XWL ϸE]G'E ϸEwPϸEwP TableFootnoteodYHz$HZY $H(( (TU TU ` #The Mindy Compiler and Interpreter *UU ( HcCopyright (c) 1994, 1995, 1996, 1997 Carnegie Mellon University All rights reserved. Refer to the 6UU@( 0end of this document for precise terms of use. DoVUU`& wThe Gwydion Project would like to thank those on the net that have contributed code patches and bug reports for Mindy: lUU  lAdam Alpern, Steve Strassman, Scott Collins, Ed Gamble, Bruno Haible, John Shen, Galen Hunt, Richard Lynch, inxUU eDan Ratner, Court Demas, Miles Bader, Kelly Murray, Nick Thompson, Brent Benson, Brian Rogoff, Alain UU jRogister, Mark Chu-Carroll, Enrico Colombini, Dave Dyer, Jonathan Bachrach, Michael Binz, Jonathan Sobel, UU@ TaKEric Kidd, John Shen, Carl Gay, Patrick Premont, Eric Gouriou, Kim Barrett UU` HzSpecial thanks for major efforts to Roger Critchlow, Patrick Beard, Gary Palter, and Jim Studt for enhancements to Mindy. JUTU ` Th Introduction rUU  Mindy is an implementation of a language that is very much like the language described in the DylanTM Reference Manual ( UU do}(DRM). Mindy was named for Mindy Is Not Dylan Yet, and it still is and will probably always remain a Dylan subset, nUU hepprimarily because mindycomp doesnt do enough semantic analysis to implement macros or to implement the precise o UU  Gysemantics of Dylan naming. Now that the d2c Dylan-to-C compiler is available (see web documentation), debugged Dylan B UU@ f,aapplications will normally be compiled for better performance. Mindy remains useful because: h"UU  , aMindy provides a better debugging environment when its performance can be tolerated, since Mindy ,.UU@ =has a source-level debugger and vastly faster compile times. t=UU` rdOMindy is more portable, so can be used on machines where d2c is not supported. rodIUU`  _UU  imsMindy was developed by the Gwydion Project at Carnegie Mellon University for our own internal use as a development kUU  {tool while we work on our real high-performance Dylan implementation. We have decided to make Mindy available for bsewUU  uother people who want to learn about Dylan. However, the amount of effort that we can put into maintaining Mindy is UU@  Gstrictly limited. UU  hawMindy will never be an industrial-strength implementation, and nobody should depend on it for real work. We will make ll UU edxfuture releases from time to time as we add new features and fix bugs, but this is strictly a sideshow for us. We would nmUU rmyappreciate receiving bug reports (especially those accompanied by code patches) and suggestions for improvements, but we UU@ MiEmay not fix every bug reported in a timely manner, or fix it at all. rUU  rMindy comprises two C programs, a compiler that produces byte-codes and a byte-code interpreter. Instructions for UU  acompiling and installing Mindy can be found in the file INSTALL at the top level of the Mindy release. Instructions for edUU@ ilqobtaining the different versions of Mindy can be found in the file README at the top level of the Mindy release. e4U TU h ta [Hello, World !UU  stWell, the first program anyone should endeavor to write in a new language is, of course, Hello World. Type this into a file l-UU@ ke!called hw-exports.dylan: lCUU`  tModule: dylan-user rOUU`y ut i[UU` dedefine library hello-world gUU`) ecuse Dylan; g rsUU`+  tend library; by UU`k su sUU`, endefine module hello-world Mid[yan$H\[ sa $H b**e interpti*UU`F  ause dylan; nstUU`G e use cheap-io; UU`H heuse extensions; y *UU`I onend module; 6UU`z in BUU`{ io&And put this in hw.dylan: XUU`` elmodule: Hello-World dUU`c ta pUU`b !2// This is the canonical ``hello, world'' demo. |UU`s it;define method main (argv0 :: , #rest noise) thUU`u -puts("Hello, World.\n"); -UU`x  lend; UUU` :  aUU` MTo compile your program invoke $INSTALL/bin/mindycomp, for example: UU` n;<% $INSTALL/bin/mindycomp -lhello-world hw-exports.dylan suUU`] , 4% $INSTALL/bin/mindycomp -lhello-world hw.dylan UU  This produces files named hw.dbc and hw-exports.dbc. The .dbc stands for Dylan Byte Code. To run the program, nUU@ tisay: UU`  a5% $INSTALL/bin/mindy -f hw-exports.dbc -f hw.dbc -UU` H JIt should print "Hello, World." to standard output and then exit. UU j zNote that even the minimal Dylan program has at least two files. This is because in order to do anything much at all, you *UUj zmust access additional libraries, and the only way to set up your namespace is to define your own library and module. But 6UU@j mthe only way to place code in a module is to use the Module: file header, so two files are required. LUU` ouSNote also that a blank line is required after the Module: file header.  big.dbc yopUU@ gg% mindy -f big.dbc tio|UU   Under Microsoft Windows, many implementations of cat will corrupt .dbc files because they perform newline translation. ow UU@  reGFor this reason, under MS-Windows, we recommend using dbclink: pled ] nd-f$H!^] $Hfi''-fth'UU  le2% dbclink big.dbc cat foo.dbc bar.dbc baz.dbc UU@ t % mindy -f big.dbc modRU3TU h io ]Return Codes eHUU   N|If Mindy encounters an unrecoverable error, or if Mindy is exited via the debugger quit command, Mindy exits with a ntTUU  vereturn code of 1. If the Dylan program ends with a call to exit() and a return code is specified (see  ^section Exiting Applications`UUJ r.K _), Mindy exits with that return code. Otherwise, the return code is 0. MUTU h r < ` aCommand Line Switches and  bEnvironment Variables rrUU` il:Mindycomp recognizes the following command line switches: UU   r~-Dfeature : This tells the conditional compilation system that feature is present (ie, define). Notice that UU@ $rthere is no space between -D and feature. (See libraries/extensions.txt for more details) UU  -Ufeature : This tells the conditional compilation system that feature is not present (ie, undefine). Notice  UU@ Hwthat there is no space between -U and feature. (See libraries/extensions.txt for more details) , MUU` nt UU` re6Mindy recognizes the following command line switches: UUj rnr-f filename : This tells Mindy to load file filename. See  csection Multiple Files d. UU   t-x filename : This tells Mindy to load file filename like -f does, but the rest of the command line is then yc&UU@  feleft uninterpretted by Mindy. This can be useful if your Dylan program also has a -f option. m2UU` at 햪HUU` es6Mindy recognizes the following environment variables: ^UU( twi eBYTES_CONSED_BETWEEN_GCS : This is the number of bytes Mindy will allocate before invoking a gar jUU efbage collection. For maximum speed, this should be set to the largest value possible that wont cause vUUJ zthrashing. See also collect-garbage and *print-GC-messages* in  fsection The System Module g. UU* vDYLANPATH: This controls where Mindy searches for Dylan libraries. See  isection Using Libraries and ModulesUUJ is j. UU  aDYLANDIR: This provides a way to inform a precompiled Gwydion Dylan binary distribution where it ۏUU@ dy`has been installed. All Mindy uses this variable for is to determine the default for DYLANPATH. &8UTU ` leErrors and Warnings inh ef kSyntax Errors UU  If there are any syntax errors in your program, mindycomp will report them to stderr while compiling. For example, if  UU@ NSzyou had left off the closing parenthesis in the call to puts in the above example, mindycomp would have reported: UU`  s-hw.dylan:4: parse error at or before `;' o+UU  ca~Because the line introduction, hw.dylan:4:, has the same format that the C compiler uses, gnu-emacs's compile package 7UU@ . -can parse the error messages from mindycomp. oMUU  rc}Mindycomp's error recovery is not the best in the world. Often, it has to completely punt, telling you only about the first DYUU@ a Efew errors it found. You have to fix what it reports and try again. ۅoUU  dyA hint to getting slightly tighter error recovery is to end all method and class definitions with end method; or end ar{UU class;. For example, if you forget an end token for a statement inside a method definition, the mindycomp parser goes deUU liall the way to the end of the file and then reports a syntax error at the EOF position. You do not get any more clues. If you amUU lduse end method;, then the parser can recover at the end of the method containing the bad syntax and reports the syntax td"_athu-ac$H#`_ apa$H f))UU  p')uUU@ e \error there. This gives you a lot tighter recovery and more information in this situation. Qh er lRuntime Errors aveeUU  poqMuch more common than syntax errors are runtime errors. And given the simplistic model of compilation mindycomp dqUU  wxuses, most semantic errors are not detected until runtime. When Mindy hits a runtime error that is not handled via the n }UU si}condition system, it drops you into a debugger. From this debugger you can look at variables, examine the stack, and invoke UU e functions. For example, if you had assumed that puts would be named something more reasonable, like put-string, you UU@ hoXwould have gotten the following when you tried to run your Hello World program: UU  % mindy -f hw.dbc UU  UU pa4Warning: the following variables are undefined:  UU in library Dylan-user: UU  yin module Dylan-user: UU th'put-string[hw.dylan, line 9] RuUU e UU  mthread [0] D main or UU rs@fp 0x1003009c: invoke-debugger({ 0x101a24c9}) UU@ , mindy> er#UU  teTyping help at the mindy> prompt will list the various commands you can use. See the document debug.ps for more /UU@ is information. aJh s,  mWarnings a^UU` 0Mindycomp issues warnings at compile time when: hatUU` peWhile or until is used inside a for loop instead of while: or until: oUU` e lThe obsolete keyword: (default) syntax is used instead of the keyword = default syntax. c UU` 0Function return values have names but not types ngUU` efgNext-method is referenced inside a method that does not declare #next in the method header -usUU`   hUU` ri'Mindy issues warnings at runtime when: eUU`  kA variable is undefined (this becomes an error if the code referencing the undefined variable is executed) 1a2UU  gA methods return types do not match the generic functions return types because return types were not theUU@ yospecified for the method. ` foStack Overflow U#UU ! io}Mindy does not gracefully handle stack overflows. If Mindy gets a stack overflow, it will die with some kind of signal, like /UU@!  kSIGSEG (segmentation fault). If this happens, you probably have an infinite recursion in your program. ThJ` ywInternal Lossage ^UU  texSometimes mindycomp or Mindy will get an internal error. When this happens, it will print a message to stderr and then jUU Neabort. This results in the process dying due to some kind of signal. On the pmax, this signal is SIGILL, or Illegal Instruction.  vUU  wWhen this happens, send gwydion-bugs@cs.cmu.edu a piece of mail containing the error message and information on what it inUU@ (was you did that triggered the problem. etTU TU h at0 n o :Dylan vs. Mindy Language Issues urUU  he}The Dylan language is still changing slightly. Mindy implements most of the Dylan Reference Manual, as well as some a*UU  ckfeatures we would like to see in Dylan. In addition to those extensions described in  the document Gwydion Extensions |, Mindy Id$atreThJ$H%ba $Hnd--an interen-6UU@ nt*diverges from the DRM as described below: LUU` Th Additions: thbUU( e x pMindy supports multiple value binding in the =/then clauses of for statements. The format of such a tnUU@  clause is zUU` a /(var1, var2, ...) = expr1 THEN expr2 forUU( ine sKeyword parameters may have type information, and you can specify default values with either DRM yUU uatsyntax (which uses = ...) or with the obsolete syntax (which uses (...)). Using the second synanUU dtax will generate a compiler warning. Mindy does not enforce any congruence rules for keyword param eUU d `eter types, so effectively, keyword type information in generic function declarations serves as UU@ documentation only. $UU(* nMindy allows you to place library and module definitions in the same file as the actual code. See  @section UUH* rg1Using Libraries and Modules ? for details. UU`- thDeficiencies: UU(. ppq }Mindy does not implement macros. The DRM built-in macros (such as if and method-definer) can UU@. se*not be manipulated via the module system. UUh/ THY ~ Mindy does not have limited collections. (It does have limited integers, though) UU(0 t ~   Sealed/open and primary keywords are parsed where allowed, but Mindy ignores this information ,UU@0  tabout your program. ;UU`1 wiiMindy parses the seal generic and define sealed domain forms, but does not enforce them. JUU(2 eso  Define method does not automatically insert #next next-method in parameter lists. You have to umeVUU@2 explicitly add it yourself. yeUU 3 y dMany of the DRM built-in macros allow the bodies to be empty. Mindy does not. For example, in Mindy g qUU@3 lethe following is not legal: }UU 4 ciif (foo) . UU@4 esend if; UU`5 n 'Make(, ...) is unsupported. -de6UTU `6 Built-in Libraries and Modules tedUU 7 stMindy has full support for modules and libraries. Mindy provides two built-in libraries, Dylan and Dylan-user. The UU@7 edaDylan library contains the Dylan language implementation and the following exported modules: oUU`8 Dylan UU`9 amgThis module contains the Dylan language implementation and exports all the built-in Dylan definitions. ut UU`: he Extensions UUU*; DewThis module exports useful extensions to the Dylan language (see  Gsection The Extensions Module F). %UU; t fUltimately, there will be several, more logically separate libraries that extend Dylan or provide an 1UU; e,aapplication framework for users. For now, we put any commonly used utilities in the Extensions (=UU@; module. NUU`< System 5 ZUU(= , qThis module exports an interface to operating system calls and special, low-level functionality (see  Dsection fUUH= odThe System Module C). vi~wUU`> Introspection }UU`? n-WThis module exports reflective operations for examining classes, functions, and so on. menUU`@ loFile-descriptors eUU`A 8 cThis module exports an interface to most standard C system calls that operate on file descriptors. all#UU`B n Cheap-io ./UU`C : MThis module exports some basic, unextendable input and output functionality. d&cTF $H'dc ll$Hca++hat exteov+@UU`D e,Threads ioLUU E ermThis module exports an interface to threads, locks, and objects that behave similarly to cthreads.h XUU@E 5 condition variables. hiUU  an~The Dylan-user library is the default library in which mindycomp compiles user code. Mindy provides this library for uUU wvuser convenience when whipping up play code or small applications for which the programmer does not want to bother to UU n.create a library. You cannot redefine the Dylan-user library. This library contains one module, Dylan-user, and you UU@ sccannot redefine this module. UU K The Dylan language requires every library to contain a Dylan-user module, and this module must use the Dylan module UUK from the Dylan library regardless of any user specifications. This module provides a starting point in every library where ovUUK tusers can begin to define modules; without an initial module in the library, you would be unable to write any code, siUUK reincluding module definitions. Each Dylan-user module in Mindy also automatically uses the modules from the Dylan UUK  c}library described above. You cannot redefine the Dylan-user module, so if your code requires module other than those aUU@K icCdescribed above, then you must define your own library and module. ateUU L anuMindy comes bundled with several other libraries. Documentation for these libraries can be found in $INSTALL/doc/UU@L edlibraries. . AU"TU hM   Using Libraries and Modules y 7UU`N  aRTo compile code into a particular library use the -l switch to mindycomp: MUU`O fr#% mindycomp -lmy-lib foo.dylan ss YUU P icIf there is no -l switch, then mindycomp compiles the code into the Dylan-user library. When loading a .dbc file into al eUU@P arvMindy that was compiled into a particular library, one of the following conditions must be satisfied to avoid errors: {UU Q lswThe library must be the Dylan-user library. Technically, you could put code in the Dylan library, but e tUU@Q do not do this. urUU*R ulzYou must have defined the library in a file previously loaded (see  Isection Multiple Files H for information UU@R meon loading multiple files). ibUU`S iooThe first piece of code in the source file that produced the .dbc file must be the library definition. UU T ie{While loading a file, if Mindy processes a library definition that uses an undefined library, then Mindy stops loading the UUT % ~current file, searches for the undefined library, and loads it. After loading the undefined library, Mindy continues loading UUT ~the current file and processing the original library definition. Mindy searches for the undefined library in the directories UUHT co|listed in the  DYLANPATH environment variable. If DYLANPATH is undefined, then Mindy uses the path: alUU`% co.:$DYLANDIR/lib/dylan UU ' If DYLANDIR is also undefined, then the fallback default is /usr/local/lib/dylan on Unix and c:\dylan\lib\dylan ulUU@'  ^on Windows. This default can be changed by recompiling Mindy, see the build instructions. /UU  inIn each directory, Mindy first looks for the file -lib.dbc, where  is the name of the undefined ;UU@  aVlibrary, and if this file does not exist, then Mindy looks for .dbc. QUU U cuMindy loads the Dylan library when it first sees a reference to it. A reference to the Dylan library occurs when loading a ]UUU  afile compiled to be in the Dylan library, or when loading a file with a library definition that uses the Dylan library. Mindy iUU@U en`loads the Dylan library by looking for the file dylan.dbc on DYLANPATH. UU V YLTo make a single compiled file for a library which has multiple source files, compile all the files that constitute the library UU V cwith the -l switch set to the library's name. Then cat all the resulting .dbc files together (see  Ksection Multiple Files J), making ectUU@V oosure the file that defines the library is first. Then install the combined .dbc file in one of the directories in your DYLANPATH. notUU W  lTo compile code into a particular module, use the module: file header. Whenever a source file lacks a module: file header, e t(UUW  ~mindycomp issues a compiler warning and compiles the code into the Dylan-user module. This is the Dylan-user 4UUW nimodule of the library specified with the -l switch, and if there was no -l switch, it is the Dylan-user module of the d(e YLd le$H)fe , $Hth--y c-@UU@W chDylan-user library. If a file contains no file headers, it still must contain a leading blank line to conform to Dylan syntax. J)VUU X When loading a .dbc file into Mindy that was compiled into a particular module, one of the following conditions must be iebUU@X NPsatisfied to avoid errors:  lxUU`Y in2The module must be the Dylan-user module. UU*Z a yYou must have defined the module in a file previously loaded (see  Msection Multiple Files L for information tUU@Z on loading multiple files). isUU [ rrThe first code in the source file that produced the .dbc file must be library and module definitions, and UU@[  >one of the module definitions must be the module in question. HUTU h\  4The  Extensions Module UU J {Ultimately, there will be several, more logically separate libraries that extend Dylan or provide an application framework DyUUJ ry|for users. For now, we put any commonly used utilities in the Extensions module. Extensions which are likely to be X UU J  asupported in future Gwydion compilers are documented in  the document Gwydion Extensions ; here we document those NPUU@J id+extensions whose future is not so certain. mus#`^ -uGenerally Useful Definitions 7UU`_ e TThe Extensions module exports the following generally useful functionality:  RUUhd  t  main[Generic Function] ul^UU`e  Arguments jUU`f de!invocation-name :: hvUU`g e #rest arguments d UU`h , Description UU i hemHas no methods, but is called by Mindy when it starts up. To make a standalone program, you define a method UUi son main that does whatever you want it to do. Invocation-name is the first token on the command line that DyUUi ry}invoked Mindy. Arguments is a sequence of strings. There is a string in arguments for every argument on the UUi  a|command line that invoked Mindy, except all -f switches and the argument following each -f switch (that is, t UUi sthe file to load) is missing. Remember that any module that adds a method to main must use the Extensions UUU@i Ex'module from the Dylan library. geUUh~ ct  load[Function] tUU` ne Arguments UU` e name :: UU` caValues ::UU` vnone !UU` gu Description -UU  rivThis function takes the name of a .dbc file and loads the code in the file into Mindy as if the file had been 9UU  hspecified on the command line to Mindy. There is one exception: you can only load code that defines new toEUU  lhvariables or adds methods. You cannot redefine existing definitions. Advanced Mindy users can call this trQUUJ tssfunction from the debugger to add code to a running process. (See  the document The Mindy Debugger ) anUU` loload-library[Function] haUU`  Arguments UU`  mname :: h*UU`  aValues hod6UU` thnone xBUU`  Description ExNUU  oThis function takes a library name and loads the code for the library into Mindy as if the library was used by ZUU  :hanother library. Advanced Mindy users can call this function from the debugger to add code to a running iofUUJ  ?process. (See  the document The Mindy Debugger ) ds d*gi h sp$H+hg o$Hxon((s new to (h th Exiting Applications iUU`  Ap The Extensions module exports the following functionality for controlling the exiting of applications: esUUh cu on-exit[Function] UU`  Arguments UU` ncfunction :: UU` Values  mUU`  hmeaningless :: singleton(#f) dUU` th Description UU  riArranges for the exit function to call the argument function. The argument function must take no required useUU arguments. Users may call on-exit multiple times to install more than one function for exit to call, but the order UU in which exit invokes the functions is undefined. Calling on-exit on the same function repeatedly, installs that UU@ function multiple times. 7h on Weak Pointers KUU` Q The Extensions module exports the following weak-pointer functionality: AfUUh on [Class] g frUU  onThis class is a subclass of . The make method for this class takes the keyword parameter object:. ~UU  :}Instances of  refer to the object passed to the make method as long as some other reference to iUU uthe object exists. Whenever an instance of  is the only reference to an object, and a garbage mUU edicollection occurs, then Mindy considers the object to be garbage. When Mindy garbage collects an object eUU ex~referred to by a weak pointer, then Mindy marks the weak pointer as being broken (see the weak-pointer-object UU@ e function). ateUUh  ( weak-pointer-object [Function] meUU`  Arguments UU` wp :: EUU` leValues theUU` inobject :: fUU`  broken? :: lUU`  Description cUU   ovReturns the object referred to by the weak pointer and whether the weak pointer is broken. A weak pointer is )UU s xbroken when it contains the only reference to an object, and in this situation, weak-pointer-object returns the 5UU@ ob"values #f and #t. Ph r>( r t uDebugger Customizations nddUU` LThe Extensions module exports the following debugger customization: . UUht e " z*debug-output*[Variable] UU v by}The debugger uses the value of *debug-output* when performing output; its use is similar to *warning-output* UUJv te9(See  vDebugger Customizations on page45 q). nUU(w  yUsing the  wDebugger-format module in the Format library will set both *debug-output* and *warning- (UU@w *output* to *standard-output*. QUITU h+ ri The  System Module ^UUj, ctIn addition to those extensions described in  the document Gwydion Extensions , the System module exports the following: thd,isuaec$H-ji s$H. ,,r   C,yUUh: ' *print-GC-messages*ariable] xpoUU`; deDefault value UU`< #f e UU`= t* Description ] UU > byjThis variable controls whether Mindy prints garbage collection information whenever the garbage collector UU@>  runs. UUh?  '  collect-garbage[Function] 45UU`@  Arguments UU`A bu#key purify :: = #f UU`B seValues *UU`C anmeaningless :: singleton(#f) UU`D to Description -oUU E  uIf purify is true, collect-garbage does a purifying garbage collection. Otherwise, it does a normal garbage m$UUE tepcollection. A purifying collection is just like a normal collection except that everything left over after the ua0UUE lcollection is rendered permanent and is never again considered for collection. This can be quite useful in <UU@E  CNreducing the memory demands of your programs, as the total heap you need is: RUU`F ul0overhead + permanent + newspace + oldspace = hUU G ] with overhead being about five megabytes. Without purify, permanent will be 0, newspace is the amount of tUUG ru{live data, and oldspace is the amount of live data plus BYTES_CONSED_BETWEEN_GCS. Note that the live data y pUUG  =}is being counted twice: once in newspace and once in oldspace. But if you purify, that live data gets moved UU@G If<over to permanent, and then only gets counted once. agUUhH er getcwd[Function] UU`I E Arguments UU`J  cnone oUU`K orValues ctiUU`L rycurrent-directory :: UU`M co Description ndUU`N  i'Returns the current working directory. Th2UTU he efThe  Introspection Module e%UU*" deThe Mindy Introspection module exports reflective operations for examining classes, functions, and types. (See also  the document Gwydion Extensionsein1UUJ" yt ) L`# ,Classes and Instances `UU r The Introspection module exports the following for class objects, slot descriptions, and fetching and modifying the slot GlUU@r  tvalues of general objects: G UUhs nt abstract?unction] UU`t o Arguments UU`u y,class :: s*UU`v Values ov6UU`w tresult :: s BUU`x  Description erNUU`y Fu\Returns #t if class is an abstract class; otherwise returns #f. esiUUh L &  [Class] uUU  DeThis class is a subclass of . The slot-descriptors function returns instances of this class to describe the UU@ Mislots of a class object. od.kingyp. $H/lk non$H@yt**,Cl an*UUh Th$ slot-descriptors[Function] tUU` la Arguments UU` class :: iUU` lValues r UU` nedescriptors :: UU` ab Description unUU` bReturns a list of s for class. The result may be the empty list. UUh lt slot-name[Function] UU` er Arguments UU` slot :: #UU` ; Values re/UU` name :: ;UU` t- Description GUU` 8Returns the name of slot as a . e bUUh rs# slot-allocation[Function] is nUU` th Arguments zUU` s slot :: UU` Values UU` Jallocation :: one-of(#"instance", #"class", #"each-subclass", #"virtual") UU`  Description UU` DReturns the allocation type for slot as a . onUUh   slot-type[Function] UU` as Arguments UU` esslot :: UU` > Values UUU` iotype ::  UU` st Description de UU`  7Returns the type of values permitted for slot. U(UUh -n slot-getter[Function]  4UU`  Arguments @UU` t-slot :: LUU` /Values  XUU` bogf :: edUU`  Description Re~pUU` 9Returns the generic function that accesses slot. UUh  slot-setter[Function] thUU`  Arguments UU` scslot :: *UU` Values 6UU` e-gf :: "BUU` vi Description NUU` ri<Returns the generic function that stores into slot. d0mun$H1nm $H2 UU` (object :: slUU` ctValues 4UU` Arvalue :: UU`  UU`  Description UU  icReturns the value for slot in object and #t. If the slot in the object is uninitialized, then this function returns #f slUU ctvand #f. Note, this function does not go through generic function dispatch, and it calls no user methods; this UU@ e-?function uses an internal primitive to fetch the slots value. NUUh Re% slot-value-setter[Function] iUU`  Arguments UU` value :: UU` slot :: ,UU` object :: 8UU` Values DUU`  value :: PUU` sl Description Fu\UU  Stores value into slot of object and returns value. This function performs whatever type checking is necessary to hUU vaensure value is safe for slot. Note, this function does not go through generic function dispatch, and it calls no user ue tUU@ n Kmethods; this function uses an internal primitive to set the slots value. en UUh rn  init-keyword[Function] ctUU` No Arguments UU` thslot :: UU` noValues hodUU` keyword :: false-or() UU` et Description vaUU` WReturns the init-keyword associated with slot, or #f if there is none. UUUh  <% keyword-required?[Function] sUU` , Arguments UU` bjslot :: UU` Values  "UU` > answer :: De.UU`  Description St:UU`  igReturns #t if there is a required-init-keyword for slot, otherwise returns #f. ng )U[TU h hThe  File-descriptor Module e}pUU* sA cleaner interface to most of these functions is available from the Streams library (see  the document The Streams Library ). ||UU@  sjYou probably do not need to use the File-descriptor module, unless you need an obscure file mode. {UU`  RThe File-descriptor module exports the following functions and constants: d2o $H3po ewi$H11 U  <1UUh  fd-exec[Function] ,UU`  Arguments UU` sccommand-line :: *UU` Values > 6UU` anin-fd :: false-or() iBUU` out-fd :: false-or() NUU` d- Description orZUU  erpThis function provides a facility for running programs and scripts from within Mindy. The command-line r fUU ofiargument should contain the name of the program and all of the command line arguments for that program. brUU |zThis function returns the file descriptors for the new process's standard input and output. If fd-exec is unable ~UU@  Ato start the process, then it returns #f and #f. sUU  Note: This function has been deprecated in favor of piped-exec, which is exported from the Piped-exec module UUJ of the Streams library. See  {section Extensions to the Streams Library y in  the document Gwydion Extensions . UUh  UU` lsflags :: UU` riValues ZUU` Thfd :: false-or() UU` ogerrno :: false-or() nUU` nd Description fUU  arThis function calls the C open system call and returns the file descriptor and #f, if successful. If the first value 'UU leris #f, then the second value is the error number. You can convert the error number to a string using the 3UU@ , fderrorstring function. NUUh  fd-close[Function] unZUU` re Arguments fUU` ecfd :: orrUU` ipValues  ~UU` win? :: UU` ryerrno :: false-or() sUU`  Description UU  umThis function calls the C close system call and returns #t and #f, if successful. If the first value is #f, then the UU rsecond value is the error number. You can convert the error number to a string using the fd-error-string UU@ og function. UUh  n fd-read[Function] tioUU`  Arguments UU`! C fd :: m UU`" hebuffer :: ꄪUU`# sfoffset :: e UU`$ lecount :: thUU`% thValues umb)UU`& rtcount :: false-or( ) 5UU`' errno :: false-or() uAUU`(  Description fd~MUU ) onThis function calls the C read system call and returns the number of bytes read and #f, if successful. Offset is an e}YUU)  index into buffer, and it the index at which fd-read should start writing into the buffer. All other arguments are sy|eUU@) rn2the same as those described by the Unix man page. {{UU * #{If the first value is #f, then the second value is the error number. You can convert the error number to a string he zUU@* g,using the fd-error-string function. d4q$H5rq " $Hr>11offset e 1UU`+ t 'This function does no bounds checking. ues!UUh, &  fd-write[Function] ge-UU`- ' Arguments 9UU`. erfd :: ( EUU`/ fdbuffer :: ThQUU`0 thoffset :: m ]UU`1 hecount :: aniUU`2 ucValues uUU`3  ecount :: false-or( ) UU`4 nderrno :: false-or() eUU`5 t Description heUU 6 r This function calls the C write system call and returns the number of bytes written and #f, if successful. Offset , UU6 luis an index into buffer, and it is the index at which fd-write should start reading from the buffer. All other ncUU@6 d@arguments are the same as those described by the Unix man page. UU 7 {If the first value is #f, then the second value is the error number. You can convert the error number to a string t UU@7 es,using the fd-error-string function.  UU`8 nc'This function does no bounds checking. 9UUh9 fd' fd-input-available?[Function] ferUU`: Q Arguments UU`; ntfd :: (UU`<  <Values an4UU`= ucinput? :: @UU`>  ferrno :: false-or() LUU`?  f Description erXUU @ 5 zThis function returns whether there is any input available on the file descriptor. The second return value is #f dUU@ #fzif fd-input-available? could determine whether input was available. If there is an error, the second return value pUU@@ hoois the error number. You can convert the error number to a string using the fd-error-string function. y tUUhA " fd-sync-output[Function] UU`B , Arguments UU`C rrfd :: n UU`D nuValues stUU`E win? :: UU`F gerrno :: false-or() UU`G n Description cUU H This function calls the C fsync system call and returns #t and #f, if successful. If the first value is #f, then the UUH rsecond value is the error number. You can convert the error number to a string using the fd-error-string UU@H @ function. UUhI et fd-seek[Function] bleUU`J ip Arguments *UU`K isfd :: 6UU`L offset :: BUU`M hewhence :: leNUU`N rrValues ecoZUU`O pnew-pos :: false-or() mbe~fUU`P t errno :: false-or() i}rUU`Q r- Description ct|~UU R This function calls the C lseek system call and returns the new absolute position in the file and #f, if successful. {UUR {If the first value is #f, then the second value is the error number. You can convert the error number to a string zUU@R  f,using the fd-error-string function. and6scsf #$H7ts dal$Hj. 00or numbeus0UUhS  # fd-error-string[Function] UU`T  Arguments UU`U errno :: ume*UU`V K Values :: 6UU`W msg :: false-or() BUU`X he Description ntNUU Y }This function calls the C strerror system call and returns the string that describes the given error number. If the iZUU@Y r-Ierror number is unknown, then fd-error-string return #f. ڢuUUhZ re SEEK_SET[Constant] n UUh[  SEEK_CUR[Constant] UUh\ he SEEK_END[Constant] enUUh] is O_RDONLY[Constant] nvUUh^ er O_WRONLY[Constant] R UUh_  O_RDWR[Constant] UUh`  O_APPEND[Constant] sfUUha  O_CREAT[Constant] UUhb  O_TRUNC[Constant] . UUhc  O_EXCL[Constant] UUhd  ENOENT[Constant] UUhe  EIO[Constant] umeUUhf U  ENXIO[Constant] eUUhg K  EACCES[Constant] UUhh -o EFAULT[Constant] )UUhi ri EEXIST[Constant] 5UUhj ll ENOTDIR[Constant] em AUUhk he EISDIR[Constant] MUUhl   EINVAL[Constant] YUUhm un ENFILE[Constant] eUUhn # EMFILE[Constant] qUUho [ ENOSPC[Constant] }UUhp  EROFS[Constant] UUhq _E  ENAMETOOLONG[Constant] ] UUhr  EBADF[Constant] UUhs ON EINTR[Constant] UUht O_ EPIPE[Constant] UUhu O_ EFBIG[Constant] UU(v  These constants are mostly the same constants from the standard C libraries,  file.h and  errno.h, but a few UUv  hnames have been changed. Those names that have changed should be obvious. The Filedescriptors onUUv omodule exports all the constants users need to call the functions in the module, or test the functions return ISTUU@v 5values. j ,U TU hw The  Cheap-io Module UU $ IRThe Cheap-io module exports some basic, unextendable I/O functionality. Mindy uses the Cheap-io functions internally. +UU$ taThe Gwydion Project also provides the Streams, Print, and Format libraries (see  The Streams Library ,  The Print Library ,  ~7UU$ anand  The Format Library , respectively). It is an error to use both Cheap-IO functions and Streams/Print/Format }CUU$ nsfunctions on a single stream. (For example, if you are using the Streams library *standard-input*, do not also use the v |OUU$ Cheap-io input functions) For this reason, if any library that you load into Mindy uses the Debugger-format library, the e{[UU $ eedebugger will use format from the Format library. Also, look at  the document Gwydion Extensions  for Cheap-IO zgUU@$ IR9functionality also supported in other Gwydion compilers. bd8ue-i. +$H9vu pvi$H,,,Formatse,UUh ar prin1[Function] tUU`  Arguments UU` object :: *UU` ).Values er6UU` meaningless :: singleton(#f) SBUU` nt Description tNUU  $ vPrints thing to stdout. Print follows thing with a newline. You cannot extend or specialize how objects are ZUU@ heWprinted because these functions are written in C code, within Mindys implementation. hatuUUh dy puts[Function] maUU`  e Arguments UU`  wstring :: m UU`  lValues lsoUU` domeaningless :: singleton(#f) ڝUU` p- Description UU` ti1Prints the contents of string to stdout. bUUh  putc[Function] -iUU`  Arguments UU` char :: iUU` Values UU` rmmeaningless :: singleton(#f) UU`  Description un UU` Prints char to stdout.  ;UUh bj getc[Function] ).GUU`  Arguments SUU` innone #_UU`  Values crikUU` char :: twUU`  Description wUU` u SRead and return the next character from stdin. Returns #f at EOF. se UUh tt fflush[Function] UU` at Arguments UU` none cUU` Values ArUU` meaningless :: singleton(#f) gUU`  Description soUU` doyForces out any pending output generated by format, print, prin1, puts, and putc. 0UTU h The  Threads Module cUU  This module is in the Dylan library and exports an interface to s, s, and s (objects on which threads ) (UU@  Hcan wait until a signalling thread indicates the events have occurred). ;C`  Classes and Functions WUU` HThe Threads module exports the following classes and functions: krUUh ch [Class] ~UU  DetThis class is a subclass of . Instances of this class are the handles by which programs manipulate e UU@ tt threads. hd:wes  c$H;xw $Het// De/UUh ut  spawn-thread[Function] 멪UU` ri Arguments UU` sdebug-name :: *UU`  init-function :: 6UU` ulValues he BUU` arthread :: rfaNUU`  Description >ZUU  ntvSpawns a concurrent asynchronous thread and invokes init-function in that thread. The dynamic context of the fUU@ kthread is the same as if it were the main thread of a program at the beginning of the program's execution. assUUh k kill-thread[Function] >UU`  Arguments UU` suthread :: >UU` thValues areUU` icthread :: e UU` tt Description UU` rKills thread immediately. After calling this function, the argument thread never executes again. UUh " current-thread[Function] UU`  Arguments UU` none cUU` Values ArUU` thread :: :: UU` * Description  ,UU`  <1Returns the thread handle of the current thread. GUUh ad  [Abstract Class] SUU  Z~This class is a subclass of . Instances of this class provide logical locks. A lock is locked when a thread _UU successfully grabs a lock, and we say the thread holds the lock. Holding a lock in no way prohibits access to a kUU -tnresource. It is purely the convention of various threads to access a shared resource only after successfully wUU@ rejgrabbing a lock. If  is passed to make, make returns a . UUh ed'  [Sealed Class] arUU  ڃThis class is a subclass of . Instances of this class provide a single-locking model. Whenever a  noUU  |is locked, any thread that tries to grab it will block. Whenever a  is locked, any thread may release it. thUU@  tCWhenever a  is unlocked, any thread may grab it. assUU   ps are designed to be held for a very short period of time, several machine instructions at most. keUU _uThreads should only hold a  for a very short period of time because other threads that are waiting oUU esyfor the lock are blocked and could be wasting CPU cycles by busy looping; that is, waiting for a  does tUU wsnot necessarily use anything as heavy weight as a system call to sleep the thread waiting for the lock. If only a >UU  ucouple threads are sharing a resource, it may be more efficient to actually hold a  for a moderate aUU  plamount of time while performing a high-level operation, rather than use a lock to build a more heavy-weight atUU@ wi[mutual exclusion mechanism (such as a semaphore) to isolate access to the shared resource.  *UU` MUnlocking a  when it is already unlocked signals an error. sEUUh de# [Sealed Class] rioQUU   mThis class is a subclass of . Instances of this class provide a multilocking model. Whenever a  ]UU aduis unlocked, any thread may grab it. A thread that holds a  may grab the lock repeatedly without tiUU  ureleasing the lock. Each grab effectively increments a counter, and each release effectively decrements a counter. e~uUU r uA  is available to be grabbed by any thread when the counter returns to zero; therefore, a thread l}UU lolmust release the lock for each grabbing of the lock. This behavior is useful for implementing a high-level ha|UU ilnoperation that needs to isolate access to a resource while calling a few lower-level operations that lock the d<y k>$H=zy o s$H= &&d Class]&UU sutresource; in this way, the high-level operation effectively calls all the lower-level operations atomically with no UU@ nlEother threads affecting the state of the resource between the calls. ڨ(UU` k ^Whenever a  is locked, only the thread that holds the lock may release it. >UU  h ys are designed to be held for as long as a thread requires. When other threads call the grab-lock hJUU texfunction and block because a  is locked, the other threads are guaranteed to sleep until the lock is ehVUU@ r available. a hlUU` NUnlocking a  when it is already unlocked signals an error. UUh  o# [Sealed Class] UU` eThis class is a subclass of . Instances of this class provide a single-locking model. UU  zWhenever a  is unlocked, any thread may grab it. Whenever a  is locked, any thread UU@ e Uthat tries to grab it will block. Whenever a d is locked, any thread may release it. nUU   rys are designed to be held for as long as a thread requires. When other threads call the grab-lock lUU . xfunction and block because a  is locked, the other threads are guaranteed to sleep until the lock is heUU@  h available.  UU`  bNUnlocking a  when it is already unlocked signals an error. UUh lo locked?[Function] av UU`  Arguments ,UU`  n i8UU` keValues anDUU` locked? :: ePUU` s] Description \UU` ss0Returns whether the lock is held by any thread. iswUUh in% grab-lock[Generic Function] UU` se Arguments UU` thlock :: WUU` apValues isUU` d meaningless :: singleton(#f) sUU` lo Description dUU  reuReturns after successfully grabbing the lock. If the lock is not immediately available, this function waits for the eUU@ lllock to become available. UUh fu  grab-lock[G.F. Method] maUU` ed Arguments UU` telock :: lo UU` Values avUU` meaningless :: singleton(#f) s"UU`  i Description nl.UU  rrzReturns after successfully grabbing the lock. This method can only grab lock when it is unlocked. When the lock :UU@  ?is held, this method may busy-loop until the lock is unlocked. d>{ ss ihe$H?|{ gr$H|un//se Ar/UU` k>grab-lock[G.F. Method] esUU`  Arguments UU` (#lock :: lo*UU` Values  6UU` r meaningless :: singleton(#f) BUU` t Description aiNUU  onzReturns after successfully grabbing the lock. This method can only grab lock when it is unlocked. When the lock ZUU@ ArSis held, this method puts the calling thread to sleep until the lock is available. uUU` megrab-lock[G.F. Method] "UU` De Arguments UU` rrlock :: sfUU` loValues meUU`  meaningless :: singleton(#f) .UU` : Description UU  thqReturns after successfully grabbing the lock. A single thread may successfully call this method repeatedly, but UU Hthe thread must call release-lock once for each call to grab-lock. If the thread calls release-lock fewer times than UU Mesgrab-lock, the lock remains locked, and any threads waiting for the lock will continue to wait. When a thread 6UU memthat does not hold the lock calls this method, the method puts the calling thread to sleep until the lock is yUU@ . available. canUUh k( release-lock[Generic Function] ZUU` is Arguments UU` lllock :: ep ,UU` avValues 8UU` memeaningless :: singleton(#f) DUU` De Description PUU` loQReleases the lock. If lock is unlocked, this function signals an error. skUU`  .release-lock[G.F. Method] wUU` th Arguments UU` ra'lock :: union(, ) essUU` thValues edlUU` meaningless :: singleton(#f) UU`  Description caUU  k~Releases the lock. If lock is unlocked, this function signals an error. Any thread may unlock a  or UU@ in\, regardless of whether it is the thread that successfully grabbed the lock. ldUU` isrelease-lock[G.F. Method] ingUU` nt Arguments UU`  lock :: UU`  Values -lo UU` meaningless :: singleton(#f) rUU`  Description :"UU  Releases the lock. If lock is unlocked, this function signals an error. Only the thread that holds lock may call this .UU Ifvfunction, and if another thread tries to release the lock, this method signals an error. When this function returns, :UU Arlock may still be locked. A thread that has repeatedly grabbed a  must call release-lock once for each ::FUU@ call to grab-lock. ca~aUUh k [Class] }mUU  edvThis class is a subclass of . Threads use events to block without busy looping and to communicate to |yUU@ er(other threads that they should wake up. d d@}o$HA~} o :$H22 $ 2UUh  r* wait-for-event[Generic Function] UU` as Arguments UU` s event :: t*UU` orlock :: th6UU` Values l tBUU`  meaningless :: singleton(#f) tNUU` ea Description hiZUU  n {Releases the lock and puts the calling thread to sleep until some other thread signals event. After this function a fUU  vreturns, the lock is unheld, and the calling thread must try to grab the lock before accessing any shared resources. rUU [CpDue to implementation details, this function may return even when the lock is unavailable, or the event has not us~UU omtruly occurred; because of this, programs need to loop over wait-for-event and grab-lock, testing that the event UU@ Yactually occurred. Methods exist for both s and s. UUh   signal-event[Function] UU` -e Arguments UU` event :: rUU` Values evUU` *meaningless :: singleton(#f) >UU`  Description tUU`  nSignals that the event occurred, indicating that Mindy should wake up a thread that is waiting on this event. UUh hr# broadcast-event[Function] sigUU` . Arguments UU`   ,UU` k Values , a8UU` eameaningless :: singleton(#f) oDUU` ha Description PUU` [ChSignals that the event occurred and causes Mindy to wake up every thread that is waiting on this event. hak`!  Examples rUU`" usSThe following code shows how to use locks and events to isolate access to a queue: estUU #  L// This example shows two routines, get-queue and release-queue. Code >UU# phN// that accesses the queue should call get-queue before doing so and call UU# s K// release-queue when done. Any code failing to isolate access to the UU# inL// queue in this way has undefined behavior and is incorrectly written.  UU@#  e// rreUU $  ML// This variable is #t if and only if the queue is generally available. hrUU$ en// nctUU@$ +define variable queue-available? = #t; entUU %  J// This constant holds an event object used to signal when the queue UU% ri*// becomes generally available again. UU% an// MinUU@% y 5define constant queue-available = make(); %UU & C// This constant holds a lock object used to isolate access to s t1UU& o :// queue-available? for testing and setting purposes. =UU& qu// eleIUU@& >/define constant queue-lock = make(); eueUUU ' ueK// When this function returns, the caller has exclusive access to the one~aUU' g J// queue. If necessary, this function waits for the queue to become }mUU' ioK// available, but it does not busy loop. This function returns #f as $ |yUU' va$// a meaningless return value. is{UU' le// zUU' //define method get-queue () inedBta h$HC eue$Hri55ly avail 5UU' ingrab-lock(queue-lock); UU' ai!while (~ queue-available?) UU' hi5wait-for-event(queue-available, queue-lock); o*UU' & grab-lock(queue-lock); te6UU' pu end; BUU' //queue-available? := #f; NUU' e- lock-release(queue-lock); ZUU' he #f; fUU@' al end; lrUU ( e L// This function releases the queue and signals that it is released so t~UU(  K// that someone waiting on the queue will be woken up. This function tioUU( $ 2// returns #f as a meaningless return value. UU( // UU( #define method release-queue () ()UU( grab-lock(queue-lock); UU( queue-available? := #t; UU(  release-lock(queue-lock); UU( %signal-event(queue-available); UU(  #f; UU@(  end; iUU`) uetThe following example shows how to use a lock to isolate queue access in a different way than the previous example:  UU * loK// This constant holds an event object used to signal when an element -avUU* N// exists in the queue. l$UU* $ // U0UU@* ; 9define constant something-available = make(); /<UU + eaO// This constant holds a lock that is held whenever a thread is accessing thaHUU+ on// queue. TUU+  f// tio`UU@+ $ )define constant lock = make(); lUU , +// This constant holds a queue object. dexUU, e-// ()UU@, +define constant queue = make(); ( UU - avG// This function returns an element from queue. If no element is UU- M// immediately available, then this function blocks until it can return UU-  iM// an element. This function assumes only one or two other threads are qUU- ifL// ever waiting for the queue, and it assumes pop is a fast high-level taUU- ob// operation. henUU- // * UU- s "define method get-something() UU- grab-lock(lock); conUU- aiwhile (empty?(queue)) UU- //3wait-for-event(something-available, lock); hreUU- hagrab-lock(lock); /UU-  end; //~ UU- + let result = pop(queue); mak},UU- lock-release(lock); |8UU- ueresult; {DUU@-  end; zPUU . M// This function adds thing to queue. It assumes only one or two other uy\UU. elN// threads are ever waiting for the queue, and it assumes push is a fast xhUU. hi// high-level operation. wtUU. // vUU. Th'define method put-something(thing) thdDewat su$HE - $H. //UU. d grab-lock(lock); UUU. abpush(queue, thing); UU. ilrelease-lock(lock); *UU. )signal-event(something-available); ;6UU@. - end; OUWTU `m  /%Miscellaneous Implementation Choices lUU(n The error method specialized on  applies the format function to the arguments passed to error. See  section xUU n hiThe Extensions Module  for the details of format from the Cheap-io module of the Dylan library. See  the document The Format LibraryUUJn //H  for the details of format from the Format library. ThUU r d Rest arguments in Mindy are s. You cannot use any functions on the rest argument that assumes the collection UUr - is an instance of any class more specific than ; for example, you cannot use the head or tail functions because UU@r , -they operate on instances of . kUU(s Mindys  implementation is equivalent to  .unicode characters. The  class exported from the cUU@s n YExtensions module of the Dylan library is a subclass of . EUTU ht  a /Copyright and Terms of Use S UU`u xWCopyright (c) 1994, 1995, 1996, 1997 Carnegie Mellon University All rights reserved. e  UU v duuUse and copying of this software and preparation of derivative works based on this software are permitted, including i,UU@v Ecommercial use, provided that the following conditions are observed: sBUU w . FirstBody. $$fnSE *$ 1Step Step Number S:.\tStep. fo % 2Heading .. . dff2ff233@p %H     h  Argument.  @q %H     h  Body. 33+33$frB %ul33+n Bullet Bullet SymbolB:\t. ]K$fsB % ]m Bullet2. Bullet SymbolB:\t. 33+33+$ft %CBullet. HHH@u % H    h e Copyright. $$$fv *CStep. ff2ff233@w %H    h ln Description. dd33@x %H m t u th : Description2. ff233@y %HH    h  DItem. KK@z %$H    h  DItem2. @{ H    h  Verbatim. 33 @ %33 Endnote.\t. %33 @ %33 Endnote1.\t. 333333 @  %H I    h  Excerpt. ff2K33@ %HI 2   h  Extra Key Arg. ff2ff2 @ %VeH    h  Function Body. @P % Function HeadDItem. HHH fT % HeadingBody. HHHfD %  HeadingSub. $$fS *$ Step Step Number S:.\t. f * CellHeading. f *CellBody. fT *  TableTitleT:Table : . @ %H     h  Body. @ %  Body. @ %Body. HHH fT % HeadingBody. HHH@ %H    h  Copyright. 333333 @  %H    h  Excerpt. $0fQ %  1Heading 1Heading Rule. FirstBody. 33+33$fB %33+ yBullet Bullet SymbolB:\t. @ %. H    h  Body. @ H    h  Verbatim. f % 2Heading .. . @ eaHl   i  h  Verbatim. 33+33$ fB %33+ Bullet Bullet SymbolB:\t. ff2ff233@ %H o   h  Description. ff233@ % Ht    h  DItem. @ % Function Head. ff2ff2 @ %VeH    h  Function Body. ff2ff233@ %H    h  Argument. @P % Function HeadDItem. ff2ff233@ % H    h  Argument. @P %  Function HeadDItem. @ % B Function Head. @ %  Function Head. @ % Function Head. @P % Function HeadDitem.  Vz *  % Variable  % Superscript  *   % Superscript  %Argument    Bullet Symbol%@ %  @ %   %  %  % _   Computer  %Emphasis  EquationVariables@    Step Number   SubscriptFu   Superscript  % Variable  %Emphasis oc;   Bullet Symbol _ Computer @ % Variable  %Argument  % @ %     Thin Medium Double Thick@  Very Thinh     HHHHHFormat A    iHHHHHFormat Ba q b a Comment    U V / W X < Z Y le   ^ _ 8  c d r  f g  w i j  ! v q s " X # 6 5 T $ { y x % |  & ~ ' @ ?  (   ) D C  * G F   + I H  , K J  - M L   . O N  / Meum 0   1  2 Th 3  4  Tnh 5  6  7  8  d Black!T WhiteddA Reddd Greendd BluedCyanidHMagentaHd YellowW.Palatino.R.700 Palatino-Bold W.Times.R.400 Times-Roman W.Palatino.R.400Palatino-RomanW.Palatino.I.400Palatino-Italic W.Courier.R.400 Courier W.Times.R.700 Times-BoldW.Courier.R.700 Courier-BoldW.Helvetica.R.700 Helvetica-Bold7Courier  Helvetica%Palatino*Times Regular Regular BoldItalicRegularx>2e(5s*ne U9# BJ9ZWNs\?0hDBC6a|jg4 #A"zsFCOiJ9a?Mb /GK/CR?;, xn_kYeaHk EP<2N9 Dx& [=6 h)ھ3ѣL#)Vpv4GdC]c_}|sT`7Ԉc$oc̞)o@XYǼΞX*z 1Ys bD,oKTk;"@P\GV)AK&h $4VΤxZ ''KŶd-'̞cp