1: \input texinfo @c -*-texinfo-*- 2: @comment %**start of header 3: @c EN 4: @setfilename gauche-deve.info 5: @settitle Gauche Developers' Reference 6: @dircategory The Algorithmic Language Scheme 7: @direntry 8: * Gauche Developers' Reference: (gauche-deve.info). Internals of Gauche 9: @end direntry 10: @c JP 11: @setfilename gauche-devj.info 12: @settitle Gauche -A-A-A??ȯ?ԥ???????$)B$)B$)B 13: @dircategory The Algorithmic Language Scheme 14: @direntry 15: * Gauche Developers' Reference (ja): (gauche-devj.info). Internals of Gauche 16: @end direntry 17: @c COMMON 18: @comment %**end of header 19: 20: @c $Id: gauche-dev.texi,v 1.30 2007/04/13 11:15:36 shirok Exp $ 21: 22: @iftex 23: @finalout 24: @parskip 4pt plus 1pt 25: @end iftex 26: 27: @titlepage 28: @c EN 29: @title Gauche Developers' Reference 30: @c JP 31: @title Gauche -A-A-A??ȯ?ԥ???????$)B$)B$)B 32: @c COMMON 33: @subtitle version @VERSION@ 34: @author Shiro Kawai (shiro@@acm.org) 35: 36: @page 37: @vskip 0pt plus 1filll 38: Copyright @copyright{} 2005 Shiro Kawai (shiro@@acm.org) 39: 40: @end titlepage 41: 42: @node Top, Introduction, (dir), (dir) 43: 44: @ifnottex 45: @c EN 46: This document explains the internal guts of Gauche 47: for developers who want to extend Gauche functionality in C, 48: or to embed Gauche to other applications. 49: This manual is for version @VERSION@. 50: @c JP 51: -A-A-A????Gauche?ε?ǽ??????????ꡢGauche??Υ??ץꥱ????????$)B$)B$)B 52: -A-A-A????????ä????Ȥ????ȯ?ԤΤ?????$)B$)B$)B 53: Gauche-A-A-A?????¤???????ΤǤ???$)B$)B$)B 54: Gauche-A-A-A?ΥС?????@VERSION@??б????ޤ???$)B$)B$)B 55: @c COMMON 56: @end ifnottex 57: 58: @menu 59: * Introduction:: 60: * Getting started:: 61: * Fundamental concepts:: 62: * Real-life examples:: 63: * C API reference:: 64: * Creating new Scheme datatypes:: 65: * Helper program reference:: 66: * Indices:: 67: @end menu 68: 69: @c ====================================================================== 70: @node Introduction, Getting started, Top, Top 71: @chapter Introduction 72: 73: The core part of the Gauche runtime is written in C and provided 74: as a library, @file{libgauche}. This document explains how to 75: use it from C. Using C API, you can extend Gauche's 76: functionality (e.g. providing bindinds to the existing C library), 77: and also link @file{libgauche} to your application, making 78: Gauche as an embedded scripting language. 79: 80: Gauche's C API is designed for efficiency, consistency, 81: simplicity and safety, roughly in this order of precedence. 82: That is, simplicity and safety are sometimes compromized 83: by efficiency. For example, sometimes you have to choose 84: from similar APIs to achieve a goal, where each API is designed 85: to be efficient for a particular case. The API also assumes 86: the caller takes care not to break internal structure; there's 87: no much safety net that protects you from shooting your foot. 88: (By saying "safety is compromized" I don't mean @file{libgauche} 89: has security holes; I mean it assumes the programmer knows what 90: he's doing.) 91: 92: That said, it won't be too difficult to use Gauche's C API 93: as far as you know some fundamental design concepts. 94: 95: We intend this document to serve both a programmer's guide 96: that explains such design concepts, and a programer's reference 97: that describes every C API in detail. 98: 99: The guide part begins with @ref{Getting started}, that shows 100: how to write a simple Gauche extension in C, as well as 101: a simple application that embeds Gauche. It gives an overview 102: of the whole process. 103: 104: The following chapter, @ref{Fundamental concepts}, describes 105: the design behind the API. We strongly recommend you to 106: understand this chapetr before trying to use Gauche C API 107: seriously. As we mentioned above, it is very easy to break 108: something without knowing those concepts. 109: 110: The guide part concludes with @ref{Real-life examples}, that 111: explains pitfalls in the practical situations using excerpt 112: of the actual Gauche extension code. 113: 114: The reference part consists of two chapters: @ref{C API reference} 115: lists all the public C API. @ref{Helper program reference} 116: explains several programs installed as a part of Gauche Scheme 117: system to help program development. 118: 119: @c ====================================================================== 120: @node Getting started, Fundamental concepts, Introduction, Top 121: @chapter Getting started 122: 123: This chapter explains the basics of how to use Gauche C API 124: by several simple examples. 125: 126: Although each example is too small to be practical value, 127: we try to present working code for each example, so that you 128: can actually play with it. We recommend you to read through 129: all examples, for we introduce new concepts in each step. 130: 131: We deal with the advanced topics that arises in the practical 132: situation in @ref{Real-life examples}. 133: 134: The prerequisites for building Gauche extension, besides 135: the basic compiler chain, are the followings. We assume 136: these are installed in your system. 137: @itemize @bullet 138: @item 139: Gauche 0.8.8 or later 140: @item 141: GNU autoconf 2.54 or later 142: @end itemize 143: 144: @menu 145: * A trivial extension:: 146: * Simple readline binding:: 147: @end menu 148: 149: @node A trivial extension, Simple readline binding, Getting started, Getting started 150: @section A trivial extension 151: 152: @menu 153: * Generating skeletons:: 154: * Building the trivial module:: 155: * The templates explained:: 156: * Introduction of the stub file:: 157: @end menu 158: 159: @node Generating skeletons, Building the trivial module, A trivial extension, A trivial extension 160: @subsection Generating skeletons 161: 162: Let's create a Gauche extension that does nothing. 163: 164: Gauche can generate a skeleton of the extension code 165: by @code{gauche-package generate} command. You give the 166: package name to the command-line argument (here we pick @code{trivial}). 167: 168: @example 169: % @b{ls trivial} 170: ls: trivial: No such file or directory 171: % @b{gauche-package generate trivial} 172: % @b{ls trivial} 173: DIST configure.ac trivial.c trivial.scm 174: Makefile.in test.scm trivial.h triviallib.stub 175: @end example 176: 177: The @code{gauche-package} command creates a directory @file{trivial}, 178: and populates it with template files. The role of each file is shown 179: below. 180: 181: @table @emph 182: @item Glue code (@file{trivial.c} and @file{trivial.h}) 183: If what you want to do is just to write C functions and make it 184: available from Scheme, the function definitions and declarations 185: would go to these files. 186: 187: Even if what you want to do is just to write bindings to 188: an existing library, it is typical that you need small amount 189: of auxiliary management code, such as initializing the library 190: and allocating/freeing library-side data structures. 191: 192: @item Stub file (@file{trivial.stub}) 193: This file is the bridge between C world and Scheme world. 194: You have to list C functions you want to make it visible from 195: Scheme world. Because of its nature, this file looks like 196: a mixture of Scheme code and C code fragments. 197: 198: When the package is compiled, Gauche's helper scripts generates 199: a C file from a stub file, and compiles it with other glue code 200: to generate a dynamically loadable object code, called DLL 201: (dynamically loadable library) or SO (shared object), depending 202: on the platform. 203: 204: @item Module file (@file{trivail.scm}) 205: This file typically defines Gauche modules and set exported 206: symbols, and dynamically loads the compiled object code. 207: You may put auxiliary Scheme code in it. 208: 209: @item Files to build the package (@file{configure.ac}, @file{Makefile.in}, @file{DIST}) 210: Gauche relies on GNU @code{autoconf} and @code{make} to build 211: the package, that is, the package user can use the simple 212: @code{./configure}, @code{make} and @code{make install} sequence 213: to build and install the package. 214: 215: @file{DIST} is a small shell script that automates creating 216: a distribution tarball. 217: 218: @item Unit test (@file{test.scm}) 219: It is strongly encouraged to include unit test in your package, 220: and this file contains the skeleton of it. The package user 221: can run the test by @code{make check}. 222: @end table 223: 224: @node Building the trivial module, The templates explained, Generating skeletons, A trivial extension 225: @subsection Building, testing and installing the trivial module 226: 227: These auto-generated files are already buildable. 228: First, you need to run @file{autoconf} to generate a @file{configure} 229: script. 230: 231: @example 232: % @b{cd trivial} 233: % @b{autoconf} 234: % @b{ls} 235: DIST autom4te.cache configure.ac trivial.c trivial.scm 236: Makefile.in configure test.scm trivial.h triviallib.stub 237: @end example 238: 239: The directory @file{autom4te.cache} is a temporary structure used 240: by autoconf. You can safely remove it if it bothers you. 241: 242: Once @file{configure} script is generated, you can run it to 243: generate @file{Makefile}, then run @code{make}. 244: 245: @example 246: % @b{./configure} 247: checking for gosh... /usr/bin/gosh 248: checking for gauche-config... /usr/bin/gauche-config 249: checking for gauche-package... /usr/bin/gauche-package 250: checking for gauche-install... /usr/bin/gauche-install 251: checking for gauche-cesconv... /usr/bin/gauche-cesconv 252: configure: creating trivial.gpd 253: configure: creating ./config.status 254: config.status: creating Makefile 255: % @b{make} 256: /usr/bin/gauche-package compile --verbose trivial trivial.c triviallib.stub 257: @i{(... message truncated ...)} 258: % @b{ls} 259: DIST config.log trivial.c trivial.so triviallib.o 260: Makefile config.status trivial.gpd trivial_head.c triviallib.stub 261: Makefile.in configure trivial.h trivial_head.o 262: VERSION configure.ac trivial.o trivial_tail.c 263: autom4te.cache test.scm trivial.scm trivial_tail.o 264: @end example 265: 266: The build process creates @file{trivial.so}, the dynamically loadable 267: object file (the actual suffix may differ on some OSes). 268: 269: Now it's ready to load the extension into Gauche. The skeleton code 270: defines a Scheme function @code{test-trivial}, which just returns 271: a string. Run the Gauche interpreter, load the @code{trivial} module, 272: and call @code{test-trivial} function. Note that you need to give 273: @code{-I.} option to @code{gosh}, so that Gauche can find the @file{trivial} 274: module files. 275: 276: @example 277: % @b{gosh -I.} 278: gosh> @b{(use trivial)} 279: #<undef> 280: gosh> @b{(test-trivial)} 281: "trivial is working" 282: gosh> 283: @end example 284: 285: You may have noticed a file @file{trivial.gpd}. The unfamiliar 286: suffix @code{gpd} stands for ``Gauche package description''. 287: It is created by @file{configure}, and records the name and version 288: of the package, and the configure options. It is installed as a part 289: of the package and will be used by @code{gauche-package} script 290: (e.g. @code{gauche-package list} lists the installed packages). 291: 292: You can also run a unit test by @code{make check}. 293: 294: @example 295: % make check 296: /usr/bin/gosh -I. test.scm > test.log 297: Testing trivial ... passed. 298: @end example 299: 300: For now, it just checks if the compiled extention can be loaded, 301: and the integrity of the module. As you add APIs in the extension, 302: you're expected to add tests as well. 303: 304: Finally, you can install the extension by @code{make install}. 305: 306: @example 307: % make install 308: /usr/bin/gauche-install -m 444 -T /usr/lib/gauche/site/include 309: /usr/bin/gauche-install -m 444 -T /usr/share/gauche/site/lib trivial.scm 310: /usr/bin/gauche-install -m 555 -T /usr/lib/gauche/site/0.8.8/i686-pc-linux-gnu trivial.so 311: /usr/bin/gauche-install -m 444 -T /usr/share/gauche/site/lib/.packages trivial.gpd 312: @end example 313: 314: By default, the files are installed in the site-specific area 315: reserved within the intalled Gauche. 316: If you want to change the install location, you can do the 317: same as typical autoconfiscated softwares; e.g. giving 318: @code{--prefix} option to the @code{configure} script, 319: or 320: 321: 322: 323: 324: 325: 326: @node The templates explained, Introduction of the stub file, Building the trivial module, A trivial extension 327: @subsection The templates explained 328: 329: 330: 331: 332: 333: @node Introduction of the stub file, , The templates explained, A trivial extension 334: @subsection Introduction of the stub file 335: 336: 337: 338: @node Simple readline binding, , A trivial extension, Getting started 339: @section Simple readline binding 340: 341: 342: 343: 344: 345: 346: 347: 348: 349: @c ====================================================================== 350: @node Fundamental concepts, Real-life examples, Getting started, Top 351: @chapter Fundamental concepts 352: 353: @menu 354: * Naming convention:: 355: * Scheme types and C types:: 356: * Memories:: 357: * The VM:: 358: * CPS API:: 359: @end menu 360: 361: @node Naming convention, Scheme types and C types, Fundamental concepts, Fundamental concepts 362: @section Naming convention 363: 364: @node Scheme types and C types, Memories, Naming convention, Fundamental concepts 365: @section Scheme types and C types 366: 367: @node Memories, The VM, Scheme types and C types, Fundamental concepts 368: @section Memories 369: 370: @node The VM, CPS API, Memories, Fundamental concepts 371: @section The VM 372: 373: 374: 375: 376: @node CPS API, , The VM, Fundamental concepts 377: @section CPS API 378: 379: 380: 381: 382: @c ====================================================================== 383: @node Real-life examples, C API reference, Fundamental concepts, Top 384: @chapter Real-life examples 385: 386: 387: @c ====================================================================== 388: @node C API reference, Creating new Scheme datatypes, Real-life examples, Top 389: @chapter C API reference 390: 391: In this chapter we describe most of public C APIs provided by 392: libgauche. We say `most' because the features to let you create 393: a new Scheme datatype requires dedicated chapter, 394: @ref{Creating new Scheme datatypes}. 395: 396: @menu 397: * Representation of Scheme objects:: 398: * Initialization and cleanup:: 399: * Memory allocation and GC:: 400: * Booleans:: 401: * Numbers:: 402: * Pairs and Lists:: 403: * Symbols:: 404: * Glocs:: 405: * Modules:: 406: * Keywords:: 407: * Characters:: 408: * Character sets:: 409: * Strings:: 410: * Regular expressions:: 411: * Vectors:: 412: * Dictionaries:: 413: * Weak pointers:: 414: * Exceptions:: 415: * Calling back to Scheme:: 416: * Input and output:: 417: * Loading programs:: 418: * System interface:: 419: @end menu 420: 421: @node Representation of Scheme objects, Initialization and cleanup, C API reference, C API reference 422: @section Representation of Scheme objects 423: 424: @deftp {Type} ScmObj 425: Scheme objects are uniformly treated as of type @code{ScmObj}, 426: which may be either a tagged pointer to a heap allocated object 427: or a tagged immediate value. 428: 429: Most Scheme objects are heap allocated, and except Scheme pairs, 430: heap allocated Scheme object has a fixed header. We don't go 431: into more details here, but we'll revisit this topic in 432: @ref{Creating new Scheme datatypes}. Certain frequently used 433: Scheme objcts, such as boolean values, small exact integers 434: and characters, are encoded in a word without allocating 435: objects in heap, and we call them @emph{immediate values}. 436: 437: Querying the type of a Scheme object and accessing its fields 438: should be done via provided macros or APIs. The user code must 439: treat @code{ScmObj} as an opaque word, since the internal 440: representation may change. 441: 442: The standard way to treat @code{ScmObj} value is (1) check to see 443: if its type matches what you expect, and (2) cast @code{ScmObj} to 444: the actual type and use it, as the following example shows. 445: 446: @example 447: void your_C_function(ScmObj arg) 448: @{ 449: if (SCM_STRINGP(arg)) @{ /* check */ 450: ScmString *s = SCM_STRING(arg); /* cast */ 451: do_whatever_you_like_with_scheme_string(s); 452: @} else @{ 453: SCM_TYPE_ERROR(arg, "a string"); 454: @} 455: @} 456: @end example 457: 458: The @code{SCM_TYPE_ERROR} macro raises an error reporting 459: "a string is required for arg, but got ...". That's a convenient 460: way to report the wrong type argument. See @ref{Exceptions} 461: for more details of reporting errors. 462: 463: Although it is not always checked explicitly, the programmer should 464: keep in mind that C's @code{NULL} is never a valid value for @code{ScmObj}. 465: If a C API requires @code{ScmObj} as an argument, you shouldn't pass 466: @code{NULL} to it. Also if your function returns @code{ScmObj}, 467: you should make sure it will never return @code{NULL}. 468: @end deftp 469: 470: @deftypefn {Macro} ScmObj SCM_OBJ (void *@var{obj}) 471: Typecast @var{obj} to @code{ScmObj}. @var{Obj} must be 472: a pointer to an actual Scheme object. 473: @end deftypefn 474: 475: We describe a few special constant Scheme objects here: 476: 477: @deftypevr {Macro} ScmObj SCM_EOF 478: The Scheme's @code{#<eof>} object. 479: @end deftypevr 480: 481: @deftypevr {Macro} ScmObj SCM_UNDEFINED 482: The Gauche's @code{#<undef>} object. In Gauche, it is used as a 483: placeholder where the value itself doesn't matter. At the time of 484: writing this document, there's a discussion in the next Scheme standard 485: to define @emph{the `unspecified' value} for this purpose, and it is 486: likely that this value will become such a value. 487: @end deftypevr 488: 489: @deftypevr {Macro} ScmObj SCM_UNBOUND 490: This is a special value only seen in C world, and used to indicate 491: that a variable hasn't got a Scheme value assigned. For example, 492: if a Scheme procedure with an optional argument is defined in C, 493: and no value is passed to the optional argument, @code{SCM_UNBOUND} 494: is given in C world. This value should never be leaked out to 495: Scheme world. 496: @end deftypevr 497: 498: @deftypefn {Macro} int SCM_EOFP (ScmObj @var{obj}) 499: @deftypefnx {Macro} int SCM_UNDEFINEDP (ScmObj @var{obj}) 500: @deftypefnx {Macro} int SCM_UNBOUNDP (ScmObj @var{obj}) 501: Predicates to check whether the given @var{obj} is @code{SCM_EOF}, 502: @code{SCM_UNDEFINED}, or @code{SCM_UNBOUND}, respectively. 503: @end deftypefn 504: 505: @node Initialization and cleanup, Memory allocation and GC, Representation of Scheme objects, C API reference 506: @section Initialization and cleanup 507: 508: This section explains how to initialize Gauche scheme runtime, 509: and how to clean it up. 510: 511: @subsubheading Initialization 512: 513: @deftypefun void Scm_Init (const char *@var{signature}) 514: Initializes the runtime. Must be called before any other 515: Gauche API call. 516: 517: To @var{signature}, you should always 518: pass a macro @code{GAUCHE_SIGNATURE}. It is used to check a 519: proper version of Gauche shared library is linked. If you 520: have several version of Gauche libraries (e.g. different 521: encoding or thread configuration), accidentally linking 522: unintended version would cause mysterious runtime crash. 523: If the signature doesn't match the library's, this function 524: exits the process with a message explaining it. 525: @end deftypefun 526: 527: @subsubheading Cleanup and termination 528: 529: @deftypefun void Scm_Exit (int @var{code}) 530: Exits the process with @var{code} as the exit code. 531: Calling @code{Scm_Exit} is the easiest way to terminate Gauche 532: application safely. It runs pending dynamic handlers, 533: registered cleanup handlers (see below), flushes output ports, 534: then call @code{exit(2)} to exit. 535: 536: Directly calling @code{exit(2)} would skip all those cleanup 537: process. 538: @end deftypefun 539: 540: @deftypefun void Scm_Cleanup (void) 541: Cleans up the Scheme runtime just like @code{Scm_Exit()}, 542: but does not call @code{exit(2)} at the end. This is useful 543: for applications that want to shut down Gauche runtime but 544: need to continue running. 545: 546: Once you call @code{Scm_Cleanup()}, you shoudn't use any 547: other Gauche functions. 548: 549: It is harmless to call @code{Scm_Cleanup()} more than once; 550: it becomes no-op from the second time and after. 551: @end deftypefun 552: 553: @deftypefun void Scm_Panic (const char *@var{msg}, @dots{}) 554: The @var{msg} and other arguments are treated like @code{printf(3)}. 555: Formats and displays the formatted messate, then exits the process 556: by calling @code{_exit(2)} with exit code 1. No cleanup is done. 557: 558: This is called when a serious defect is detected in the Gauche 559: runtime and cannot continue normal operation in any way. 560: @end deftypefun 561: 562: @deftypefun void Scm_Abort (const char *@var{msg}) 563: Writes @var{msg} to file desctipor 2, and exits the process 564: by calling @code{_exit(2)} with exit code 1. No cleanup is done. 565: 566: This is the last resort of emergency exit, where you cannot 567: even call @code{malloc} reliably. 568: @end deftypefun 569: 570: @subsubheading Cleanup handlers 571: 572: You can register functions to be called when Gauche runtime 573: is shut down. The registered functions are called by 574: @code{Scm_Exit()} or @code{Scm_Cleanup()} in the reverse 575: order of their registration. 576: 577: @deftypefun {void *} Scm_AddCleanupHandler (void (*@var{h})(void *), void *@var{d}) 578: Adds a function @var{h} to the clanup handler chain, with an opaque 579: data pointer @var{d}. At the cleanup time, @var{h} is called 580: with @var{d} as the single argument. 581: 582: Returns an opaque handle, which can be passed to DeleteCleanupHandler. 583: @end deftypefun 584: 585: @deftypefun void Scm_DeleteCleanupHandler (void *@var{handle}) 586: Delete cleanup handler. The @var{handle} argument should be an opaque pointer 587: returned from @code{Scm_AddCleanupHandler}. (But it won't complain if 588: other pointer is given; it just do nothing.) 589: @end deftypefun 590: 591: @node Memory allocation and GC, Booleans, Initialization and cleanup, C API reference 592: @section Memory allocation and GC 593: 594: Memories allocated by using the following macros are owned 595: by Gauche runtime and managed by the garbage collector. 596: 597: @subsubheading Allocator macros 598: 599: There's two kind of allocators; ordinary ones and 600: @emph{atomic} ones. Here the term @emph{atomic} means 601: the allocated memory would never contain pointers 602: the collector needs to trace. For example, when you 603: allocate memory for a character string, you can use 604: atomic allocator since the memory won't contain any 605: pointers. 606: 607: It is important to use atomic versions whenever possible. 608: Gauche's GC is conservative, which means if there's a 609: word that looks like a pointer in a live object, the collector assumes 610: it is a pointer and retains the memory chunk pointed by it. 611: If it is not really a pointer, the collector may retain 612: unnecessary memory chunks. It is called false pointers. 613: Telling the collector that a chunk of memory never contains 614: traceable pointer you can reduce the chance of false pointers. 615: 616: It is OK for the atomic memory chunk to contain a pointer, 617: as far as the pointed chunk is reachable by other means, 618: or you can allow the pointed chunk to be collected (like 619: weak pointers). 620: 621: Note: The term @emph{atomic} here probably came from the 622: fact that such a memory chunk is a terminal node, or an atom, 623: in the graph the collector traverses. It has nothing to 624: do with the atomic operations. 625: 626: @deftypefn {Macro} {@var{TYPE} *} SCM_NEW (@var{TYPE}) 627: @deftypefnx {Macro} {@var{TYPE} *} SCM_NEW_ATOMIC (@var{TYPE}) 628: Allocates memory for datatype @var{TYPE} and returns its pointer. 629: @code{ATOMIC} version allocates the memory as an atomic chunk. 630: @end deftypefn 631: 632: @deftypefn {Macro} {@var{TYPE} *} SCM_NEW_ARRAY (@var{TYPE}, size_t @var{nelts}) 633: @deftypefnx {Macro} {@var{TYPE} *} SCM_NEW_ATOMIC_ARRAY (@var{TYPE}, size_t @var{nelts}) 634: Allocates memory for an array of size @var{nelts} of datatype @var{TYPE}, 635: and returns its pointer. 636: @end deftypefn 637: 638: @deftypefn {Macro} {@var{TYPE} *} SCM_NEW2 (@var{TYPE}, size_t @var{size}) 639: @deftypefnx {Macro} {@var{TYPE} *} SCM_NEW_ATOMIC2 (@var{TYPE}, size_t @var{size}) 640: Allocates memory of @var{size} bytes, and returns it as a pointer to 641: the datatype @var{TYPE}. 642: @end deftypefn 643: 644: Note: to allocate a Scheme object for the class that is inheritable 645: from Scheme, you should use @code{SCM_ALLOCATE} macro to do some 646: extra initialization. It is described in @ref{Creating new Scheme datatypes}. 647: You don't need to worry about it as far as you uses provided set 648: of Scheme datatypes, for each of them have a special "make" function 649: such as @code{Scm_MakeString}, @code{Scm_MakeVector}, etc. 650: 651: @subsubheading Garbage collection 652: 653: The garbage collector runs implicitly whenever it is necessary. 654: However, you can run it explicitly by this function: 655: 656: @deftypefun void Scm_GC (void) 657: Triggers full GC. 658: @end deftypefun 659: 660: 661: 662: @subsubheading Finalizers 663: 664: 665: @node Booleans, Numbers, Memory allocation and GC, C API reference 666: @section Booleans 667: 668: @deftypevr {Macro} ScmObj SCM_TRUE 669: @deftypevrx {Macro} ScmObj SCM_FALSE 670: Scheme's @code{#t} and @code{#f}. 671: @end deftypevr 672: 673: @deftypefn {Macro} int SCM_TRUEP (ScmObj @var{obj}) 674: @deftypefnx {Macro} int SCM_FALSEP (ScmObj @var{obj}) 675: Predicates to check whether the given @var{obj} is @code{SCM_TRUE} or 676: @code{SCM_FALSE}, respectively. Note that @code{!SCM_FALSEP(obj)} 677: is different from @code{SCM_TRUEP(obj)}. Since Scheme treats anthing 678: other than @code{#f} as a true value, usually what you need is 679: @code{SCM_FALSEP}. You use @code{SCM_TRUEP} only iff you want 680: to make sure the object is @code{#t}. 681: @end deftypefn 682: 683: @deftypefn {Macro} int SCM_BOOLP (ScmObj @var{obj}) 684: Returns @code{TRUE} iff @var{obj} is either @code{SCM_FALSE} or 685: @code{SCM_TRUE}. 686: @end deftypefn 687: 688: @deftypefn {Macro} int SCM_BOOL_VALUE (ScmObj @var{obj}) 689: Converts Scheme value to C boolean value. Returns @code{FALSE} 690: iff @var{obj} is @code{#f}. 691: @end deftypefn 692: 693: @deftypefn {Macro} ScmObj SCM_MAKE_BOOL (@var{obj}) 694: Converts C boolean value to a Scheme boolean value. 695: Returns @code{SCM_FALSE} if @var{obj} is @code{FALSE}, 696: and @code{SCM_TRUE} for any other values. 697: @end deftypefn 698: 699: @deftypefn {Macro} int SCM_EQ (ScmObj @var{x}, ScmObj @var{y}) 700: Compare two Scheme objects are the same, in the sense of 701: Scheme's @code{eq?}. You should always use this macro 702: instead of comparing two Scheme objects by @code{==}. 703: @end deftypefn 704: 705: @deftypefun int Scm_EqP (ScmObj @var{x}, ScmObj @var{y}) 706: A function version of @code{SCM_EQ}. 707: @end deftypefun 708: 709: @deftypefun int Scm_EqvP (ScmObj @var{x}, ScmObj @var{y}) 710: Scheme's @code{eqv?}. 711: @end deftypefun 712: 713: @deftypefun int Scm_EqualP (ScmObj @var{x}, ScmObj @var{y}) 714: Scheme's @code{equal?}. Note: this function may call back VM recursively. 715: @end deftypefun 716: 717: @deftypefun int Scm_EqualM (ScmObj @var{x}, ScmObj @var{y}, int @var{mode}) 718: A convenient function to write functions with parameterized 719: equivalence procedure. @var{Mode} may be one of the following 720: constants: 721: @table @code 722: @item SCM_CMP_EQ 723: Compare using @code{eq?} 724: @item SCM_CMP_EQV 725: Compare using @code{eqv?} 726: @item SCM_CMP_EQUAL 727: Compare using @code{equal?} 728: @end table 729: @end deftypefun 730: 731: 732: 733: @node Numbers, Pairs and Lists, Booleans, C API reference 734: @section Numbers 735: 736: @menu 737: * Scheme number objects:: 738: * Number predicates:: 739: * Converting C and Scheme numbers:: 740: * Generic arithmetics:: 741: * Subtype-specific number operations:: 742: * Reading and writing numbers:: 743: @end menu 744: 745: @node Scheme number objects, Number predicates, Numbers, Numbers 746: @subsection Scheme number objects 747: 748: @subsubheading C representation of numbers 749: 750: Gauche uses several different structures to represent Scheme