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 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.18 2001-04-02 21:53:20 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 slighty 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::
443 @subsection General Rules
445 Any code which operates on Guile datatypes must @code{#include} the
446 header file @code{<libguile.h>}. This file contains a definition for
447 the @code{SCM} typedef (Guile's universal type, as in the examples
448 above), and definitions and declarations for a host of macros and
449 functions that operate on @code{SCM} values.
451 All identifiers declared by @code{<libguile.h>} begin with @code{scm_}
454 @c [[I wish this were true, but I don't think it is at the moment. -JimB]]
455 @c Macros do not evaluate their arguments more than once, unless documented
458 The functions described here generally check the types of their
459 @code{SCM} arguments, and signal an error if their arguments are of an
460 inappropriate type. Macros generally do not, unless that is their
461 specified purpose. You must verify their argument types beforehand, as
464 Macros and functions that return a boolean value have names ending in
465 @code{P} or @code{_p} (for ``predicate''). Those that return a negated
466 boolean value have names starting with @code{SCM_N}. For example,
467 @code{SCM_IMP (@var{x})} is a predicate which returns non-zero iff
468 @var{x} is an immediate value (an @code{IM}). @code{SCM_NCONSP
469 (@var{x})} is a predicate which returns non-zero iff @var{x} is
470 @emph{not} a pair object (a @code{CONS}).
473 @node Conservative GC
474 @subsection Conservative Garbage Collection
476 Aside from the latent typing, the major source of constraints on a
477 Scheme implementation's data representation is the garbage collector.
478 The collector must be able to traverse every live object in the heap, to
479 determine which objects are not live.
481 There are many ways to implement this, but Guile uses an algorithm
482 called @dfn{mark and sweep}. The collector scans the system's global
483 variables and the local variables on the stack to determine which
484 objects are immediately accessible by the C code. It then scans those
485 objects to find the objects they point to, @i{et cetera}. The collector
486 sets a @dfn{mark bit} on each object it finds, so each object is
487 traversed only once. This process is called @dfn{tracing}.
489 When the collector can find no unmarked objects pointed to by marked
490 objects, it assumes that any objects that are still unmarked will never
491 be used by the program (since there is no path of dereferences from any
492 global or local variable that reaches them) and deallocates them.
494 In the above paragraphs, we did not specify how the garbage collector
495 finds the global and local variables; as usual, there are many different
496 approaches. Frequently, the programmer must maintain a list of pointers
497 to all global variables that refer to the heap, and another list
498 (adjusted upon entry to and exit from each function) of local variables,
499 for the collector's benefit.
501 The list of global variables is usually not too difficult to maintain,
502 since global variables are relatively rare. However, an explicitly
503 maintained list of local variables (in the author's personal experience)
504 is a nightmare to maintain. Thus, Guile uses a technique called
505 @dfn{conservative garbage collection}, to make the local variable list
508 The trick to conservative collection is to treat the stack as an
509 ordinary range of memory, and assume that @emph{every} word on the stack
510 is a pointer into the heap. Thus, the collector marks all objects whose
511 addresses appear anywhere in the stack, without knowing for sure how
512 that word is meant to be interpreted.
514 Obviously, such a system will occasionally retain objects that are
515 actually garbage, and should be freed. In practice, this is not a
516 problem. The alternative, an explicitly maintained list of local
517 variable addresses, is effectively much less reliable, due to programmer
520 To accommodate this technique, data must be represented so that the
521 collector can accurately determine whether a given stack word is a
522 pointer or not. Guile does this as follows:
526 Every heap object has a two-word header, called a @dfn{cell}. Some
527 objects, like pairs, fit entirely in a cell's two words; others may
528 store pointers to additional memory in either of the words. For
529 example, strings and vectors store their length in the first word, and a
530 pointer to their elements in the second.
533 Guile allocates whole arrays of cells at a time, called @dfn{heap
534 segments}. These segments are always allocated so that the cells they
535 contain fall on eight-byte boundaries, or whatever is appropriate for
536 the machine's word size. Guile keeps all cells in a heap segment
537 initialized, whether or not they are currently in use.
540 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 suprisingly, @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, as of Guile 1.4, it is no longer 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}. The definitions of all Guile type predicates
584 now include a call to @code{SCM_NIMP} where necessary.
587 @node Immediate Datatypes
588 @subsection Immediate Datatypes
590 The following datatypes are immediate values; that is, they fit entirely
591 within an @code{SCM} value. The @code{SCM_IMP} and @code{SCM_NIMP}
592 macros will distinguish these from non-immediates; see @ref{Immediates
593 vs Non-immediates} for an explanation of the distinction.
595 Note that the type predicates for immediate values work correctly on any
596 @code{SCM} value; you do not need to call @code{SCM_IMP} first, to
597 establish that a value is immediate. This differs from the
598 non-immediate type predicates, which work correctly only on
599 non-immediate values; you must be sure the value is @code{SCM_NIMP}
600 before applying them.
611 @subsubsection Integers
613 Here are functions for operating on small integers, that fit within an
614 @code{SCM}. Such integers are called @dfn{immediate numbers}, or
615 @dfn{INUMs}. In general, INUMs occupy all but two bits of an
618 Bignums and floating-point numbers are non-immediate objects, and have
619 their own, separate accessors. The functions here will not work on
620 them. This is not as much of a problem as you might think, however,
621 because the system never constructs bignums that could fit in an INUM,
622 and never uses floating point values for exact integers.
624 @deftypefn Macro int SCM_INUMP (SCM @var{x})
625 Return non-zero iff @var{x} is a small integer value.
628 @deftypefn Macro int SCM_NINUMP (SCM @var{x})
629 The complement of SCM_INUMP.
632 @deftypefn Macro int SCM_INUM (SCM @var{x})
633 Return the value of @var{x} as an ordinary, C integer. If @var{x}
634 is not an INUM, the result is undefined.
637 @deftypefn Macro SCM SCM_MAKINUM (int @var{i})
638 Given a C integer @var{i}, return its representation as an @code{SCM}.
639 This function does not check for overflow.
644 @subsubsection Characters
646 Here are functions for operating on characters.
648 @deftypefn Macro int SCM_CHARP (SCM @var{x})
649 Return non-zero iff @var{x} is a character value.
652 @deftypefn Macro {unsigned int} SCM_CHAR (SCM @var{x})
653 Return the value of @code{x} as a C character. If @var{x} is not a
654 Scheme character, the result is undefined.
657 @deftypefn Macro SCM SCM_MAKE_CHAR (int @var{c})
658 Given a C character @var{c}, return its representation as a Scheme
664 @subsubsection Booleans
666 Here are functions and macros for operating on booleans.
668 @deftypefn Macro SCM SCM_BOOL_T
669 @deftypefnx Macro SCM SCM_BOOL_F
670 The Scheme true and false values.
673 @deftypefn Macro int SCM_NFALSEP (@var{x})
674 Convert the Scheme boolean value to a C boolean. Since every object in
675 Scheme except @code{#f} is true, this amounts to comparing @var{x} to
676 @code{#f}; hence the name.
677 @c Noel feels a chill here.
680 @deftypefn Macro SCM SCM_BOOL_NOT (@var{x})
681 Return the boolean inverse of @var{x}. If @var{x} is not a
682 Scheme boolean, the result is undefined.
687 @subsubsection Unique Values
689 The immediate values that are neither small integers, characters, nor
690 booleans are all unique values --- that is, datatypes with only one
693 @deftypefn Macro SCM SCM_EOL
694 The Scheme empty list object, or ``End Of List'' object, usually written
695 in Scheme as @code{'()}.
698 @deftypefn Macro SCM SCM_EOF_VAL
699 The Scheme end-of-file value. It has no standard written
700 representation, for obvious reasons.
703 @deftypefn Macro SCM SCM_UNSPECIFIED
704 The value returned by expressions which the Scheme standard says return
705 an ``unspecified'' value.
707 This is sort of a weirdly literal way to take things, but the standard
708 read-eval-print loop prints nothing when the expression returns this
709 value, so it's not a bad idea to return this when you can't think of
710 anything else helpful.
713 @deftypefn Macro SCM SCM_UNDEFINED
714 The ``undefined'' value. Its most important property is that is not
715 equal to any valid Scheme value. This is put to various internal uses
716 by C code interacting with Guile.
718 For example, when you write a C function that is callable from Scheme
719 and which takes optional arguments, the interpreter passes
720 @code{SCM_UNDEFINED} for any arguments you did not receive.
722 We also use this to mark unbound variables.
725 @deftypefn Macro int SCM_UNBNDP (SCM @var{x})
726 Return true if @var{x} is @code{SCM_UNDEFINED}. Apply this to a
727 symbol's value to see if it has a binding as a global variable.
731 @node Non-immediate Datatypes
732 @subsection Non-immediate Datatypes
734 A non-immediate datatype is one which lives in the heap, either because
735 it cannot fit entirely within a @code{SCM} word, or because it denotes a
736 specific storage location (in the nomenclature of the Revised^4 Report
739 The @code{SCM_IMP} and @code{SCM_NIMP} macros will distinguish these
740 from immediates; see @ref{Immediates vs Non-immediates}.
742 Given a cell, Guile distinguishes between pairs and other non-immediate
743 types by storing special @dfn{tag} values in a non-pair cell's car, that
744 cannot appear in normal pairs. A cell with a non-tag value in its car
745 is an ordinary pair. The type of a cell with a tag in its car depends
746 on the tag; the non-immediate type predicates test this value. If a tag
747 value appears elsewhere (in a vector, for example), the heap may become
752 * Non-immediate Type Predicates:: Special rules for using the type
753 predicates described here.
762 @node Non-immediate Type Predicates
763 @subsubsection Non-immediate Type Predicates
765 As mentioned in @ref{Conservative GC}, all non-immediate objects
766 start with a @dfn{cell}, or a pair of words. Furthermore, all type
767 information that distinguishes one kind of non-immediate from another is
768 stored in the cell. The type information in the @code{SCM} value
769 indicates only that the object is a non-immediate; all finer
770 distinctions require one to examine the cell itself, usually with the
771 appropriate type predicate macro.
773 The type predicates for non-immediate objects generally assume that
774 their argument is a non-immediate value. Thus, you must be sure that a
775 value is @code{SCM_NIMP} first before passing it to a non-immediate type
776 predicate. Thus, the idiom for testing whether a value is a cell or not
779 SCM_NIMP (@var{x}) && SCM_CONSP (@var{x})
786 Pairs are the essential building block of list structure in Scheme. A
787 pair object has two fields, called the @dfn{car} and the @dfn{cdr}.
789 It is conventional for a pair's @sc{car} to contain an element of a
790 list, and the @sc{cdr} to point to the next pair in the list, or to
791 contain @code{SCM_EOL}, indicating the end of the list. Thus, a set of
792 pairs chained through their @sc{cdr}s constitutes a singly-linked list.
793 Scheme and libguile define many functions which operate on lists
794 constructed in this fashion, so although lists chained through the
795 @sc{car}s of pairs will work fine too, they may be less convenient to
796 manipulate, and receive less support from the community.
798 Guile implements pairs by mapping the @sc{car} and @sc{cdr} of a pair
799 directly into the two words of the cell.
802 @deftypefn Macro int SCM_CONSP (SCM @var{x})
803 Return non-zero iff @var{x} is a Scheme pair object.
804 The results are undefined if @var{x} is an immediate value.
807 @deftypefn Macro int SCM_NCONSP (SCM @var{x})
808 The complement of SCM_CONSP.
811 @deftypefn Macro void SCM_NEWCELL (SCM @var{into})
812 Allocate a new cell, and set @var{into} to point to it. This macro
813 expands to a statement, not an expression, and @var{into} must be an
816 This is the most primitive way to allocate a cell; it is quite fast.
818 The @sc{car} of the cell initially tags it as a ``free cell''. If the
819 caller intends to use it as an ordinary cons, she must store ordinary
820 SCM values in its @sc{car} and @sc{cdr}.
822 If the caller intends to use it as a header for some other type, she
823 must store an appropriate magic value in the cell's @sc{car}, to mark
824 it as a member of that type, and store whatever value in the @sc{cdr}
825 that type expects. You should generally not do this, unless you are
826 implementing a new datatype, and thoroughly understand the code in
827 @code{<libguile/tags.h>}.
830 @deftypefun SCM scm_cons (SCM @var{car}, SCM @var{cdr})
831 Allocate (``CONStruct'') a new pair, with @var{car} and @var{cdr} as its
836 The macros below perform no typechecking. The results are undefined if
837 @var{cell} is an immediate. However, since all non-immediate Guile
838 objects are constructed from cells, and these macros simply return the
839 first element of a cell, they actually can be useful on datatypes other
840 than pairs. (Of course, it is not very modular to use them outside of
841 the code which implements that datatype.)
843 @deftypefn Macro SCM SCM_CAR (SCM @var{cell})
844 Return the @sc{car}, or first field, of @var{cell}.
847 @deftypefn Macro SCM SCM_CDR (SCM @var{cell})
848 Return the @sc{cdr}, or second field, of @var{cell}.
851 @deftypefn Macro void SCM_SETCAR (SCM @var{cell}, SCM @var{x})
852 Set the @sc{car} of @var{cell} to @var{x}.
855 @deftypefn Macro void SCM_SETCDR (SCM @var{cell}, SCM @var{x})
856 Set the @sc{cdr} of @var{cell} to @var{x}.
859 @deftypefn Macro SCM SCM_CAAR (SCM @var{cell})
860 @deftypefnx Macro SCM SCM_CADR (SCM @var{cell})
861 @deftypefnx Macro SCM SCM_CDAR (SCM @var{cell}) @dots{}
862 @deftypefnx Macro SCM SCM_CDDDDR (SCM @var{cell})
863 Return the @sc{car} of the @sc{car} of @var{cell}, the @sc{car} of the
864 @sc{cdr} of @var{cell}, @i{et cetera}.
869 @subsubsection Vectors, Strings, and Symbols
871 Vectors, strings, and symbols have some properties in common. They all
872 have a length, and they all have an array of elements. In the case of a
873 vector, the elements are @code{SCM} values; in the case of a string or
874 symbol, the elements are characters.
876 All these types store their length (along with some tagging bits) in the
877 @sc{car} of their header cell, and store a pointer to the elements in
878 their @sc{cdr}. Thus, the @code{SCM_CAR} and @code{SCM_CDR} macros
879 are (somewhat) meaningful when applied to these datatypes.
881 @deftypefn Macro int SCM_VECTORP (SCM @var{x})
882 Return non-zero iff @var{x} is a vector.
883 The results are undefined if @var{x} is an immediate value.
886 @deftypefn Macro int SCM_STRINGP (SCM @var{x})
887 Return non-zero iff @var{x} is a string.
888 The results are undefined if @var{x} is an immediate value.
891 @deftypefn Macro int SCM_SYMBOLP (SCM @var{x})
892 Return non-zero iff @var{x} is a symbol.
893 The results are undefined if @var{x} is an immediate value.
896 @deftypefn Macro int SCM_LENGTH (SCM @var{x})
897 Return the length of the object @var{x}.
898 The results are undefined if @var{x} is not a vector, string, or symbol.
901 @deftypefn Macro {SCM *} SCM_VELTS (SCM @var{x})
902 Return a pointer to the array of elements of the vector @var{x}.
903 The results are undefined if @var{x} is not a vector.
906 @deftypefn Macro {char *} SCM_CHARS (SCM @var{x})
907 Return a pointer to the characters of @var{x}.
908 The results are undefined if @var{x} is not a symbol or a string.
911 There are also a few magic values stuffed into memory before a symbol's
912 characters, but you don't want to know about those. What cruft!
916 @subsubsection Procedures
918 Guile provides two kinds of procedures: @dfn{closures}, which are the
919 result of evaluating a @code{lambda} expression, and @dfn{subrs}, which
920 are C functions packaged up as Scheme objects, to make them available to
923 (There are actually other sorts of procedures: compiled closures, and
924 continuations; see the source code for details about them.)
926 @deftypefun SCM scm_procedure_p (SCM @var{x})
927 Return @code{SCM_BOOL_T} iff @var{x} is a Scheme procedure object, of
928 any sort. Otherwise, return @code{SCM_BOOL_F}.
933 @subsubsection Closures
935 [FIXME: this needs to be further subbed, but texinfo has no subsubsub]
937 A closure is a procedure object, generated as the value of a
938 @code{lambda} expression in Scheme. The representation of a closure is
939 straightforward --- it contains a pointer to the code of the lambda
940 expression from which it was created, and a pointer to the environment
943 In Guile, each closure also has a property list, allowing the system to
944 store information about the closure. I'm not sure what this is used for
945 at the moment --- the debugger, maybe?
947 @deftypefn Macro int SCM_CLOSUREP (SCM @var{x})
948 Return non-zero iff @var{x} is a closure. The results are
949 undefined if @var{x} is an immediate value.
952 @deftypefn Macro SCM SCM_PROCPROPS (SCM @var{x})
953 Return the property list of the closure @var{x}. The results are
954 undefined if @var{x} is not a closure.
957 @deftypefn Macro void SCM_SETPROCPROPS (SCM @var{x}, SCM @var{p})
958 Set the property list of the closure @var{x} to @var{p}. The results
959 are undefined if @var{x} is not a closure.
962 @deftypefn Macro SCM SCM_CODE (SCM @var{x})
963 Return the code of the closure @var{x}. The results are undefined if
964 @var{x} is not a closure.
966 This function should probably only be used internally by the
967 interpreter, since the representation of the code is intimately
968 connected with the interpreter's implementation.
971 @deftypefn Macro SCM SCM_ENV (SCM @var{x})
972 Return the environment enclosed by @var{x}.
973 The results are undefined if @var{x} is not a closure.
975 This function should probably only be used internally by the
976 interpreter, since the representation of the environment is intimately
977 connected with the interpreter's implementation.
984 [FIXME: this needs to be further subbed, but texinfo has no subsubsub]
986 A subr is a pointer to a C function, packaged up as a Scheme object to
987 make it callable by Scheme code. In addition to the function pointer,
988 the subr also contains a pointer to the name of the function, and
989 information about the number of arguments accepted by the C fuction, for
990 the sake of error checking.
992 There is no single type predicate macro that recognizes subrs, as
993 distinct from other kinds of procedures. The closest thing is
994 @code{scm_procedure_p}; see @ref{Procedures}.
996 @deftypefn Macro {char *} SCM_SNAME (@var{x})
997 Return the name of the subr @var{x}. The results are undefined if
998 @var{x} is not a subr.
1001 @deftypefun SCM scm_make_gsubr (char *@var{name}, int @var{req}, int @var{opt}, int @var{rest}, SCM (*@var{function})())
1002 Create a new subr object named @var{name}, based on the C function
1003 @var{function}, make it visible to Scheme the value of as a global
1004 variable named @var{name}, and return the subr object.
1006 The subr object accepts @var{req} required arguments, @var{opt} optional
1007 arguments, and a @var{rest} argument iff @var{rest} is non-zero. The C
1008 function @var{function} should accept @code{@var{req} + @var{opt}}
1009 arguments, or @code{@var{req} + @var{opt} + 1} arguments if @code{rest}
1012 When a subr object is applied, it must be applied to at least @var{req}
1013 arguments, or else Guile signals an error. @var{function} receives the
1014 subr's first @var{req} arguments as its first @var{req} arguments. If
1015 there are fewer than @var{opt} arguments remaining, then @var{function}
1016 receives the value @code{SCM_UNDEFINED} for any missing optional
1017 arguments. If @var{rst} is non-zero, then any arguments after the first
1018 @code{@var{req} + @var{opt}} are packaged up as a list as passed as
1019 @var{function}'s last argument.
1021 Note that subrs can actually only accept a predefined set of
1022 combinations of required, optional, and rest arguments. For example, a
1023 subr can take one required argument, or one required and one optional
1024 argument, but a subr can't take one required and two optional arguments.
1025 It's bizarre, but that's the way the interpreter was written. If the
1026 arguments to @code{scm_make_gsubr} do not fit one of the predefined
1027 patterns, then @code{scm_make_gsubr} will return a compiled closure
1028 object instead of a subr object.
1033 @subsubsection Ports
1035 Haven't written this yet, 'cos I don't understand ports yet.
1038 @node Signalling Type Errors
1039 @subsection Signalling Type Errors
1041 Every function visible at the Scheme level should aggressively check the
1042 types of its arguments, to avoid misinterpreting a value, and perhaps
1043 causing a segmentation fault. Guile provides some macros to make this
1046 @deftypefn Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, int @var{position}, char *@var{subr})
1047 If @var{test} is zero, signal an error, attributed to the subroutine
1048 named @var{subr}, operating on the value @var{obj}. The @var{position}
1049 value determines exactly what sort of error to signal.
1051 If @var{position} is a string, @code{SCM_ASSERT} raises a
1052 ``miscellaneous'' error whose message is that string.
1054 Otherwise, @var{position} should be one of the values defined below.
1057 @deftypefn Macro int SCM_ARG1
1058 @deftypefnx Macro int SCM_ARG2
1059 @deftypefnx Macro int SCM_ARG3
1060 @deftypefnx Macro int SCM_ARG4
1061 @deftypefnx Macro int SCM_ARG5
1062 Signal a ``wrong type argument'' error. When used as the @var{position}
1063 argument of @code{SCM_ASSERT}, @code{SCM_ARG@var{n}} claims that
1064 @var{obj} has the wrong type for the @var{n}'th argument of @var{subr}.
1066 The only way to complain about the type of an argument after the fifth
1067 is to use @code{SCM_ARGn}, defined below, which doesn't specify which
1068 argument is wrong. You could pass your own error message to
1069 @code{SCM_ASSERT} as the @var{position}, but then the error signalled is
1070 a ``miscellaneous'' error, not a ``wrong type argument'' error. This
1072 @comment Any function with more than two arguments is wrong --- Perlis
1073 @comment Despite Perlis, I agree. Why not have two Macros, one with
1074 @comment a string error message, and the other with an integer position
1075 @comment that only claims a type error in an argument?
1076 @comment --- Keith Wright
1079 @deftypefn Macro int SCM_ARGn
1080 As above, but does not specify which argument's type is incorrect.
1083 @deftypefn Macro int SCM_WNA
1084 Signal an error complaining that the function received the wrong number
1087 Interestingly, the message is attributed to the function named by
1088 @var{obj}, not @var{subr}, so @var{obj} must be a Scheme string object
1089 naming the function. Usually, Guile catches these errors before ever
1090 invoking the subr, so we don't run into these problems.
1094 @node Defining New Types (Smobs)
1095 @section Defining New Types (Smobs)
1097 @dfn{Smobs} are Guile's mechanism for adding new non-immediate types to
1098 the system.@footnote{The term ``smob'' was coined by Aubrey Jaffer, who
1099 says it comes from ``small object'', referring to the fact that only the
1100 @sc{cdr} and part of the @sc{car} of a smob's cell are available for
1101 use.} To define a new smob type, the programmer provides Guile with
1102 some essential information about the type --- how to print it, how to
1103 garbage collect it, and so on --- and Guile returns a fresh type tag for
1104 use in the @sc{car} of new cells. The programmer can then use
1105 @code{scm_make_gsubr} to make a set of C functions that create and
1106 operate on these objects visible to Scheme code.
1108 (You can find a complete version of the example code used in this
1109 section in the Guile distribution, in @file{doc/example-smob}. That
1110 directory includes a makefile and a suitable @code{main} function, so
1111 you can build a complete interactive Guile shell, extended with the
1112 datatypes described here.)
1115 * Describing a New Type::
1116 * Creating Instances::
1118 * Garbage Collecting Smobs::
1119 * A Common Mistake In Allocating Smobs::
1120 * Garbage Collecting Simple Smobs::
1121 * A Complete Example::
1124 @node Describing a New Type
1125 @subsection Describing a New Type
1127 To define a new type, the programmer must write four functions to
1128 manage instances of the type:
1132 Guile will apply this function to each instance of the new type it
1133 encounters during garbage collection. This function is responsible for
1134 telling the collector about any other non-immediate objects the object
1135 refers to. The default smob mark function is to not mark any data.
1136 @xref{Garbage Collecting Smobs}, for more details.
1139 Guile will apply this function to each instance of the new type it could
1140 not find any live pointers to. The function should release all
1141 resources held by the object and return the number of bytes released.
1142 This is analagous to the Java finalization method-- it is invoked at
1143 an unspecified time (when garbage collection occurs) after the object
1145 The default free function frees the smob data (if the size of the struct
1146 passed to @code{scm_make_smob_type} or @code{scm_make_smob_type_mfpe} is
1147 non-zero) using @code{scm_must_free} and returns the size of that
1148 struct. @xref{Garbage Collecting Smobs}, for more details.
1151 @c GJB:FIXME:: @var{exp} and @var{port} need to refer to a prototype of
1152 @c the print function.... where is that, or where should it go?
1153 Guile will apply this function to each instance of the new type to print
1154 the value, as for @code{display} or @code{write}. The function should
1155 write a printed representation of @var{exp} on @var{port}, in accordance
1156 with the parameters in @var{pstate}. (For more information on print
1157 states, see @ref{Port Data}.) The default print function prints @code{#<NAME ADDRESS>}
1158 where @code{NAME} is the first argument passed to @code{scm_make_smob_type} or
1159 @code{scm_make_smob_type_mfpe}.
1162 If Scheme code asks the @code{equal?} function to compare two instances
1163 of the same smob type, Guile calls this function. It should return
1164 @code{SCM_BOOL_T} if @var{a} and @var{b} should be considered
1165 @code{equal?}, or @code{SCM_BOOL_F} otherwise. If @code{equalp} is
1166 @code{NULL}, @code{equal?} will assume that two instances of this type are
1167 never @code{equal?} unless they are @code{eq?}.
1171 To actually register the new smob type, call @code{scm_make_smob_type}:
1173 @deftypefun long scm_make_smob_type (const char *name, scm_sizet size)
1174 This function implements the standard way of adding a new smob type,
1175 named @var{name}, with instance size @var{size}, to the system. The
1176 return value is a tag that is used in creating instances of the type.
1177 If @var{size} is 0, then no memory will be allocated when instances of
1178 the smob are created, and nothing will be freed by the default free
1179 function. Default values are provided for mark, free, print, and,
1180 equalp, as described above. If you want to customize any of these
1181 functions, the call to @code{scm_make_smob_type} should be immediately
1182 followed by calls to one or several of @code{scm_set_smob_mark},
1183 @code{scm_set_smob_free}, @code{scm_set_smob_print}, and/or
1184 @code{scm_set_smob_equalp}.
1187 Each of the below @code{scm_set_smob_XXX} functions registers a smob
1188 special function for a given type. Each function is intended to be used
1189 only zero or one time per type, and the call should be placed
1190 immediately following the call to @code{scm_make_smob_type}.
1192 @deftypefun void scm_set_smob_mark (long tc, SCM (*mark) (SCM))
1193 This function sets the smob marking procedure for the smob type specified by
1194 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1197 @deftypefun void scm_set_smob_free (long tc, scm_sizet (*free) (SCM))
1198 This function sets the smob freeing procedure for the smob type specified by
1199 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1202 @deftypefun void scm_set_smob_print (long tc, int (*print) (SCM,SCM,scm_print_state*))
1203 This function sets the smob printing procedure for the smob type specified by
1204 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1207 @deftypefun void scm_set_smob_equalp (long tc, SCM (*equalp) (SCM,SCM))
1208 This function sets the smob equality-testing predicate for the smob type specified by
1209 the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
1212 Instead of using @code{scm_make_smob_type} and calling each of the
1213 individual @code{scm_set_smob_XXX} functions to register each special
1214 function independently, you can use @code{scm_make_smob_type_mfpe} to
1215 register all of the special functions at once as you create the smob
1216 type@footnote{Warning: There is an ongoing discussion among the developers which
1217 may result in deprecating @code{scm_make_smob_type_mfpe} in next release
1220 @deftypefun long scm_make_smob_type_mfpe(const char *name, scm_sizet size, SCM (*mark) (SCM), scm_sizet (*free) (SCM), int (*print) (SCM, SCM, scm_print_state*), SCM (*equalp) (SCM, SCM))
1221 This function invokes @code{scm_make_smob_type} on its first two arguments
1222 to add a new smob type named @var{name}, with instance size @var{size} to the system.
1223 It also registers the @var{mark}, @var{free}, @var{print}, @var{equalp} smob
1224 special functions for that new type. Any of these parameters can be @code{NULL}
1225 to have that special function use the default behaviour for guile.
1226 The return value is a tag that is used in creating instances of the type. If @var{size}
1227 is 0, then no memory will be allocated when instances of the smob are created, and
1228 nothing will be freed by the default free function.
1231 For example, here is how one might declare and register a new type
1232 representing eight-bit grayscale images:
1234 #include <libguile.h>
1241 image_tag = scm_make_smob_type_mfpe ("image",sizeof(struct image),
1242 mark_image, free_image, print_image, NULL);
1247 @node Creating Instances
1248 @subsection Creating Instances
1250 Like other non-immediate types, smobs start with a cell whose @sc{car}
1251 contains typing information, and whose @code{cdr} is free for any use. For smobs,
1252 the @code{cdr} stores a pointer to the internal C structure holding the
1254 To create an instance of a smob type following these standards, you should
1255 use @code{SCM_NEWSMOB}:
1257 @deftypefn Macro void SCM_NEWSMOB(SCM value,long tag,void *data)
1258 Make @var{value} contain a smob instance of the type with tag @var{tag}
1259 and smob data @var{data}. @var{value} must be previously declared
1260 as C type @code{SCM}.
1263 Since it is often the case (e.g., in smob constructors) that you will
1264 create a smob instance and return it, there is also a slightly specialized
1265 macro for this situation:
1267 @deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(long tab, void *data)
1268 This macro expands to a block of code that creates a smob instance of
1269 the type with tag @var{tag} and smob data @var{data}, and returns
1270 that @code{SCM} value. It should be the last piece of code in
1274 Guile provides the following functions for managing memory, which are
1275 often helpful when implementing smobs:
1277 @deftypefun {char *} scm_must_malloc (long @var{len}, char *@var{what})
1278 Allocate @var{len} bytes of memory, using @code{malloc}, and return a
1281 If there is not enough memory available, invoke the garbage collector,
1282 and try once more. If there is still not enough, signal an error,
1283 reporting that we could not allocate @var{what}.
1285 This function also helps maintain statistics about the size of the heap.
1288 @deftypefun {char *} scm_must_realloc (char *@var{addr}, long @var{olen}, long @var{len}, char *@var{what})
1289 Resize (and possibly relocate) the block of memory at @var{addr}, to
1290 have a size of @var{len} bytes, by calling @code{realloc}. Return a
1291 pointer to the new block.
1293 If there is not enough memory available, invoke the garbage collector,
1294 and try once more. If there is still not enough, signal an error,
1295 reporting that we could not allocate @var{what}.
1297 The value @var{olen} should be the old size of the block of memory at
1298 @var{addr}; it is only used for keeping statistics on the size of the
1302 @deftypefun void scm_must_free (char *@var{addr})
1303 Free the block of memory at @var{addr}, using @code{free}. If
1304 @var{addr} is zero, signal an error, complaining of an attempt to free
1305 something that is already free.
1307 This does no record-keeping; instead, the smob's @code{free} function
1308 must take care of that.
1310 This function isn't usually sufficiently different from the usual
1311 @code{free} function to be worth using.
1315 Continuing the above example, if the global variable @code{image_tag}
1316 contains a tag returned by @code{scm_newsmob}, here is how we could
1317 construct a smob whose @sc{cdr} contains a pointer to a freshly
1318 allocated @code{struct image}:
1325 /* The name of this image */
1328 /* A function to call when this image is
1329 modified, e.g., to update the screen,
1330 or SCM_BOOL_F if no action necessary */
1335 make_image (SCM name, SCM s_width, SCM s_height)
1337 struct image *image;
1340 SCM_ASSERT (SCM_NIMP (name) && SCM_STRINGP (name), name,
1341 SCM_ARG1, "make-image");
1342 SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
1343 SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
1345 width = SCM_INUM (s_width);
1346 height = SCM_INUM (s_height);
1348 image = (struct image *) scm_must_malloc (sizeof (struct image), "image");
1349 image->width = width;
1350 image->height = height;
1351 image->pixels = scm_must_malloc (width * height, "image pixels");
1353 image->update_func = SCM_BOOL_F;
1355 SCM_RETURN_NEWSMOB (image_tag, image);
1361 @subsection Typechecking
1363 Functions that operate on smobs should aggressively check the types of
1364 their arguments, to avoid misinterpreting some other datatype as a smob,
1365 and perhaps causing a segmentation fault. Fortunately, this is pretty
1366 simple to do. The function need only verify that its argument is a
1367 non-immediate, whose @sc{car} is the type tag returned by
1370 For example, here is a simple function that operates on an image smob,
1371 and checks the type of its argument. We also present an expanded
1372 version of the @code{init_image_type} function, to make
1373 @code{clear_image} and the image constructor function @code{make_image}
1374 visible to Scheme code.
1377 clear_image (SCM image_smob)
1380 struct image *image;
1382 SCM_ASSERT (SCM_SMOB_PREDICATE (image_tag, image_smob),
1383 image_smob, SCM_ARG1, "clear-image");
1385 image = (struct image *) SCM_SMOB_DATA (image_smob);
1386 area = image->width * image->height;
1387 memset (image->pixels, 0, area);
1389 /* Invoke the image's update function. */
1390 if (image->update_func != SCM_BOOL_F)
1391 scm_apply (image->update_func, SCM_EOL, SCM_EOL);
1393 return SCM_UNSPECIFIED;
1400 image_tag = scm_newsmob (&image_funs);
1402 scm_make_gsubr ("make-image", 3, 0, 0, make_image);
1403 scm_make_gsubr ("clear-image", 1, 0, 0, clear_image);
1407 Note that checking types is a little more complicated during garbage
1408 collection; see the description of @code{SCM_GCTYP16} in @ref{Garbage
1411 @c GJB:FIXME:: should talk about guile-snarf somewhere!
1413 @node Garbage Collecting Smobs
1414 @subsection Garbage Collecting Smobs
1416 Once a smob has been released to the tender mercies of the Scheme
1417 system, it must be prepared to survive garbage collection. Guile calls
1418 the @code{mark} and @code{free} functions of the @code{scm_smobfuns}
1419 structure to manage this.
1421 As described before (@pxref{Conservative GC}), every object in the
1422 Scheme system has a @dfn{mark bit}, which the garbage collector uses to
1423 tell live objects from dead ones. When collection starts, every
1424 object's mark bit is clear. The collector traces pointers through the
1425 heap, starting from objects known to be live, and sets the mark bit on
1426 each object it encounters. When it can find no more unmarked objects,
1427 the collector walks all objects, live and dead, frees those whose mark
1428 bits are still clear, and clears the mark bit on the others.
1430 The two main portions of the collection are called the @dfn{mark phase},
1431 during which the collector marks live objects, and the @dfn{sweep
1432 phase}, during which the collector frees all unmarked objects.
1434 The mark bit of a smob lives in its @sc{car}, along with the smob's type
1435 tag. When the collector encounters a smob, it sets the smob's mark bit,
1436 and uses the smob's type tag to find the appropriate @code{mark}
1437 function for that smob: the one listed in that smob's
1438 @code{scm_smobfuns} structure. It then calls the @code{mark} function,
1439 passing it the smob as its only argument.
1441 The @code{mark} function is responsible for marking any other Scheme
1442 objects the smob refers to. If it does not do so, the objects' mark
1443 bits will still be clear when the collector begins to sweep, and the
1444 collector will free them. If this occurs, it will probably break, or at
1445 least confuse, any code operating on the smob; the smob's @code{SCM}
1446 values will have become dangling references.
1448 To mark an arbitrary Scheme object, the @code{mark} function may call
1451 @deftypefun void scm_gc_mark (SCM @var{x})
1452 Mark the object @var{x}, and recurse on any objects @var{x} refers to.
1453 If @var{x}'s mark bit is already set, return immediately.
1456 Thus, here is how we might write the @code{mark} function for the image
1457 smob type discussed above:
1461 mark_image (SCM image_smob)
1463 /* Mark the image's name and update function. */
1464 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1466 scm_gc_mark (image->name);
1467 scm_gc_mark (image->update_func);
1474 Note that, even though the image's @code{update_func} could be an
1475 arbitrarily complex structure (representing a procedure and any values
1476 enclosed in its environment), @code{scm_gc_mark} will recurse as
1477 necessary to mark all its components. Because @code{scm_gc_mark} sets
1478 an object's mark bit before it recurses, it is not confused by
1479 circular structures.
1481 As an optimization, the collector will mark whatever value is returned
1482 by the @code{mark} function; this helps limit depth of recursion during
1483 the mark phase. Thus, the code above could also be written as:
1487 mark_image (SCM image_smob)
1489 /* Mark the image's name and update function. */
1490 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1492 scm_gc_mark (image->name);
1493 return image->update_func;
1499 Finally, when the collector encounters an unmarked smob during the sweep
1500 phase, it uses the smob's tag to find the appropriate @code{free}
1501 function for the smob. It then calls the function, passing it the smob
1502 as its only argument.
1504 The @code{free} function must release any resources used by the smob.
1505 However, it need not free objects managed by the collector; the
1506 collector will take care of them. The return type of the @code{free}
1507 function should be @code{scm_sizet}, an unsigned integral type; the
1508 @code{free} function should return the number of bytes released, to help
1509 the collector maintain statistics on the size of the heap.
1511 Here is how we might write the @code{free} function for the image smob
1515 free_image (SCM image_smob)
1517 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1518 scm_sizet size = image->width * image->height + sizeof (*image);
1520 free (image->pixels);
1527 During the sweep phase, the garbage collector will clear the mark bits
1528 on all live objects. The code which implements a smob need not do this
1531 There is no way for smob code to be notified when collection is
1534 Note that, since a smob's mark bit lives in its @sc{car}, along with the
1535 smob's type tag, the technique for checking the type of a smob described
1536 in @ref{Typechecking} will not necessarily work during GC. If you need
1537 to find out whether a given object is a particular smob type during GC,
1538 use the following macro:
1540 @deftypefn Macro void SCM_GCTYP16 (SCM @var{x})
1541 Return the type bits of the smob @var{x}, with the mark bit clear.
1543 Use this macro instead of @code{SCM_CAR} to check the type of a smob
1544 during GC. Usually, only code called by the smob's @code{mark} function
1545 need worry about this.
1548 It is usually a good idea to minimize the amount of processing done
1549 during garbage collection; keep @code{mark} and @code{free} functions
1550 very simple. Since collections occur at unpredictable times, it is easy
1551 for any unusual activity to interfere with normal code.
1554 @node A Common Mistake In Allocating Smobs, Garbage Collecting Simple Smobs, Garbage Collecting Smobs, Defining New Types (Smobs)
1555 @subsection A Common Mistake In Allocating Smobs
1557 When constructing new objects, you must be careful that the garbage
1558 collector can always find any new objects you allocate. For example,
1559 suppose we wrote the @code{make_image} function this way:
1563 make_image (SCM name, SCM s_width, SCM s_height)
1565 struct image *image;
1569 SCM_ASSERT (SCM_NIMP (name) && SCM_STRINGP (name), name,
1570 SCM_ARG1, "make-image");
1571 SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
1572 SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
1574 width = SCM_INUM (s_width);
1575 height = SCM_INUM (s_height);
1577 image = (struct image *) scm_must_malloc (sizeof (struct image), "image");
1578 image->width = width;
1579 image->height = height;
1580 image->pixels = scm_must_malloc (width * height, "image pixels");
1582 /* THESE TWO LINES HAVE CHANGED: */
1583 image->name = scm_string_copy (name);
1584 image->update_func = scm_make_gsubr (@dots{});
1586 SCM_NEWCELL (image_smob);
1587 SCM_SETCDR (image_smob, image);
1588 SCM_SETCAR (image_smob, image_tag);
1594 This code is incorrect. The calls to @code{scm_string_copy} and
1595 @code{scm_make_gsubr} allocate fresh objects. Allocating any new object
1596 may cause the garbage collector to run. If @code{scm_make_gsubr}
1597 invokes a collection, the garbage collector has no way to discover that
1598 @code{image->name} points to the new string object; the @code{image}
1599 structure is not yet part of any Scheme object, so the garbage collector
1600 will not traverse it. Since the garbage collector cannot find any
1601 references to the new string object, it will free it, leaving
1602 @code{image} pointing to a dead object.
1604 A correct implementation might say, instead:
1606 image->name = SCM_BOOL_F;
1607 image->update_func = SCM_BOOL_F;
1609 SCM_NEWCELL (image_smob);
1610 SCM_SETCDR (image_smob, image);
1611 SCM_SETCAR (image_smob, image_tag);
1613 image->name = scm_string_copy (name);
1614 image->update_func = scm_make_gsubr (@dots{});
1619 Now, by the time we allocate the new string and function objects,
1620 @code{image_smob} points to @code{image}. If the garbage collector
1621 scans the stack, it will find a reference to @code{image_smob} and
1622 traverse @code{image}, so any objects @code{image} points to will be
1626 @node Garbage Collecting Simple Smobs, A Complete Example, A Common Mistake In Allocating Smobs, Defining New Types (Smobs)
1627 @subsection Garbage Collecting Simple Smobs
1629 It is often useful to define very simple smob types --- smobs which have
1630 no data to mark, other than the cell itself, or smobs whose @sc{cdr} is
1631 simply an ordinary Scheme object, to be marked recursively. Guile
1632 provides some functions to handle these common cases; you can use these
1633 functions as your smob type's @code{mark} function, if your smob's
1634 structure is simple enough.
1636 If the smob refers to no other Scheme objects, then no action is
1637 necessary; the garbage collector has already marked the smob cell
1638 itself. In that case, you can use zero as your mark function.
1640 @deftypefun SCM scm_markcdr (SCM @var{x})
1641 Mark the references in the smob @var{x}, assuming that @var{x}'s
1642 @sc{cdr} contains an ordinary Scheme object, and @var{x} refers to no
1643 other objects. This function simply returns @var{x}'s @sc{cdr}.
1646 @deftypefun scm_sizet scm_free0 (SCM @var{x})
1647 Do nothing; return zero. This function is appropriate for smobs that
1648 use either zero or @code{scm_markcdr} as their marking functions, and
1649 refer to no heap storage, including memory managed by @code{malloc},
1650 other than the smob's header cell.
1654 @node A Complete Example
1655 @subsection A Complete Example
1657 Here is the complete text of the implementation of the image datatype,
1658 as presented in the sections above. We also provide a definition for
1659 the smob's @code{print} function, and make some objects and functions
1660 static, to clarify exactly what the surrounding code is using.
1662 As mentioned above, you can find this code in the Guile distribution, in
1663 @file{doc/example-smob}. That directory includes a makefile and a
1664 suitable @code{main} function, so you can build a complete interactive
1665 Guile shell, extended with the datatypes described here.)
1668 /* file "image-type.c" */
1671 #include <libguile.h>
1673 static long image_tag;
1679 /* The name of this image */
1682 /* A function to call when this image is
1683 modified, e.g., to update the screen,
1684 or SCM_BOOL_F if no action necessary */
1689 make_image (SCM name, SCM s_width, SCM s_height)
1691 struct image *image;
1695 SCM_ASSERT (SCM_NIMP (name) && SCM_STRINGP (name), name,
1696 SCM_ARG1, "make-image");
1697 SCM_ASSERT (SCM_INUMP (s_width), s_width, SCM_ARG2, "make-image");
1698 SCM_ASSERT (SCM_INUMP (s_height), s_height, SCM_ARG3, "make-image");
1700 width = SCM_INUM (s_width);
1701 height = SCM_INUM (s_height);
1703 image = (struct image *) scm_must_malloc (sizeof (struct image), "image");
1704 image->width = width;
1705 image->height = height;
1706 image->pixels = scm_must_malloc (width * height, "image pixels");
1708 image->update_func = SCM_BOOL_F;
1710 SCM_NEWSMOB (image_smob, image_tag, image);
1716 clear_image (SCM image_smob)
1719 struct image *image;
1721 SCM_ASSERT (SCM_SMOB_PREDICATE (image_tag, image_smob),
1722 image_smob, SCM_ARG1, "clear-image");
1724 image = (struct image *) SCM_SMOB_DATA (image_smob);
1725 area = image->width * image->height;
1726 memset (image->pixels, 0, area);
1728 /* Invoke the image's update function. */
1729 if (image->update_func != SCM_BOOL_F)
1730 scm_apply (image->update_func, SCM_EOL, SCM_EOL);
1732 return SCM_UNSPECIFIED;
1736 mark_image (SCM image_smob)
1738 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1740 scm_gc_mark (image->name);
1741 return image->update_func;
1745 free_image (SCM image_smob)
1747 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1748 scm_sizet size = image->width * image->height + sizeof (struct image);
1750 free (image->pixels);
1757 print_image (SCM image_smob, SCM port, scm_print_state *pstate)
1759 struct image *image = (struct image *) SCM_SMOB_DATA (image_smob);
1761 scm_puts ("#<image ", port);
1762 scm_display (image->name, port);
1763 scm_puts (">", port);
1765 /* non-zero means success */
1769 static scm_smobfuns image_funs = @{
1770 mark_image, free_image, print_image, 0
1776 image_tag = scm_newsmob (&image_funs);
1778 scm_make_gsubr ("clear-image", 1, 0, 0, clear_image);
1779 scm_make_gsubr ("make-image", 3, 0, 0, make_image);
1783 Here is a sample build and interaction with the code from the
1784 @file{example-smob} directory, on the author's machine:
1787 zwingli:example-smob$ make CC=gcc
1788 gcc `guile-config compile` -c image-type.c -o image-type.o
1789 gcc `guile-config compile` -c myguile.c -o myguile.o
1790 gcc image-type.o myguile.o `guile-config link` -o myguile
1791 zwingli:example-smob$ ./myguile
1793 #<primitive-procedure make-image>
1794 guile> (define i (make-image "Whistler's Mother" 100 100))
1796 #<image Whistler's Mother>
1797 guile> (clear-image i)
1798 guile> (clear-image 4)
1799 ERROR: In procedure clear-image in expression (clear-image 4):
1800 ERROR: Wrong type argument in position 1: 4
1801 ABORT: (wrong-type-arg)
1803 Type "(backtrace)" to get more information.