1 @c essay \input texinfo
2 @c essay @c -*-texinfo-*-
3 @c essay @c %**start of header
4 @c essay @setfilename data-rep.info
5 @c essay @settitle Data Representation in Guile
6 @c essay @c %**end of header
8 @c essay @include version.texi
10 @c essay @dircategory The Algorithmic Language Scheme
12 @c essay * data-rep: (data-rep). Data Representation in Guile --- how to use
13 @c essay Guile objects in your C code.
14 @c essay @end direntry
16 @c essay @setchapternewpage off
19 @c essay Data Representation in Guile
21 @c essay Copyright (C) 1998, 1999, 2000 Free Software Foundation
23 @c essay Permission is granted to make and distribute verbatim copies of
24 @c essay this manual provided the copyright notice and this permission notice
25 @c essay are preserved on all copies.
28 @c essay Permission is granted to process this file through TeX and print the
29 @c essay results, provided the printed document carries copying permission
30 @c essay notice identical to this one except for the removal of this paragraph
31 @c essay (this paragraph not being relevant to the printed manual).
34 @c essay Permission is granted to copy and distribute modified versions of this
35 @c essay manual under the conditions for verbatim copying, provided that the entire
36 @c essay resulting derived work is distributed under the terms of a permission
37 @c essay notice identical to this one.
39 @c essay Permission is granted to copy and distribute translations of this manual
40 @c essay into another language, under the above conditions for modified versions,
41 @c essay except that this permission notice may be stated in a translation approved
42 @c essay by the Free Software Foundation.
47 @c essay @comment The title is printed in a large font.
48 @c essay @title Data Representation in Guile
49 @c essay @subtitle $Id: data-rep.texi,v 1.6 2002-03-12 21:08:57 ossau Exp $
50 @c essay @subtitle For use with Guile @value{VERSION}
51 @c essay @author Jim Blandy
52 @c essay @author Free Software Foundation
53 @c essay @author @email{jimb@@red-bean.com}
54 @c essay @c The following two commands start the copyright page.
56 @c essay @vskip 0pt plus 1filll
57 @c essay @vskip 0pt plus 1filll
58 @c essay Copyright @copyright{} 1998 Free Software Foundation
60 @c essay Permission is granted to make and distribute verbatim copies of
61 @c essay this manual provided the copyright notice and this permission notice
62 @c essay are preserved on all copies.
64 @c essay Permission is granted to copy and distribute modified versions of this
65 @c essay manual under the conditions for verbatim copying, provided that the entire
66 @c essay resulting derived work is distributed under the terms of a permission
67 @c essay notice identical to this one.
69 @c essay Permission is granted to copy and distribute translations of this manual
70 @c essay into another language, under the above conditions for modified versions,
71 @c essay except that this permission notice may be stated in a translation approved
72 @c essay by Free Software Foundation.
73 @c essay @end titlepage
75 @c essay @c @smallbook
77 @c essay @headings double
80 @c essay @node Top, Data Representation in Scheme, (dir), (dir)
81 @c essay @top Data Representation in Guile
84 @c essay This essay is meant to provide the background necessary to read and
85 @c essay write C code that manipulates Scheme values in a way that conforms to
86 @c essay libguile's interface. If you would like to write or maintain a
87 @c essay Guile-based application in C or C++, this is the first information you
90 @c essay In order to make sense of Guile's @code{SCM_} functions, or read
91 @c essay libguile's source code, it's essential to have a good grasp of how Guile
92 @c essay actually represents Scheme values. Otherwise, a lot of the code, and
93 @c essay the conventions it follows, won't make very much sense.
95 @c essay We assume you know both C and Scheme, but we do not assume you are
96 @c essay familiar with Guile's C interface.
101 @node Data Representation
102 @chapter Data Representation in Guile
104 @strong{by Jim Blandy}
106 [Due to the rather non-orthogonal and performance-oriented nature of the
107 SCM interface, you need to understand SCM internals *before* you can use
108 the SCM API. That's why this chapter comes first.]
110 [NOTE: this is Jim Blandy's essay almost entirely unmodified. It has to
111 be adapted to fit this manual smoothly.]
113 In order to make sense of Guile's SCM_ functions, or read libguile's
114 source code, it's essential to have a good grasp of how Guile actually
115 represents Scheme values. Otherwise, a lot of the code, and the
116 conventions it follows, won't make very much sense. This essay is meant
117 to provide the background necessary to read and write C code that
118 manipulates Scheme values in a way that is compatible with libguile.
120 We assume you know both C and Scheme, but we do not assume you are
121 familiar with Guile's implementation.
124 * Data Representation in Scheme:: Why things aren't just totally
125 straightforward, in general terms.
126 * How Guile does it:: How to write C code that manipulates
127 Guile values, with an explanation
128 of Guile's garbage collector.
129 * Defining New Types (Smobs):: How to extend Guile with your own
130 application-specific datatypes.
133 @node Data Representation in Scheme
134 @section Data Representation in Scheme
136 Scheme is a latently-typed language; this means that the system cannot,
137 in general, determine the type of a given expression at compile time.
138 Types only become apparent at run time. Variables do not have fixed
139 types; a variable may hold a pair at one point, an integer at the next,
140 and a thousand-element vector later. Instead, values, not variables,
143 In order to implement standard Scheme functions like @code{pair?} and
144 @code{string?} and provide garbage collection, the representation of
145 every value must contain enough information to accurately determine its
146 type at run time. Often, Scheme systems also use this information to
147 determine whether a program has attempted to apply an operation to an
148 inappropriately typed value (such as taking the @code{car} of a string).
150 Because variables, pairs, and vectors may hold values of any type,
151 Scheme implementations use a uniform representation for values --- a
152 single type large enough to hold either a complete value or a pointer
153 to a complete value, along with the necessary typing information.
155 The following sections will present a simple typing system, and then
156 make some refinements to correct its major weaknesses. However, this is
157 not a description of the system Guile actually uses. It is only an
158 illustration of the issues Guile's system must address. We provide all
159 the information one needs to work with Guile's data in @ref{How Guile
164 * A Simple Representation::
170 @node A Simple Representation
171 @subsection A Simple Representation
173 The simplest way to meet the above requirements in C would be to
174 represent each value as a pointer to a structure containing a type
175 indicator, followed by a union carrying the real value. Assuming that
176 @code{SCM} is the name of our universal type, we can write:
179 enum type @{ integer, pair, string, vector, ... @};
181 typedef struct value *SCM;
187 struct @{ SCM car, cdr; @} pair;
188 struct @{ int length; char *elts; @} string;
189 struct @{ int length; SCM *elts; @} vector;
194 with the ellipses replaced with code for the remaining Scheme types.
196 This representation is sufficient to implement all of Scheme's
197 semantics. If @var{x} is an @code{SCM} value:
200 To test if @var{x} is an integer, we can write @code{@var{x}->type == integer}.
202 To find its value, we can write @code{@var{x}->value.integer}.
204 To test if @var{x} is a vector, we can write @code{@var{x}->type == vector}.
206 If we know @var{x} is a vector, we can write
207 @code{@var{x}->value.vector.elts[0]} to refer to its first element.
209 If we know @var{x} is a pair, we can write
210 @code{@var{x}->value.pair.car} to extract its car.
214 @node Faster Integers
215 @subsection Faster Integers
217 Unfortunately, the above representation has a serious disadvantage. In
218 order to return an integer, an expression must allocate a @code{struct
219 value}, initialize it to represent that integer, and return a pointer to
220 it. Furthermore, fetching an integer's value requires a memory
221 reference, which is much slower than a register reference on most
222 processors. Since integers are extremely common, this representation is
223 too costly, in both time and space. Integers should be very cheap to
224 create and manipulate.
226 One possible solution comes from the observation that, on many
227 architectures, structures must be aligned on a four-byte boundary.
228 (Whether or not the machine actually requires it, we can write our own
229 allocator for @code{struct value} objects that assures this is true.)
230 In this case, the lower two bits of the structure's address are known to
233 This gives us the room we need to provide an improved representation
234 for integers. We make the following rules:
237 If the lower two bits of an @code{SCM} value are zero, then the SCM
238 value is a pointer to a @code{struct value}, and everything proceeds as
241 Otherwise, the @code{SCM} value represents an integer, whose value
242 appears in its upper bits.
245 Here is C code implementing this convention:
247 enum type @{ pair, string, vector, ... @};
249 typedef struct value *SCM;
254 struct @{ SCM car, cdr; @} pair;
255 struct @{ int length; char *elts; @} string;
256 struct @{ int length; SCM *elts; @} vector;
261 #define POINTER_P(x) (((int) (x) & 3) == 0)
262 #define INTEGER_P(x) (! POINTER_P (x))
264 #define GET_INTEGER(x) ((int) (x) >> 2)
265 #define MAKE_INTEGER(x) ((SCM) (((x) << 2) | 1))
268 Notice that @code{integer} no longer appears as an element of @code{enum
269 type}, and the union has lost its @code{integer} member. Instead, we
270 use the @code{POINTER_P} and @code{INTEGER_P} macros to make a coarse
271 classification of values into integers and non-integers, and do further
272 type testing as before.
274 Here's how we would answer the questions posed above (again, assume
275 @var{x} is an @code{SCM} value):
278 To test if @var{x} is an integer, we can write @code{INTEGER_P (@var{x})}.
280 To find its value, we can write @code{GET_INTEGER (@var{x})}.
282 To test if @var{x} is a vector, we can write:
284 @code{POINTER_P (@var{x}) && @var{x}->type == vector}
286 Given the new representation, we must make sure @var{x} is truly a
287 pointer before we dereference it to determine its complete type.
289 If we know @var{x} is a vector, we can write
290 @code{@var{x}->value.vector.elts[0]} to refer to its first element, as
293 If we know @var{x} is a pair, we can write
294 @code{@var{x}->value.pair.car} to extract its car, just as before.
297 This representation allows us to operate more efficiently on integers
298 than the first. For example, if @var{x} and @var{y} are known to be
299 integers, we can compute their sum as follows:
301 MAKE_INTEGER (GET_INTEGER (@var{x}) + GET_INTEGER (@var{y}))
303 Now, integer math requires no allocation or memory references. Most
304 real Scheme systems actually use an even more efficient representation,
305 but this essay isn't about bit-twiddling. (Hint: what if pointers had
306 @code{01} in their least significant bits, and integers had @code{00}?)
310 @subsection Cheaper Pairs
312 However, there is yet another issue to confront. Most Scheme heaps
313 contain more pairs than any other type of object; Jonathan Rees says
314 that pairs occupy 45% of the heap in his Scheme implementation, Scheme
315 48. However, our representation above spends three @code{SCM}-sized
316 words per pair --- one for the type, and two for the @sc{car} and
317 @sc{cdr}. Is there any way to represent pairs using only two words?
319 Let us refine the convention we established earlier. Let us assert
323 If the bottom two bits of an @code{SCM} value are @code{#b00}, then
324 it is a pointer, as before.
326 If the bottom two bits are @code{#b01}, then the upper bits are an
327 integer. This is a bit more restrictive than before.
329 If the bottom two bits are @code{#b10}, then the value, with the bottom
330 two bits masked out, is the address of a pair.
333 Here is the new C code:
335 enum type @{ string, vector, ... @};
337 typedef struct value *SCM;
342 struct @{ int length; char *elts; @} string;
343 struct @{ int length; SCM *elts; @} vector;
352 #define POINTER_P(x) (((int) (x) & 3) == 0)
354 #define INTEGER_P(x) (((int) (x) & 3) == 1)
355 #define GET_INTEGER(x) ((int) (x) >> 2)
356 #define MAKE_INTEGER(x) ((SCM) (((x) << 2) | 1))
358 #define PAIR_P(x) (((int) (x) & 3) == 2)
359 #define GET_PAIR(x) ((struct pair *) ((int) (x) & ~3))
362 Notice that @code{enum type} and @code{struct value} now only contain
363 provisions for vectors and strings; both integers and pairs have become
364 special cases. The code above also assumes that an @code{int} is large
365 enough to hold a pointer, which isn't generally true.
368 Our list of examples is now as follows:
371 To test if @var{x} is an integer, we can write @code{INTEGER_P
372 (@var{x})}; this is as before.
374 To find its value, we can write @code{GET_INTEGER (@var{x})}, as
377 To test if @var{x} is a vector, we can write:
379 @code{POINTER_P (@var{x}) && @var{x}->type == vector}
381 We must still make sure that @var{x} is a pointer to a @code{struct
382 value} before dereferencing it to find its type.
384 If we know @var{x} is a vector, we can write
385 @code{@var{x}->value.vector.elts[0]} to refer to its first element, as
388 We can write @code{PAIR_P (@var{x})} to determine if @var{x} is a
389 pair, and then write @code{GET_PAIR (@var{x})->car} to refer to its
393 This change in representation reduces our heap size by 15%. It also
394 makes it cheaper to decide if a value is a pair, because no memory
395 references are necessary; it suffices to check the bottom two bits of
396 the @code{SCM} value. This may be significant when traversing lists, a
397 common activity in a Scheme system.
399 Again, most real Scheme systems use a slightly different implementation;
400 for example, if GET_PAIR subtracts off the low bits of @code{x}, instead
401 of masking them off, the optimizer will often be able to combine that
402 subtraction with the addition of the offset of the structure member we
403 are referencing, making a modified pointer as fast to use as an
407 @node Guile Is Hairier
408 @subsection Guile Is Hairier
410 We originally started with a very simple typing system --- each object
411 has a field that indicates its type. Then, for the sake of efficiency
412 in both time and space, we moved some of the typing information directly
413 into the @code{SCM} value, and left the rest in the @code{struct value}.
414 Guile itself employs a more complex hierarchy, storing finer and finer
415 gradations of type information in different places, depending on the
416 object's coarser type.
418 In the author's opinion, Guile could be simplified greatly without
419 significant loss of efficiency, but the simplified system would still be
420 more complex than what we've presented above.
423 @node How Guile does it
424 @section How Guile does it
426 Here we present the specifics of how Guile represents its data. We
427 don't go into complete detail; an exhaustive description of Guile's
428 system would be boring, and we do not wish to encourage people to write
429 code which depends on its details anyway. We do, however, present
430 everything one need know to use Guile's data.
436 * Immediates vs Non-immediates::
437 * Immediate Datatypes::
438 * Non-immediate Datatypes::
439 * Signalling Type Errors::
440 * Unpacking the SCM type::
444 @subsection General Rules
446 Any code which operates on Guile datatypes must @code{#include} the
447 header file @code{<libguile.h>}. This file contains a definition for
448 the @code{SCM} typedef (Guile's universal type, as in the examples
449 above), and definitions and declarations for a host of macros and
450 functions that operate on @code{SCM} values.
452 All identifiers declared by @code{<libguile.h>} begin with @code{scm_}
455 @c [[I wish this were true, but I don't think it is at the moment. -JimB]]
456 @c Macros do not evaluate their arguments more than once, unless documented
459 The functions described here generally check the types of their
460 @code{SCM} arguments, and signal an error if their arguments are of an
461 inappropriate type. Macros generally do not, unless that is their
462 specified purpose. You must verify their argument types beforehand, as
465 Macros and functions that return a boolean value have names ending in
466 @code{P} or @code{_p} (for ``predicate''). Those that return a negated
467 boolean value have names starting with @code{SCM_N}. For example,
468 @code{SCM_IMP (@var{x})} is a predicate which returns non-zero iff
469 @var{x} is an immediate value (an @code{IM}). @code{SCM_NCONSP
470 (@var{x})} is a predicate which returns non-zero iff @var{x} is
471 @emph{not} a pair object (a @code{CONS}).
474 @node Conservative GC
475 @subsection Conservative Garbage Collection
477 Aside from the latent typing, the major source of constraints on a
478 Scheme implementation's data representation is the garbage collector.
479 The collector must be able to traverse every live object in the heap, to
480 determine which objects are not live.
482 There are many ways to implement this, but Guile uses an algorithm
483 called @dfn{mark and sweep}. The collector scans the system's global
484 variables and the local variables on the stack to determine which
485 objects are immediately accessible by the C code. It then scans those
486 objects to find the objects they point to, @i{et cetera}. The collector
487 sets a @dfn{mark bit} on each object it finds, so each object is
488 traversed only once. This process is called @dfn{tracing}.
490 When the collector can find no unmarked objects pointed to by marked
491 objects, it assumes that any objects that are still unmarked will never
492 be used by the program (since there is no path of dereferences from any
493 global or local variable that reaches them) and deallocates them.
495 In the above paragraphs, we did not specify how the garbage collector
496 finds the global and local variables; as usual, there are many different
497 approaches. Frequently, the programmer must maintain a list of pointers
498 to all global variables that refer to the heap, and another list
499 (adjusted upon entry to and exit from each function) of local variables,
500 for the collector's benefit.
502 The list of global variables is usually not too difficult to maintain,
503 since global variables are relatively rare. However, an explicitly
504 maintained list of local variables (in the author's personal experience)
505 is a nightmare to maintain. Thus, Guile uses a technique called
506 @dfn{conservative garbage collection}, to make the local variable list
509 The trick to conservative collection is to treat the stack as an
510 ordinary range of memory, and assume that @emph{every} word on the stack
511 is a pointer into the heap. Thus, the collector marks all objects whose
512 addresses appear anywhere in the stack, without knowing for sure how
513 that word is meant to be interpreted.
515 Obviously, such a system will occasionally retain objects that are
516 actually garbage, and should be freed. In practice, this is not a
517 problem. The alternative, an explicitly maintained list of local
518 variable addresses, is effectively much less reliable, due to programmer
521 To accommodate this technique, data must be represented so that the
522 collector can accurately determine whether a given stack word is a
523 pointer or not. Guile does this as follows:
527 Every heap object has a two-word header, called a @dfn{cell}. Some
528 objects, like pairs, fit entirely in a cell's two words; others may
529 store pointers to additional memory in either of the words. For
530 example, strings and vectors store their length in the first word, and a
531 pointer to their elements in the second.
534 Guile allocates whole arrays of cells at a time, called @dfn{heap
535 segments}. These segments are always allocated so that the cells they
536 contain fall on eight-byte boundaries, or whatever is appropriate for
537 the machine's word size. Guile keeps all cells in a heap segment
538 initialized, whether or not they are currently in use.
541 Guile maintains a sorted table of heap segments.
544 Thus, given any random word @var{w} fetched from the stack, Guile's
545 garbage collector can consult the table to see if @var{w} falls within a
546 known heap segment, and check @var{w}'s alignment. If both tests pass,
547 the collector knows that @var{w} is a valid pointer to a cell,
548 intentional or not, and proceeds to trace the cell.
550 Note that heap segments do not contain all the data Guile uses; cells
551 for objects like vectors and strings contain pointers to other memory
552 areas. However, since those pointers are internal, and not shared among
553 many pieces of code, it is enough for the collector to find the cell,
554 and then use the cell's type to find more pointers to trace.
557 @node Immediates vs Non-immediates
558 @subsection Immediates vs Non-immediates
560 Guile classifies Scheme objects into two kinds: those that fit entirely
561 within an @code{SCM}, and those that require heap storage.
563 The former class are called @dfn{immediates}. The class of immediates
564 includes small integers, characters, boolean values, the empty list, the
565 mysterious end-of-file object, and some others.
567 The remaining types are called, not surprisingly, @dfn{non-immediates}.
568 They include pairs, procedures, strings, vectors, and all other data
571 @deftypefn Macro int SCM_IMP (SCM @var{x})
572 Return non-zero iff @var{x} is an immediate object.
575 @deftypefn Macro int SCM_NIMP (SCM @var{x})
576 Return non-zero iff @var{x} is a non-immediate object. This is the
577 exact complement of @code{SCM_IMP}, above.
580 Note that for versions of Guile prior to 1.4 it was necessary to use the
581 @code{SCM_NIMP} macro before calling a finer-grained predicate to
582 determine @var{x}'s type, such as @code{SCM_CONSP} or
583 @code{SCM_VECTORP}. This is no longer required: the definitions of all
584 Guile type predicates now include a call to @code{SCM_NIMP} where
588 @node Immediate Datatypes
589 @subsection Immediate Datatypes
591 The following datatypes are immediate values; that is, they fit entirely
592 within an @code{SCM} value. The @code{SCM_IMP} and @code{SCM_NIMP}
593 macros will distinguish these from non-immediates; see @ref{Immediates
594 vs Non-immediates} for an explanation of the distinction.
596 Note that the type predicates for immediate values work correctly on any
597 @code{SCM} value; you do not need to call @code{SCM_IMP} first, to
598 establish that a value is immediate.
608 @subsubsection Integers
610 Here are functions for operating on small integers, that fit within an
611 @code{SCM}. Such integers are called @dfn{immediate numbers}, or
612 @dfn{INUMs}. In general, INUMs occupy all but two bits of an
615 Bignums and floating-point numbers are non-immediate objects, and have
616 their own, separate accessors. The functions here will not work on
617 them. This is not as much of a problem as you might think, however,
618 because the system never constructs bignums that could fit in an INUM,
619 and never uses floating point values for exact integers.
621 @deftypefn Macro int SCM_INUMP (SCM @var{x})
622 Return non-zero iff @var{x} is a small integer value.
625 @deftypefn Macro int SCM_NINUMP (SCM @var{x})
626 The complement of SCM_INUMP.
629 @deftypefn Macro int SCM_INUM (SCM @var{x})
630 Return the value of @var{x} as an ordinary, C integer. If @var{x}
631 is not an INUM, the result is undefined.
634 @deftypefn Macro SCM SCM_MAKINUM (int @var{i})
635 Given a C integer @var{i}, return its representation as an @code{SCM}.
636 This function does not check for overflow.
641 @subsubsection Characters
643 Here are functions for operating on characters.
645 @deftypefn Macro int SCM_CHARP (SCM @var{x})
646 Return non-zero iff @var{x} is a character value.
649 @deftypefn Macro {unsigned int} SCM_CHAR (SCM @var{x})
650 Return the value of @code{x} as a C character. If @var{x} is not a
651 Scheme character, the result is undefined.
654 @deftypefn Macro SCM SCM_MAKE_CHAR (int @var{c})
655 Given a C character @var{c}, return its representation as a Scheme
661 @subsubsection Booleans
663 Here are functions and macros for operating on booleans.
665 @deftypefn Macro SCM SCM_BOOL_T
666 @deftypefnx Macro SCM SCM_BOOL_F
667 The Scheme true and false values.
670 @deftypefn Macro int SCM_NFALSEP (@var{x})
671 Convert the Scheme boolean value to a C boolean. Since every object in
672 Scheme except @code{#f} is true, this amounts to comparing @var{x} to
673 @code{#f}; hence the name.
674 @c Noel feels a chill here.
677 @deftypefn Macro SCM SCM_BOOL_NOT (@var{x})
678 Return the boolean inverse of @var{x}. If @var{x} is not a
679 Scheme boolean, the result is undefined.
684 @subsubsection Unique Values
686 The immediate values that are neither small integers, characters, nor
687 booleans are all unique values --- that is, datatypes with only one
690 @deftypefn Macro SCM SCM_EOL
691 The Scheme empty list object, or ``End Of List'' object, usually written
692 in Scheme as @code{'()}.
695 @deftypefn Macro SCM SCM_EOF_VAL
696 The Scheme end-of-file value. It has no standard written
697 representation, for obvious reasons.
700 @deftypefn Macro SCM SCM_UNSPECIFIED
701 The value returned by expressions which the Scheme standard says return
702 an ``unspecified'' value.
704 This is sort of a weirdly literal way to take things, but the standard
705 read-eval-print loop prints nothing when the expression returns this
706 value, so it's not a bad idea to return this when you can't think of
707 anything else helpful.
710 @deftypefn Macro SCM SCM_UNDEFINED
711 The ``undefined'' value. Its most important property is that is not
712 equal to any valid Scheme value. This is put to various internal uses
713 by C code interacting with Guile.
715 For example, when you write a C function that is callable from Scheme
716 and which takes optional arguments, the interpreter passes
717 @code{SCM_UNDEFINED} for any arguments you did not receive.
719 We also use this to mark unbound variables.
722 @deftypefn Macro int SCM_UNBNDP (SCM @var{x})
723 Return true if @var{x} is @code{SCM_UNDEFINED}. Apply this to a
724 symbol's value to see if it has a binding as a global variable.
728 @node Non-immediate Datatypes
729 @subsection Non-immediate Datatypes
731 A non-immediate datatype is one which lives in the heap, either because
732 it cannot fit entirely within a @code{SCM} word, or because it denotes a
733 specific storage location (in the nomenclature of the Revised^5 Report
736 The @code{SCM_IMP} and @code{SCM_NIMP} macros will distinguish these
737 from immediates; see @ref{Immediates vs Non-immediates}.
739 Given a cell, Guile distinguishes between pairs and other non-immediate
740 types by storing special @dfn{tag} values in a non-pair cell's car, that
741 cannot appear in normal pairs. A cell with a non-tag value in its car
742 is an ordinary pair. The type of a cell with a tag in its car depends
743 on the tag; the non-immediate type predicates test this value. If a tag
744 value appears elsewhere (in a vector, for example), the heap may become
747 Note how the type information for a non-immediate object is split
748 between the @code{SCM} word and the cell that the @code{SCM} word points
749 to. The @code{SCM} word itself only indicates that the object is
750 non-immediate --- in other words stored in a heap cell. The tag stored
751 in the first word of the heap cell indicates more precisely the type of
754 The type predicates for non-immediate values work correctly on any
755 @code{SCM} value; you do not need to call @code{SCM_NIMP} first, to
756 establish that a value is non-immediate.
771 Pairs are the essential building block of list structure in Scheme. A
772 pair object has two fields, called the @dfn{car} and the @dfn{cdr}.
774 It is conventional for a pair's @sc{car} to contain an element of a
775 list, and the @sc{cdr} to point to the next pair in the list, or to
776 contain @code{SCM_EOL}, indicating the end of the list. Thus, a set of
777 pairs chained through their @sc{cdr}s constitutes a singly-linked list.
778 Scheme and libguile define many functions which operate on lists
779 constructed in this fashion, so although lists chained through the
780 @sc{car}s of pairs will work fine too, they may be less convenient to
781 manipulate, and receive less support from the community.
783 Guile implements pairs by mapping the @sc{car} and @sc{cdr} of a pair
784 directly into the two words of the cell.
787 @deftypefn Macro int SCM_CONSP (SCM @var{x})
788 Return non-zero iff @var{x} is a Scheme pair object.
791 @deftypefn Macro int SCM_NCONSP (SCM @var{x})
792 The complement of SCM_CONSP.
795 @deftypefun SCM scm_cons (SCM @var{car}, SCM @var{cdr})
796 Allocate (``CONStruct'') a new pair, with @var{car} and @var{cdr} as its
800 The macros below perform no type checking. The results are undefined if
801 @var{cell} is an immediate. However, since all non-immediate Guile
802 objects are constructed from cells, and these macros simply return the
803 first element of a cell, they actually can be useful on datatypes other
804 than pairs. (Of course, it is not very modular to use them outside of
805 the code which implements that datatype.)
807 @deftypefn Macro SCM SCM_CAR (SCM @var{cell})
808 Return the @sc{car}, or first field, of @var{cell}.
811 @deftypefn Macro SCM SCM_CDR (SCM @var{cell})
812 Return the @sc{cdr}, or second field, of @var{cell}.
815 @deftypefn Macro void SCM_SETCAR (SCM @var{cell}, SCM @var{x})
816 Set the @sc{car} of @var{cell} to @var{x}.
819 @deftypefn Macro void SCM_SETCDR (SCM @var{cell}, SCM @var{x})
820 Set the @sc{cdr} of @var{cell} to @var{x}.
823 @deftypefn Macro SCM SCM_CAAR (SCM @var{cell})
824 @deftypefnx Macro SCM SCM_CADR (SCM @var{cell})
825 @deftypefnx Macro SCM SCM_CDAR (SCM @var{cell}) @dots{}
826 @deftypefnx Macro SCM SCM_CDDDDR (SCM @var{cell})
827 Return the @sc{car} of the @sc{car} of @var{cell}, the @sc{car} of the
828 @sc{cdr} of @var{cell}, @i{et cetera}.
833 @subsubsection Vectors, Strings, and Symbols
835 Vectors, strings, and symbols have some properties in common. They all
836 have a length, and they all have an array of elements. In the case of a
837 vector, the elements are @code{SCM} values; in the case of a string or
838 symbol, the elements are characters.
840 All these types store their length (along with some tagging bits) in the
841 @sc{car} of their header cell, and store a pointer to the elements in
842 their @sc{cdr}. Thus, the @code{SCM_CAR} and @code{SCM_CDR} macros
843 are (somewhat) meaningful when applied to these datatypes.
845 @deftypefn Macro int SCM_VECTORP (SCM @var{x})
846 Return non-zero iff @var{x} is a vector.
849 @deftypefn Macro int SCM_STRINGP (SCM @var{x})
850 Return non-zero iff @var{x} is a string.
853 @deftypefn Macro int SCM_SYMBOLP (SCM @var{x})
854 Return non-zero iff @var{x} is a symbol.
857 @deftypefn Macro int SCM_VECTOR_LENGTH (SCM @var{x})
858 @deftypefnx Macro int SCM_STRING_LENGTH (SCM @var{x})
859 @deftypefnx Macro int SCM_SYMBOL_LENGTH (SCM @var{x})
860 Return the length of the object @var{x}. The result is undefined if
861 @var{x} is not a vector, string, or symbol, respectively.
864 @deftypefn Macro {SCM *} SCM_VECTOR_BASE (SCM @var{x})
865 Return a pointer to the array of elements of the vector @var{x}.
866 The result is undefined if @var{x} is not a vector.
869 @deftypefn Macro {char *} SCM_STRING_CHARS (SCM @var{x})
870 @deftypefnx Macro {char *} SCM_SYMBOL_CHARS (SCM @var{x})
871 Return a pointer to the characters of @var{x}. The result is undefined
872 if @var{x} is not a symbol or string, respectively.
875 There are also a few magic values stuffed into memory before a symbol's
876 characters, but you don't want to know about those. What cruft!
880 @subsubsection Procedures
882 Guile provides two kinds of procedures: @dfn{closures}, which are the
883 result of evaluating a @code{lambda} expression, and @dfn{subrs}, which
884 are C functions packaged up as Scheme objects, to make them available to
887 (There are actually other sorts of procedures: compiled closures, and
888 continuations; see the source code for details about them.)
890 @deftypefun SCM scm_procedure_p (SCM @var{x})
891 Return @code{SCM_BOOL_T} iff @var{x} is a Scheme procedure object, of
892 any sort. Otherwise, return @code{SCM_BOOL_F}.
897 @subsubsection Closures
899 [FIXME: this needs to be further subbed, but texinfo has no subsubsub]
901 A closure is a procedure object, generated as the value of a
902 @code{lambda} expression in Scheme. The representation of a closure is
903 straightforward --- it contains a pointer to the code of the lambda
904 expression from which it was created, and a pointer to the environment
907 In Guile, each closure also has a property list, allowing the system to
908 store information about the closure. I'm not sure what this is used for
909 at the moment --- the debugger, maybe?
911 @deftypefn Macro int SCM_CLOSUREP (SCM @var{x})
912 Return non-zero iff @var{x} is a closure.
915 @deftypefn Macro SCM SCM_PROCPROPS (SCM @var{x})
916 Return the property list of the closure @var{x}. The results are
917 undefined if @var{x} is not a closure.
920 @deftypefn Macro void SCM_SETPROCPROPS (SCM @var{x}, SCM @var{p})
921 Set the property list of the closure @var{x} to @var{p}. The results
922 are undefined if @var{x} is not a closure.
925 @deftypefn Macro SCM SCM_CODE (SCM @var{x})
926 Return the code of the closure @var{x}. The result is undefined if
927 @var{x} is not a closure.
929 This function should probably only be used internally by the
930 interpreter, since the representation of the code is intimately
931 connected with the interpreter's implementation.
934 @deftypefn Macro SCM SCM_ENV (SCM @var{x})
935 Return the environment enclosed by @var{x}.
936 The result is undefined if @var{x} is not a closure.
938 This function should probably only be used internally by the
939 interpreter, since the representation of the environment is intimately
940 connected with the interpreter's implementation.
947 [FIXME: this needs to be further subbed, but texinfo has no subsubsub]
949 A subr is a pointer to a C function, packaged up as a Scheme object to
950 make it callable by Scheme code. In addition to the function pointer,
951 the subr also contains a pointer to the name of the function, and
952 information about the number of arguments accepted by the C function, for
953 the sake of error checking.
955 There is no single type predicate macro that recognizes subrs, as
956 distinct from other kinds of procedures. The closest thing is
957 @code{scm_procedure_p}; see @ref{Procedures}.
959 @deftypefn Macro {char *} SCM_SNAME (@var{x})
960 Return the name of the subr @var{x}. The result is undefined if
961 @var{x} is not a subr.
964 @deftypefun SCM scm_make_gsubr (char *@var{name}, int @var{req}, int @var{opt}, int @var{rest}, SCM (*@var{function})())
965 Create a new subr object named @var{name}, based on the C function
966 @var{function}, make it visible to Scheme the value of as a global
967 variable named @var{name}, and return the subr object.
969 The subr object accepts @var{req} required arguments, @var{opt} optional
970 arguments, and a @var{rest} argument iff @var{rest} is non-zero. The C
971 function @var{function} should accept @code{@var{req} + @var{opt}}
972 arguments, or @code{@var{req} + @var{opt} + 1} arguments if @code{rest}
975 When a subr object is applied, it must be applied to at least @var{req}
976 arguments, or else Guile signals an error. @var{function} receives the
977 subr's first @var{req} arguments as its first @var{req} arguments. If
978 there are fewer than @var{opt} arguments remaining, then @var{function}
979 receives the value @code{SCM_UNDEFINED} for any missing optional
980 arguments. If @var{rst} is non-zero, then any arguments after the first
981 @code{@var{req} + @var{opt}} are packaged up as a list as passed as
982 @var{function}'s last argument.
984 Note that subrs can actually only accept a predefined set of
985 combinations of required, optional, and rest arguments. For example, a
986 subr can take one required argument, or one required and one optional
987 argument, but a subr can't take one required and two optional arguments.
988 It's bizarre, but that's the way the interpreter was written. If the
989 arguments to @code{scm_make_gsubr} do not fit one of the predefined
990 patterns, then @code{scm_make_gsubr} will return a compiled closure
991 object instead of a subr object.
998 Haven't written this yet, 'cos I don't understand ports yet.
1001 @node Signalling Type Errors
1002 @subsection Signalling Type Errors
1004 Every function visible at the Scheme level should aggressively check the
1005 types of its arguments, to avoid misinterpreting a value, and perhaps
1006 causing a segmentation fault. Guile provides some macros to make this
1009 @deftypefn Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr})
1010 If @var{test} is zero, signal a ``wrong type argument'' error,
1011 attributed to the subroutine named @var{subr}, operating on the value
1012 @var{obj}, which is the @var{position}'th argument of @var{subr}.
1015 @deftypefn Macro int SCM_ARG1
1016 @deftypefnx Macro int SCM_ARG2
1017 @deftypefnx Macro int SCM_ARG3
1018 @deftypefnx Macro int SCM_ARG4
1019 @deftypefnx Macro int SCM_ARG5
1020 @deftypefnx Macro int SCM_ARG6
1021 @deftypefnx Macro int SCM_ARG7
1022 One of the above values can be used for @var{position} to indicate the
1023 number of the argument of @var{subr} which is being checked.
1024 Alternatively, a positive integer number can be used, which allows to
1025 check arguments after the seventh. However, for parameter numbers up to
1026 seven it is preferable to use @code{SCM_ARGN} instead of the
1027 corresponding raw number, since it will make the code easier to
1031 @deftypefn Macro int SCM_ARGn
1032 Passing a value of zero or @code{SCM_ARGn} for @var{position} allows to
1033 leave it unspecified which argument's type is incorrect. Again,
1034 @code{SCM_ARGn} should be preferred over a raw zero constant.
1038 @node Unpacking the SCM type
1039 @subsection Unpacking the SCM Type
1041 The previous sections have explained how @code{SCM} values can refer to
1042 immediate and non-immediate Scheme objects. For immediate objects, the
1043 complete object value is stored in the @code{SCM} word itself, while for
1044 non-immediates, the @code{SCM} word contains a pointer to a heap cell,
1045 and further information about the object in question is stored in that
1046 cell. This section describes how the @code{SCM} type is actually
1047 represented and used at the C level.
1049 In fact, there are two basic C data types to represent objects in Guile:
1053 @code{SCM} is the user level abstract C type that is used to represent
1054 all of Guile's Scheme objects, no matter what the Scheme object type is.
1055 No C operation except assignment is guaranteed to work with variables of
1056 type @code{SCM}, so you should only use macros and functions to work
1057 with @code{SCM} values. Values are converted between C data types and
1058 the @code{SCM} type with utility functions and macros.
1061 @code{scm_t_bits} is an integral data type that is guaranteed to be
1062 large enough to hold all information that is required to represent any
1063 Scheme object. While this data type is mostly used to implement Guile's
1064 internals, the use of this type is also necessary to write certain kinds
1065 of extensions to Guile.
1069 * Relationship between SCM and scm_t_bits::
1070 * Immediate objects::
1071 * Non-immediate objects::
1072 * Allocating Cells::
1073 * Heap Cell Type Information::
1074 * Accessing Cell Entries::
1075 * Basic Rules for Accessing Cell Entries::
1079 @node Relationship between SCM and scm_t_bits
1080 @subsubsection Relationship between @code{SCM} and @code{scm_t_bits}
1082 A variable of type @code{SCM} is guaranteed to hold a valid Scheme
1083 object. A variable of type @code{scm_t_bits}, on the other hand, may
1084 hold a representation of a @code{SCM} value as a C integral type, but
1085 may also hold any C value, even if it does not correspond to a valid
1088 For a variable @var{x} of type @code{SCM}, the Scheme object's type
1089 information is stored in a form that is not directly usable. To be able
1090 to work on the type encoding of the scheme value, the @code{SCM}
1091 variable has to be transformed into the corresponding representation as
1092 a @code{scm_t_bits} variable @var{y} by using the @code{SCM_UNPACK}
1093 macro. Once this has been done, the type of the scheme object @var{x}
1094 can be derived from the content of the bits of the @code{scm_t_bits}
1095 value @var{y}, in the way illustrated by the example earlier in this
1096 chapter (@pxref{Cheaper Pairs}). Conversely, a valid bit encoding of a
1097 Scheme value as a @code{scm_t_bits} variable can be transformed into the
1098 corresponding @code{SCM} value using the @code{SCM_PACK} macro.
1100 @deftypefn Macro scm_t_bits SCM_UNPACK (SCM @var{x})
1101 Transforms the @code{SCM} value @var{x} into its representation as an
1102 integral type. Only after applying @code{SCM_UNPACK} it is possible to
1103 access the bits and contents of the @code{SCM} value.
1106 @deftypefn Macro SCM SCM_PACK (scm_t_bits @var{x})
1107 Takes a valid integral representation of a Scheme object and transforms
1108 it into its representation as a @code{SCM} value.
1112 @node Immediate objects
1113 @subsubsection Immediate objects
1115 A Scheme object may either be an immediate, i.e. carrying all necessary
1116 information by itself, or it may contain a reference to a @dfn{cell}
1117 with additional information on the heap. Although in general it should
1118 be irrelevant for user code whether an object is an immediate or not,
1119 within Guile's own code the distinction is sometimes of importance.
1120 Thus, the following low level macro is provided:
1122 @deftypefn Macro int SCM_IMP (SCM @var{x})
1123 A Scheme object is an immediate if it fulfills the @code{SCM_IMP}
1124 predicate, otherwise it holds an encoded reference to a heap cell. The
1125 result of the predicate is delivered as a C style boolean value. User
1126 code and code that extends Guile should normally not be required to use
1134 Given a Scheme object @var{x} of unknown type, check first
1135 with @code{SCM_IMP (@var{x})} if it is an immediate object.
1137 If so, all of the type and value information can be determined from the
1138 @code{scm_t_bits} value that is delivered by @code{SCM_UNPACK
1143 @node Non-immediate objects
1144 @subsubsection Non-immediate objects
1146 A Scheme object of type @code{SCM} that does not fulfill the
1147 @code{SCM_IMP} predicate holds an encoded reference to a heap cell.
1148 This reference can be decoded to a C pointer to a heap cell using the
1149 @code{SCM2PTR} macro. The encoding of a pointer to a heap cell into a
1150 @code{SCM} value is done using the @code{PTR2SCM} macro.
1152 @c (FIXME:: this name should be changed)
1153 @deftypefn Macro (scm_t_cell *) SCM2PTR (SCM @var{x})
1154 Extract and return the heap cell pointer from a non-immediate @code{SCM}
1158 @c (FIXME:: this name should be changed)
1159 @deftypefn Macro SCM PTR2SCM (scm_t_cell * @var{x})
1160 Return a @code{SCM} value that encodes a reference to the heap cell
1164 Note that it is also possible to transform a non-immediate @code{SCM}
1165 value by using @code{SCM_UNPACK} into a @code{scm_t_bits} variable.
1166 However, the result of @code{SCM_UNPACK} may not be used as a pointer to
1167 a @code{scm_t_cell}: only @code{SCM2PTR} is guaranteed to transform a
1168 @code{SCM} object into a valid pointer to a heap cell. Also, it is not
1169 allowed to apply @code{PTR2SCM} to anything that is not a valid pointer
1176 Only use @code{SCM2PTR} on @code{SCM} values for which @code{SCM_IMP} is
1179 Don't use @code{(scm_t_cell *) SCM_UNPACK (@var{x})}! Use @code{SCM2PTR
1182 Don't use @code{PTR2SCM} for anything but a cell pointer!
1185 @node Allocating Cells
1186 @subsubsection Allocating Cells
1188 Guile provides both ordinary cells with two slots, and double cells
1189 with four slots. The following two function are the most primitive
1190 way to allocate such cells.
1192 If the caller intends to use it as a header for some other type, she
1193 must pass an appropriate magic value in @var{word_0}, to mark it as a
1194 member of that type, and pass whatever value as @var{word_1}, etc that
1195 the type expects. You should generally not need these functions,
1196 unless you are implementing a new datatype, and thoroughly understand
1197 the code in @code{<libguile/tags.h>}.
1199 If you just want to allocate pairs, use @code{scm_cons}.
1201 @deftypefn Function SCM scm_cell (scm_t_bits word_0, scm_t_bits word_1)
1202 Allocate a new cell, initialize the two slots with @var{word_0} and
1203 @var{word_1}, and return it.
1205 Note that @var{word_0} and @var{word_1} are of type @code{scm_t_bits}.
1206 If you want to pass a @code{SCM} object, you need to use
1210 @deftypefn Function SCM scm_double_cell (scm_t_bits word_0, scm_t_bits word_1, scm_t_bits word_2, scm_t_bits word_3)
1211 Like @code{scm_cell}, but allocates a double cell with four
1215 @node Heap Cell Type Information
1216 @subsubsection Heap Cell Type Information
1218 Heap cells contain a number of entries, each of which is either a scheme
1219 object of type @code{SCM} or a raw C value of type @code{scm_t_bits}.
1220 Which of the cell entries contain Scheme objects and which contain raw C
1221 values is determined by the first entry of the cell, which holds the
1222 cell type information.
1224 @deftypefn Macro scm_t_bits SCM_CELL_TYPE (SCM @var{x})
1225 For a non-immediate Scheme object @var{x}, deliver the content of the
1226 first entry of the heap cell referenced by @var{x}. This value holds
1227 the information about the cell type.
1230 @deftypefn Macro void SCM_SET_CELL_TYPE (SCM @var{x}, scm_t_bits @var{t})
1231 For a non-immediate Scheme object @var{x}, write the value @var{t} into
1232 the first entry of the heap cell referenced by @var{x}. The value
1233 @var{t} must hold a valid cell type.
1237 @node Accessing Cell Entries
1238 @subsubsection Accessing Cell Entries
1240 For a non-immediate Scheme object @var{x}, the object type can be
1241 determined by reading the cell type entry using the @code{SCM_CELL_TYPE}
1242 macro. For each different type of cell it is known which cell entries
1243 hold Scheme objects and which cell entries hold raw C data. To access
1244 the different cell entries appropriately, the following macros are
1247 @deftypefn Macro scm_t_bits SCM_CELL_WORD (SCM @var{x}, unsigned int @var{n})
1248 Deliver the cell entry @var{n} of the heap cell referenced by the
1249 non-immediate Scheme object @var{x} as raw data. It is illegal, to
1250 access cell entries that hold Scheme objects by using these macros. For
1251 convenience, the following macros are also provided.
1254 SCM_CELL_WORD_0 (@var{x}) @result{} SCM_CELL_WORD (@var{x}, 0)
1256 SCM_CELL_WORD_1 (@var{x}) @result{} SCM_CELL_WORD (@var{x}, 1)
1260 SCM_CELL_WORD_@var{n} (@var{x}) @result{} SCM_CELL_WORD (@var{x}, @var{n})
1264 @deftypefn Macro SCM SCM_CELL_OBJECT (SCM @var{x}, unsigned int @var{n})
1265 Deliver the cell entry @var{n} of the heap cell referenced by the
1266 non-immediate Scheme object @var{x} as a Scheme object. It is illegal,
1267 to access cell entries that do not hold Scheme objects by using these
1268 macros. For convenience, the following macros are also provided.
1271 SCM_CELL_OBJECT_0 (@var{x}) @result{} SCM_CELL_OBJECT (@var{x}, 0)
1273 SCM_CELL_OBJECT_1 (@var{x}) @result{} SCM_CELL_OBJECT (@var{x}, 1)
1277 SCM_CELL_OBJECT_@var{n} (@var{x}) @result{} SCM_CELL_OBJECT (@var{x},
1282 @deftypefn Macro void SCM_SET_CELL_WORD (SCM @var{x}, unsigned int @var{n}, scm_t_bits @var{w})
1283 Write the raw C value @var{w} into entry number @var{n} of the heap cell
1284 referenced by the non-immediate Scheme value @var{x}. Values that are
1285 written into cells this way may only be read from the cells using the
1286 @code{SCM_CELL_WORD} macros or, in case cell entry 0 is written, using
1287 the @code{SCM_CELL_TYPE} macro. For the special case of cell entry 0 it
1288 has to be made sure that @var{w} contains a cell type information which
1289 does not describe a Scheme object. For convenience, the following
1290 macros are also provided.
1293 SCM_SET_CELL_WORD_0 (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
1294 (@var{x}, 0, @var{w})
1296 SCM_SET_CELL_WORD_1 (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
1297 (@var{x}, 1, @var{w})
1301 SCM_SET_CELL_WORD_@var{n} (@var{x}, @var{w}) @result{} SCM_SET_CELL_WORD
1302 (@var{x}, @var{n}, @var{w})
1306 @deftypefn Macro void SCM_SET_CELL_OBJECT (SCM @var{x}, unsigned int @var{n}, SCM @var{o})
1307 Write the Scheme object @var{o} into entry number @var{n} of the heap
1308 cell referenced by the non-immediate Scheme value @var{x}. Values that
1309 are written into cells this way may only be read from the cells using
1310 the @code{SCM_CELL_OBJECT} macros or, in case cell entry 0 is written,
1311 using the @code{SCM_CELL_TYPE} macro. For the special case of cell
1312 entry 0 the writing of a Scheme object into this cell is only allowed
1313 if the cell forms a Scheme pair. For convenience, the following macros
1317 SCM_SET_CELL_OBJECT_0 (@var{x}, @var{o}) @result{} SCM_SET_CELL_OBJECT
1318 (@var{x}, 0, @var{o})
1320 SCM_SET_CELL_OBJECT_1 (@var{x}, @var{o}) @result{} SCM_SET_CELL_OBJECT
1321 (@var{x}, 1, @var{o})
1325 SCM_SET_CELL_OBJECT_@var{n} (@var{x}, @var{o}) @result{}
1326 SCM_SET_CELL_OBJECT (@var{x}, @var{n}, @var{o})
1334 For a non-immediate Scheme object @var{x} of unknown type, get the type
1335 information by using @code{SCM_CELL_TYPE (@var{x})}.
1337 As soon as the cell type information is available, only use the
1338 appropriate access methods to read and write data to the different cell
1343 @node Basic Rules for Accessing Cell Entries
1344 @subsubsection Basic Rules for Accessing Cell Entries
1346 For each cell type it is generally up to the implementation of that type
1347 which of the corresponding cell entries hold Scheme objects and which
1348 hold raw C values. However, there is one basic rule that has to be
1349 followed: Scheme pairs consist of exactly two cell entries, which both
1350 contain Scheme objects. Further, a cell which contains a Scheme object
1351 in it first entry has to be a Scheme pair. In other words, it is not
1352 allowed to store a Scheme object in the first cell entry and a non
1353 Scheme object in the second cell entry.
1355 @c Fixme:shouldn't this rather be SCM_PAIRP / SCM_PAIR_P ?
1356 @deftypefn Macro int SCM_CONSP (SCM @var{x})
1357 Determine, whether the Scheme object @var{x} is a Scheme pair,
1358 i.e. whether @var{x} references a heap cell consisting of exactly two
1359 entries, where both entries contain a Scheme object. In this case, both
1360 entries will have to be accessed using the @code{SCM_CELL_OBJECT}
1361 macros. On the contrary, if the @code{SCM_CONSP} predicate is not
1362 fulfilled, the first entry of the Scheme cell is guaranteed not to be a
1363 Scheme value and thus the first cell entry must be accessed using the
1364 @code{SCM_CELL_WORD_0} macro.
1368 @node Defining New Types (Smobs)
1369 @section Defining New Types (Smobs)
1371 @dfn{Smobs} are Guile's mechanism for adding new non-immediate types to
1372 the system.@footnote{The term ``smob'' was coined by Aubrey Jaffer, who
1373 says it comes from ``small object'', referring to the fact that only the
1374 @sc{cdr} and part of the @sc{car} of a smob's cell are available for
1375 use.} To define a new smob type, the programmer provides Guile with
1376 some essential information about the type --- how to print it, how to
1377 garbage collect it, and so on --- and Guile returns a fresh type tag for
1378 use in the first word of new cells. The programmer can then use
1379 @code{scm_c_define_gsubr} to make a set of C functions that create and
1380 operate on these objects visible to Scheme code.
1382 (You can find a complete version of the example code used in this
1383 section in the Guile distribution, in @file{doc/example-smob}. That
1384 directory includes a makefile and a suitable @code{main} function, so
1385 you can build a complete interactive Guile shell, extended with the
1386 datatypes described here.)
1389 * Describing a New Type::
1390 * Creating Instances::
1392 * Garbage Collecting Smobs::
1393 * A Common Mistake In Allocating Smobs::
1394 * Garbage Collecting Simple Smobs::
1395 * A Complete Example::
1398 @node Describing a New Type
1399 @subsection Describing a New Type
1401 To define a new type, the programmer must write four functions to
1402 manage instances of the type:
1406 Guile will apply this function to each instance of the new type it
1407 encounters during garbage collection. This function is responsible for
1408 telling the collector about any other non-immediate objects the object
1409 refers to. The default smob mark function is to not mark any data.
1410 @xref{Garbage Collecting Smobs}, for more details.
1413 Guile will apply this function to each instance of the new type it
1414 could not find any live pointers to. The function should release all
1415 resources held by the object and return the number of bytes released.
1416 This is analogous to the Java finalization method-- it is invoked at
1417 an unspecified time (when garbage collection occurs) after the object
1418 is dead. The default free function frees the smob data (if the size
1419 of the struct passed to @code{scm_make_smob_type} is non-zero) using
1420 @code{scm_gc_free}. @xref{Garbage Collecting Smobs}, for more
1424 @c GJB:FIXME:: @var{exp} and @var{port} need to refer to a prototype of
1425 @c the print function.... where is that, or where should it go?
1426 Guile will apply this function to each instance of the new type to print
1427 the value, as for @code{display} or @code{write}. The function should
1428 write a printed representation of @var{exp} on @var{port}, in accordance
1429 with the parameters in @var{pstate}. (For more information on print
1430 states, see @ref{Port Data}.) The default print function prints
1431 @code{#<NAME ADDRESS>} where @code{NAME} is the first argument passed to
1432 @code{scm_make_smob_type}.
1435 If Scheme code asks the @code{equal?} function to compare two instances
1436 of the same smob type, Guile calls this function. It should return
1437 @code{SCM_BOOL_T} if @var{a} and @var{b} should be considered
1438 @code{equal?}, or @code{SCM_BOOL_F} otherwise. If @code{equalp} is
1439 @code{NULL}, @code{equal?} will assume that two instances of this type are
1440 never @code{equal?} unless they are @code{eq?}.
1444 To actually register the new smob type, call @code{scm_make_smob_type}:
1446 @deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size)
1447 This function implements the standard way of adding a new smob type,
1448 named @var{name}, with instance size @var{size}, to the system. The
1449 return value is a tag that is used in creating instances of the type.
1450 If @var{size} is 0, then no memory will be allocated when instances of
1451 the smob are created, and nothing will be freed by the default free
1452 function. Default values are provided for mark, free, print, and,
1453 equalp, as described above. If you want to customize any of these
1454 functions, the call to @code{scm_make_smob_type} should be immediately
1455 followed by calls to one or several of @code{scm_set_smob_mark},
1456 @code{scm_set_smob_free}, @code{scm_set_smob_print}, and/or
1457 @code{scm_set_smob_equalp}.
1460 Each of the below @code{scm_set_smob_XXX} functions registers a smob
1461 special function for a given type. Each function is intended to be used
1462 only zero or one time per type, and the call should be placed
1463 immediately following the call to @code{scm_make_smob_type}.
1465 @deftypefun void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM))
1466 This function sets the smob marking procedure for the smob type specified by
1467 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1470 @deftypefun void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM))
1471 This function sets the smob freeing procedure for the smob type specified by
1472 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1475 @deftypefun void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM, SCM, scm_print_state*))
1476 This function sets the smob printing procedure for the smob type specified by
1477 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1480 @deftypefun void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM))
1481 This function sets the smob equality-testing predicate for the smob type specified by
1482 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1485 In versions 1.4 and earlier, there was another way of creating smob
1486 types, using @code{scm_make_smob_type_mfpe}. This function is now
1487 deprecated and will be removed in a future version of Guile. You should
1488 use the mechanism described above for new code, and change old code not
1489 to use deprecated features.
1491 Instead of using @code{scm_make_smob_type} and calling each of the
1492 individual @code{scm_set_smob_XXX} functions to register each special
1493 function independently, you could use @code{scm_make_smob_type_mfpe} to
1494 register all of the special functions at once as you create the smob
1497 @deftypefun long scm_make_smob_type_mfpe(const char *name, size_t size, SCM (*mark) (SCM), size_t (*free) (SCM), int (*print) (SCM, SCM, scm_print_state*), SCM (*equalp) (SCM, SCM))
1498 This function invokes @code{scm_make_smob_type} on its first two arguments
1499 to add a new smob type named @var{name}, with instance size @var{size} to the system.
1500 It also registers the @var{mark}, @var{free}, @var{print}, @var{equalp} smob
1501 special functions for that new type. Any of these parameters can be @code{NULL}
1502 to have that special function use the default behavior for guile.
1503 The return value is a tag that is used in creating instances of the type. If @var{size}
1504 is 0, then no memory will be allocated when instances of the smob are created, and
1505 nothing will be freed by the default free function.
1508 For example, here is how one might declare and register a new type
1509 representing eight-bit gray-scale images:
1512 #include <libguile.h>
1514 static scm_t_bits image_tag;
1517 init_image_type (void)
1519 image_tag = scm_make_smob_type ("image", sizeof (struct image));
1520 scm_set_smob_mark (image_tag, mark_image);
1521 scm_set_smob_free (image_tag, free_image);
1522 scm_set_smob_print (image_tag, print_image);
1527 @node Creating Instances
1528 @subsection Creating Instances
1530 Like other non-immediate types, smobs start with a cell whose first word
1531 contains typing information, and whose remaining words are free for any
1534 After the header word containing the type code, smobs can have either
1535 one, two or three additional words of data. These words store either a
1536 pointer to the internal C structure holding the smob-specific data, or
1537 the smob data itself. To create an instance of a smob type following
1538 these standards, you should use @code{SCM_NEWSMOB}, @code{SCM_NEWSMOB2}
1539 or @code{SCM_NEWSMOB3}:@footnote{The @code{SCM_NEWSMOB2} and
1540 @code{SCM_NEWSMOB3} variants will allocate double cells and thus use
1541 twice as much memory as smobs created by @code{SCM_NEWSMOB}.}
1543 @deftypefn Macro void SCM_NEWSMOB(SCM value, scm_t_bits tag, void *data)
1544 @deftypefnx Macro void SCM_NEWSMOB2(SCM value, scm_t_bits tag, void *data1, void *data2)
1545 @deftypefnx Macro void SCM_NEWSMOB3(SCM value, scm_t_bits tag, void *data1, void *data2, void *data3)
1546 Make @var{value} contain a smob instance of the type with tag @var{tag}
1547 and smob data @var{data} (or @var{data1}, @var{data2}, and @var{data3}).
1548 @var{value} must be previously declared as C type @code{SCM}.
1551 Since it is often the case (e.g., in smob constructors) that you will
1552 create a smob instance and return it, there is also a slightly specialized
1553 macro for this situation:
1555 @deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(scm_t_bits tag, void *data)
1556 @deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB2(scm_t_bits tag, void *data1, void *data2)
1557 @deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_t_bits tag, void *data1, void *data2, void *data3)
1558 This macro expands to a block of code that creates a smob instance of
1559 the type with tag @var{tag} and smob data @var{data} (or @var{data1},
1560 @var{data2}, and @var{data3}), and causes the surrounding function to
1561 return that @code{SCM} value. It should be the last piece of code in
1565 Guile provides some functions for managing memory, which are often
1566 helpful when implementing smobs. @xref{Memory Blocks}.
1569 Continuing the above example, if the global variable @code{image_tag}
1570 contains a tag returned by @code{scm_make_smob_type}, here is how we
1571 could construct a smob whose @sc{cdr} contains a pointer to a freshly
1572 allocated @code{struct image}:
1579 /* The name of this image */
1582 /* A function to call when this image is
1583 modified, e.g., to update the screen,
1584 or SCM_BOOL_F if no action necessary */
1589 make_image (SCM name, SCM s_width, SCM s_height)
1591 struct image *image;
1594 SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
1595 SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
1596 SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
1598 width = SCM_INUM (s_width);
1599 height = SCM_INUM (s_height);
1601 image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
1602 image->width = width;
1603 image->height = height;
1604 image->pixels = scm_gc_malloc (width * height, "image pixels");
1606 image->update_func = SCM_BOOL_F;
1608 SCM_RETURN_NEWSMOB (image_tag, image);
1614 @subsection Type checking
1616 Functions that operate on smobs should aggressively check the types of
1617 their arguments, to avoid misinterpreting some other datatype as a smob,
1618 and perhaps causing a segmentation fault. Fortunately, this is pretty
1619 simple to do. The function need only verify that its argument is a
1620 non-immediate, whose first word is the type tag returned by
1621 @code{scm_make_smob_type}.
1623 For example, here is a simple function that operates on an image smob,
1624 and checks the type of its argument. We also present an expanded
1625 version of the @code{init_image_type} function, to make
1626 @code{clear_image} and the image constructor function @code{make_image}
1627 visible to Scheme code.
1631 clear_image (SCM image_smob)
1634 struct image *image;
1636 SCM_ASSERT (SCM_SMOB_PREDICATE (image_tag, image_smob),
1637 image_smob, SCM_ARG1, "clear-image");
1639 image = (struct image *) SCM_SMOB_DATA (image_smob);
1640 area = image->width * image->height;
1641 memset (image->pixels, 0, area);
1643 /* Invoke the image's update function. */
1644 if (image->update_func != SCM_BOOL_F)
1645 scm_apply (image->update_func, SCM_EOL, SCM_EOL);
1647 return SCM_UNSPECIFIED;
1652 init_image_type (void)
1654 image_tag = scm_make_smob_type ("image", sizeof (struct image));
1655 scm_set_smob_mark (image_tag, mark_image);
1656 scm_set_smob_free (image_tag, free_image);
1657 scm_set_smob_print (image_tag, print_image);
1659 scm_c_define_gsubr ("clear-image", 1, 0, 0, clear_image);
1660 scm_c_define_gsubr ("make-image", 3, 0, 0, make_image);
1664 @c GJB:FIXME:: should talk about guile-snarf somewhere!
1667 @node Garbage Collecting Smobs
1668 @subsection Garbage Collecting Smobs
1670 Once a smob has been released to the tender mercies of the Scheme
1671 system, it must be prepared to survive garbage collection. Guile calls
1672 the @code{mark} and @code{free} functions of the @code{scm_smobfuns}
1673 structure to manage this.
1675 As described before (@pxref{Conservative GC}), every object in the
1676 Scheme system has a @dfn{mark bit}, which the garbage collector uses to
1677 tell live objects from dead ones. When collection starts, every
1678 object's mark bit is clear. The collector traces pointers through the
1679 heap, starting from objects known to be live, and sets the mark bit on
1680 each object it encounters. When it can find no more unmarked objects,
1681 the collector walks all objects, live and dead, frees those whose mark
1682 bits are still clear, and clears the mark bit on the others.
1684 The two main portions of the collection are called the @dfn{mark phase},
1685 during which the collector marks live objects, and the @dfn{sweep
1686 phase}, during which the collector frees all unmarked objects.
1688 The mark bit of a smob lives in a special memory region. When the
1689 collector encounters a smob, it sets the smob's mark bit, and uses the
1690 smob's type tag to find the appropriate @code{mark} function for that
1691 smob: the one listed in that smob's @code{scm_smobfuns} structure. It
1692 then calls the @code{mark} function, passing it the smob as its only
1695 The @code{mark} function is responsible for marking any other Scheme
1696 objects the smob refers to. If it does not do so, the objects' mark
1697 bits will still be clear when the collector begins to sweep, and the
1698 collector will free them. If this occurs, it will probably break, or at
1699 least confuse, any code operating on the smob; the smob's @code{SCM}
1700 values will have become dangling references.
1702 To mark an arbitrary Scheme object, the @code{mark} function may call
1705 @deftypefun void scm_gc_mark (SCM @var{x})
1706 Mark the object @var{x}, and recurse on any objects @var{x} refers to.
1707 If @var{x}'s mark bit is already set, return immediately.
1710 Thus, here is how we might write the @code{mark} function for the image
1711 smob type discussed above:
1716 mark_image (SCM image_smob)
1718 /* Mark the image's name and update function. */
1719 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1721 scm_gc_mark (image->name);
1722 scm_gc_mark (image->update_func);
1729 Note that, even though the image's @code{update_func} could be an
1730 arbitrarily complex structure (representing a procedure and any values
1731 enclosed in its environment), @code{scm_gc_mark} will recurse as
1732 necessary to mark all its components. Because @code{scm_gc_mark} sets
1733 an object's mark bit before it recurses, it is not confused by
1734 circular structures.
1736 As an optimization, the collector will mark whatever value is returned
1737 by the @code{mark} function; this helps limit depth of recursion during
1738 the mark phase. Thus, the code above could also be written as:
1742 mark_image (SCM image_smob)
1744 /* Mark the image's name and update function. */
1745 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1747 scm_gc_mark (image->name);
1748 return image->update_func;
1754 Finally, when the collector encounters an unmarked smob during the sweep
1755 phase, it uses the smob's tag to find the appropriate @code{free}
1756 function for the smob. It then calls the function, passing it the smob
1757 as its only argument.
1759 The @code{free} function must release any resources used by the smob.
1760 However, it need not free objects managed by the collector; the
1761 collector will take care of them. For historical reasons, the return
1762 type of the @code{free} function should be @code{size_t}, an unsigned
1763 integral type; the @code{free} function should always return zero.
1765 Here is how we might write the @code{free} function for the image smob
1769 free_image (SCM image_smob)
1771 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1773 scm_gc_free (image->pixels, image->width * image->height, "image pixels");
1774 scm_gc_free (image, sizeof (struct image), "image");
1780 During the sweep phase, the garbage collector will clear the mark bits
1781 on all live objects. The code which implements a smob need not do this
1784 There is no way for smob code to be notified when collection is
1787 It is usually a good idea to minimize the amount of processing done
1788 during garbage collection; keep @code{mark} and @code{free} functions
1789 very simple. Since collections occur at unpredictable times, it is easy
1790 for any unusual activity to interfere with normal code.
1793 @node A Common Mistake In Allocating Smobs, Garbage Collecting Simple Smobs, Garbage Collecting Smobs, Defining New Types (Smobs)
1794 @subsection A Common Mistake In Allocating Smobs
1796 When constructing new objects, you must be careful that the garbage
1797 collector can always find any new objects you allocate. For example,
1798 suppose we wrote the @code{make_image} function this way:
1802 make_image (SCM name, SCM s_width, SCM s_height)
1804 struct image *image;
1808 SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
1809 SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
1810 SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
1812 width = SCM_INUM (s_width);
1813 height = SCM_INUM (s_height);
1815 image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
1816 image->width = width;
1817 image->height = height;
1818 image->pixels = scm_gc_malloc (width * height, "image pixels");
1820 /* THESE TWO LINES HAVE CHANGED: */
1821 image->name = scm_string_copy (name);
1822 image->update_func = scm_c_define_gsubr (@dots{});
1824 SCM_NEWCELL (image_smob);
1825 SCM_SET_CELL_WORD_1 (image_smob, image);
1826 SCM_SET_CELL_TYPE (image_smob, image_tag);
1832 This code is incorrect. The calls to @code{scm_string_copy} and
1833 @code{scm_c_define_gsubr} allocate fresh objects. Allocating any new object
1834 may cause the garbage collector to run. If @code{scm_c_define_gsubr}
1835 invokes a collection, the garbage collector has no way to discover that
1836 @code{image->name} points to the new string object; the @code{image}
1837 structure is not yet part of any Scheme object, so the garbage collector
1838 will not traverse it. Since the garbage collector cannot find any
1839 references to the new string object, it will free it, leaving
1840 @code{image} pointing to a dead object.
1842 A correct implementation might say, instead:
1845 image->name = SCM_BOOL_F;
1846 image->update_func = SCM_BOOL_F;
1848 SCM_NEWCELL (image_smob);
1849 SCM_SET_CELL_WORD_1 (image_smob, image);
1850 SCM_SET_CELL_TYPE (image_smob, image_tag);
1852 image->name = scm_string_copy (name);
1853 image->update_func = scm_c_define_gsubr (@dots{});
1858 Now, by the time we allocate the new string and function objects,
1859 @code{image_smob} points to @code{image}. If the garbage collector
1860 scans the stack, it will find a reference to @code{image_smob} and
1861 traverse @code{image}, so any objects @code{image} points to will be
1865 @node Garbage Collecting Simple Smobs, A Complete Example, A Common Mistake In Allocating Smobs, Defining New Types (Smobs)
1866 @subsection Garbage Collecting Simple Smobs
1868 It is often useful to define very simple smob types --- smobs which have
1869 no data to mark, other than the cell itself, or smobs whose first data
1870 word is simply an ordinary Scheme object, to be marked recursively.
1871 Guile provides some functions to handle these common cases; you can use
1872 this function as your smob type's @code{mark} function, if your smob's
1873 structure is simple enough.
1875 If the smob refers to no other Scheme objects, then no action is
1876 necessary; the garbage collector has already marked the smob cell
1877 itself. In that case, you can use zero as your mark function.
1879 @deftypefun SCM scm_markcdr (SCM @var{x})
1880 Mark the references in the smob @var{x}, assuming that @var{x}'s first
1881 data word contains an ordinary Scheme object, and @var{x} refers to no
1882 other objects. This function simply returns @var{x}'s first data word.
1884 This is only useful for simple smobs created by @code{SCM_NEWSMOB} or
1885 @code{SCM_RETURN_NEWSMOB}, not for smobs allocated as double cells.
1888 @deftypefun size_t scm_free0 (SCM @var{x})
1889 Do nothing; return zero. This function is appropriate for smobs that
1890 use either zero or @code{scm_markcdr} as their marking functions, and
1891 refer to no heap storage, including memory managed by @code{malloc},
1892 other than the smob's header cell.
1894 This function should not be needed anymore, because simply passing
1895 @code{NULL} as the free function does the same.
1899 @node A Complete Example
1900 @subsection A Complete Example
1902 Here is the complete text of the implementation of the image datatype,
1903 as presented in the sections above. We also provide a definition for
1904 the smob's @code{print} function, and make some objects and functions
1905 static, to clarify exactly what the surrounding code is using.
1907 As mentioned above, you can find this code in the Guile distribution, in
1908 @file{doc/example-smob}. That directory includes a makefile and a
1909 suitable @code{main} function, so you can build a complete interactive
1910 Guile shell, extended with the datatypes described here.)
1913 /* file "image-type.c" */
1916 #include <libguile.h>
1918 static scm_t_bits image_tag;
1924 /* The name of this image */
1927 /* A function to call when this image is
1928 modified, e.g., to update the screen,
1929 or SCM_BOOL_F if no action necessary */
1934 make_image (SCM name, SCM s_width, SCM s_height)
1936 struct image *image;
1939 SCM_ASSERT (SCM_STRINGP (name), name, SCM_ARG1, "make-image");
1940 SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
1941 SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
1943 width = SCM_INUM (s_width);
1944 height = SCM_INUM (s_height);
1946 image = (struct image *) scm_gc_malloc (sizeof (struct image), "image");
1947 image->width = width;
1948 image->height = height;
1949 image->pixels = scm_gc_malloc (width * height, "image pixels");
1951 image->update_func = SCM_BOOL_F;
1953 SCM_RETURN_NEWSMOB (image_tag, image);
1957 clear_image (SCM image_smob)
1960 struct image *image;
1962 SCM_ASSERT (SCM_SMOB_PREDICATE (image_tag, image_smob),
1963 image_smob, SCM_ARG1, "clear-image");
1965 image = (struct image *) SCM_SMOB_DATA (image_smob);
1966 area = image->width * image->height;
1967 memset (image->pixels, 0, area);
1969 /* Invoke the image's update function. */
1970 if (image->update_func != SCM_BOOL_F)
1971 scm_apply (image->update_func, SCM_EOL, SCM_EOL);
1973 return SCM_UNSPECIFIED;
1977 mark_image (SCM image_smob)
1979 /* Mark the image's name and update function. */
1980 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1982 scm_gc_mark (image->name);
1983 return image->update_func;
1987 free_image (SCM image_smob)
1989 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1991 scm_gc_free (image->pixels, image->width * image->height, "image pixels");
1992 scm_gc_free (image, sizeof (struct image), "image");
1998 print_image (SCM image_smob, SCM port, scm_print_state *pstate)
2000 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
2002 scm_puts ("#<image ", port);
2003 scm_display (image->name, port);
2004 scm_puts (">", port);
2006 /* non-zero means success */
2011 init_image_type (void)
2013 image_tag = scm_make_smob_type ("image", sizeof (struct image));
2014 scm_set_smob_mark (image_tag, mark_image);
2015 scm_set_smob_free (image_tag, free_image);
2016 scm_set_smob_print (image_tag, print_image);
2018 scm_c_define_gsubr ("clear-image", 1, 0, 0, clear_image);
2019 scm_c_define_gsubr ("make-image", 3, 0, 0, make_image);
2023 Here is a sample build and interaction with the code from the
2024 @file{example-smob} directory, on the author's machine:
2027 zwingli:example-smob$ make CC=gcc
2028 gcc `guile-config compile` -c image-type.c -o image-type.o
2029 gcc `guile-config compile` -c myguile.c -o myguile.o
2030 gcc image-type.o myguile.o `guile-config link` -o myguile
2031 zwingli:example-smob$ ./myguile
2033 #<primitive-procedure make-image>
2034 guile> (define i (make-image "Whistler's Mother" 100 100))
2036 #<image Whistler's Mother>
2037 guile> (clear-image i)
2038 guile> (clear-image 4)
2039 ERROR: In procedure clear-image in expression (clear-image 4):
2040 ERROR: Wrong type argument in position 1: 4
2041 ABORT: (wrong-type-arg)
2043 Type "(backtrace)" to get more information.