/[guile]/guile/guile-core/doc/data-rep.texi
ViewVC logotype

Diff of /guile/guile-core/doc/data-rep.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.11 by mdj, Tue Jun 20 03:22:56 2000 UTC revision 1.11.2.1 by ttn, Sun May 5 11:29:56 2002 UTC
# Line 1  Line 1 
1  \input texinfo  @c essay \input texinfo
2  @c -*-texinfo-*-  @c essay @c -*-texinfo-*-
3  @c %**start of header  @c essay @c %**start of header
4  @setfilename data-rep.info  @c essay @setfilename data-rep.info
5  @settitle Data Representation in Guile  @c essay @settitle Data Representation in Guile
6  @c %**end of header  @c essay @c %**end of header
7    @c essay
8  @include version.texi  @c essay @include version.texi
9    @c essay
10  @dircategory The Algorithmic Language Scheme  @c essay @dircategory The Algorithmic Language Scheme
11  @direntry  @c essay @direntry
12  * data-rep: (data-rep).  Data Representation in Guile --- how to use  @c essay * data-rep: (data-rep).  Data Representation in Guile --- how to use
13                           Guile objects in your C code.  @c essay                          Guile objects in your C code.
14  @end direntry  @c essay @end direntry
15    @c essay
16    @c essay @setchapternewpage off
17    @c essay
18    @c essay @ifinfo
19    @c essay Data Representation in Guile
20    @c essay
21    @c essay Copyright (C) 1998, 1999, 2000 Free Software Foundation
22    @c essay
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.
26    @c essay
27    @c essay @ignore
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).
32    @c essay @end ignore
33    @c essay
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.
38    @c essay
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.
43    @c essay @end ifinfo
44    @c essay
45    @c essay @titlepage
46    @c essay @sp 10
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$
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.
55    @c essay @page
56    @c essay @vskip 0pt plus 1filll
57    @c essay @vskip 0pt plus 1filll
58    @c essay Copyright @copyright{} 1998 Free Software Foundation
59    @c essay
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.
63    @c essay
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.
68    @c essay
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
74    @c essay
75    @c essay @c @smallbook
76    @c essay @c @finalout
77    @c essay @headings double
78    
79  @setchapternewpage off  @node Data Representation
80    @chapter Data Representation
 @ifinfo  
 Data Representation in Guile  
   
 Copyright (C) 1998, 1999, 2000 Free Software Foundation  
   
 Permission is granted to make and distribute verbatim copies of  
 this manual provided the copyright notice and this permission notice  
 are preserved on all copies.  
   
 @ignore  
 Permission is granted to process this file through TeX and print the  
 results, provided the printed document carries copying permission  
 notice identical to this one except for the removal of this paragraph  
 (this paragraph not being relevant to the printed manual).  
 @end ignore  
   
 Permission is granted to copy and distribute modified versions of this  
 manual under the conditions for verbatim copying, provided that the entire  
 resulting derived work is distributed under the terms of a permission  
 notice identical to this one.  
   
 Permission is granted to copy and distribute translations of this manual  
 into another language, under the above conditions for modified versions,  
 except that this permission notice may be stated in a translation approved  
 by the Free Software Foundation.  
 @end ifinfo  
   
 @titlepage  
 @sp 10  
 @comment The title is printed in a large font.  
 @title Data Representation in Guile  
 @subtitle $Id$  
 @subtitle For use with Guile @value{VERSION}  
 @author Jim Blandy  
 @author Free Software Foundation  
 @author @email{jimb@@red-bean.com}  
 @c The following two commands start the copyright page.  
 @page  
 @vskip 0pt plus 1filll  
 @vskip 0pt plus 1filll  
 Copyright @copyright{} 1998 Free Software Foundation  
   
 Permission is granted to make and distribute verbatim copies of  
 this manual provided the copyright notice and this permission notice  
 are preserved on all copies.  
   
 Permission is granted to copy and distribute modified versions of this  
 manual under the conditions for verbatim copying, provided that the entire  
 resulting derived work is distributed under the terms of a permission  
 notice identical to this one.  
   
 Permission is granted to copy and distribute translations of this manual  
 into another language, under the above conditions for modified versions,  
 except that this permission notice may be stated in a translation approved  
 by Free Software Foundation.  
 @end titlepage  
   
 @c @smallbook  
 @c @finalout  
 @headings double  
   
   
 @node Top, Data Representation in Scheme, (dir), (dir)  
 @top Data Representation in Guile  
81    
82  @ifinfo  @ifinfo
83  This essay is meant to provide the background necessary to read and  This essay is meant to provide the background necessary to read and
# Line 93  actually represents Scheme values.  Othe Line 92  actually represents Scheme values.  Othe
92  the conventions it follows, won't make very much sense.  the conventions it follows, won't make very much sense.
93    
94  We assume you know both C and Scheme, but we do not assume you are  We assume you know both C and Scheme, but we do not assume you are
95  familiar with Guile's C interface.  familiar with Guile's implementation.
96  @end ifinfo  @end ifinfo
97    
98  @menu  @menu
# Line 106  familiar with Guile's C interface. Line 105  familiar with Guile's C interface.
105                                          application-specific datatypes.                                          application-specific datatypes.
106  @end menu  @end menu
107    
108  @node Data Representation in Scheme, How Guile does it, Top, Top  @node Data Representation in Scheme
109  @section Data Representation in Scheme  @section Data Representation in Scheme
110    
111  Scheme is a latently-typed language; this means that the system cannot,  Scheme is a latently-typed language; this means that the system cannot,
# Line 137  does it}. Line 136  does it}.
136    
137    
138  @menu  @menu
139  * A Simple Representation::      * A Simple Representation::
140  * Faster Integers::              * Faster Integers::
141  * Cheaper Pairs::                * Cheaper Pairs::
142  * Guile Is Hairier::              * Guile Is Hairier::
143  @end menu  @end menu
144    
145  @node A Simple Representation, Faster Integers, Data Representation in Scheme, Data Representation in Scheme  @node A Simple Representation
146  @subsection A Simple Representation  @subsection A Simple Representation
147    
148  The simplest way to meet the above requirements in C would be to  The simplest way to meet the above requirements in C would be to
# Line 187  semantics.  If @var{x} is an @code{SCM} Line 186  semantics.  If @var{x} is an @code{SCM}
186  @end itemize  @end itemize
187    
188    
189  @node Faster Integers, Cheaper Pairs, A Simple Representation, Data Representation in Scheme  @node Faster Integers
190  @subsection Faster Integers  @subsection Faster Integers
191    
192  Unfortunately, the above representation has a serious disadvantage.  In  Unfortunately, the above representation has a serious disadvantage.  In
# Line 282  but this essay isn't about bit-twiddling Line 281  but this essay isn't about bit-twiddling
281  @code{01} in their least significant bits, and integers had @code{00}?)  @code{01} in their least significant bits, and integers had @code{00}?)
282    
283    
284  @node Cheaper Pairs, Guile Is Hairier, Faster Integers, Data Representation in Scheme  @node Cheaper Pairs
285  @subsection Cheaper Pairs  @subsection Cheaper Pairs
286    
287  However, there is yet another issue to confront.  Most Scheme heaps  However, there is yet another issue to confront.  Most Scheme heaps
# Line 380  are referencing, making a modified point Line 379  are referencing, making a modified point
379  unmodified pointer.  unmodified pointer.
380    
381    
382  @node Guile Is Hairier,  , Cheaper Pairs, Data Representation in Scheme  @node Guile Is Hairier
383  @subsection Guile Is Hairier  @subsection Guile Is Hairier
384    
385  We originally started with a very simple typing system --- each object  We originally started with a very simple typing system --- each object
# Line 396  significant loss of efficiency, but the Line 395  significant loss of efficiency, but the
395  more complex than what we've presented above.  more complex than what we've presented above.
396    
397    
398  @node How Guile does it, Defining New Types (Smobs), Data Representation in Scheme, Top  @node How Guile does it
399  @section How Guile does it  @section How Guile does it
400    
401  Here we present the specifics of how Guile represents its data.  We  Here we present the specifics of how Guile represents its data.  We
# Line 407  everything one need know to use Guile's Line 406  everything one need know to use Guile's
406    
407    
408  @menu  @menu
409  * General Rules::                * General Rules::
410  * Garbage Collection::            * Garbage Collection::
411  * Immediates vs. Non-immediates::    * Immediates vs. Non-immediates::
412  * Immediate Datatypes::          * Immediate Datatypes::
413  * Non-immediate Datatypes::      * Non-immediate Datatypes::
414  * Signalling Type Errors::        * Signalling Type Errors::
415  @end menu  @end menu
416    
417  @node General Rules, Garbage Collection, How Guile does it, How Guile does it  @node General Rules
418  @subsection General Rules  @subsection General Rules
419    
420  Any code which operates on Guile datatypes must @code{#include} the  Any code which operates on Guile datatypes must @code{#include} the
# Line 446  boolean value have names starting with @ Line 445  boolean value have names starting with @
445  @emph{not} a pair object (a @code{CONS}).  @emph{not} a pair object (a @code{CONS}).
446    
447    
448  @node Garbage Collection, Immediates vs. Non-immediates, General Rules, How Guile does it  @node Garbage Collection
449  @subsection Garbage Collection  @subsection Garbage Collection
450    
451  Aside from the latent typing, the major source of constraints on a  Aside from the latent typing, the major source of constraints on a
# Line 530  many pieces of code, it is enough for th Line 529  many pieces of code, it is enough for th
529  and then use the cell's type to find more pointers to trace.  and then use the cell's type to find more pointers to trace.
530    
531    
532  @node Immediates vs. Non-immediates, Immediate Datatypes, Garbage Collection, How Guile does it  @node Immediates vs. Non-immediates
533  @subsection Immediates vs. Non-immediates  @subsection Immediates vs. Non-immediates
534    
535  Guile classifies Scheme objects into two kinds: those that fit entirely  Guile classifies Scheme objects into two kinds: those that fit entirely
# Line 571  from this weakness. Line 570  from this weakness.
570  @end deftypefn  @end deftypefn
571    
572    
573  @node Immediate Datatypes, Non-immediate Datatypes, Immediates vs. Non-immediates, How Guile does it  @node Immediate Datatypes
574  @subsection Immediate Datatypes  @subsection Immediate Datatypes
575    
576  The following datatypes are immediate values; that is, they fit entirely  The following datatypes are immediate values; that is, they fit entirely
# Line 588  before applying them. Line 587  before applying them.
587    
588    
589  @menu  @menu
590  * Integers::                      * Integers::
591  * Characters::                    * Characters::
592  * Booleans::                      * Booleans::
593  * Unique Values::                * Unique Values::
594  @end menu  @end menu
595    
596  @node Integers, Characters, Immediate Datatypes, Immediate Datatypes  @node Integers
597  @subsubsection Integers  @subsubsection Integers
598    
599  Here are functions for operating on small integers, that fit within an  Here are functions for operating on small integers, that fit within an
# Line 627  This function does not check for overflo Line 626  This function does not check for overflo
626  @end deftypefn  @end deftypefn
627    
628    
629  @node Characters, Booleans, Integers, Immediate Datatypes  @node Characters
630  @subsubsection Characters  @subsubsection Characters
631    
632  Here are functions for operating on characters.  Here are functions for operating on characters.
# Line 647  character value. Line 646  character value.
646  @end deftypefn  @end deftypefn
647    
648    
649  @node Booleans, Unique Values, Characters, Immediate Datatypes  @node Booleans
650  @subsubsection Booleans  @subsubsection Booleans
651    
652  Here are functions and macros for operating on booleans.  Here are functions and macros for operating on booleans.
# Line 670  Scheme boolean, the result is undefined. Line 669  Scheme boolean, the result is undefined.
669  @end deftypefn  @end deftypefn
670    
671    
672  @node Unique Values,  , Booleans, Immediate Datatypes  @node Unique Values
673  @subsubsection Unique Values  @subsubsection Unique Values
674    
675  The immediate values that are neither small integers, characters, nor  The immediate values that are neither small integers, characters, nor
# Line 715  symbol's value to see if it has a bindin Line 714  symbol's value to see if it has a bindin
714  @end deftypefn  @end deftypefn
715    
716    
717  @node Non-immediate Datatypes, Signalling Type Errors, Immediate Datatypes, How Guile does it  @node Non-immediate Datatypes
718  @subsection Non-immediate Datatypes  @subsection Non-immediate Datatypes
719    
720  A non-immediate datatype is one which lives in the heap, either because  A non-immediate datatype is one which lives in the heap, either because
721  it cannot fit entirely within a @code{SCM} word, or because it denotes a  it cannot fit entirely within a @code{SCM} word, or because it denotes a
# Line 738  corrupted. Line 737  corrupted.
737  @menu  @menu
738  * Non-immediate Type Predicates::  Special rules for using the type  * Non-immediate Type Predicates::  Special rules for using the type
739                                          predicates described here.                                          predicates described here.
740  * Pairs::                        * Pairs::
741  * Vectors::                      * Vectors::
742  * Procedures::                    * Procedures::
743  * Closures::                      * Closures::
744  * Subrs::                        * Subrs::
745  * Ports::                        * Ports::
746  @end menu  @end menu
747    
748  @node Non-immediate Type Predicates, Pairs, Non-immediate Datatypes, Non-immediate Datatypes  @node Non-immediate Type Predicates
749  @subsubsection Non-immediate Type Predicates  @subsubsection Non-immediate Type Predicates
750    
751  As mentioned in @ref{Garbage Collection}, all non-immediate objects  As mentioned in @ref{Garbage Collection}, all non-immediate objects
# Line 767  SCM_NIMP (@var{x}) && SCM_CONSP (@var{x} Line 766  SCM_NIMP (@var{x}) && SCM_CONSP (@var{x}
766  @end example  @end example
767    
768    
769  @node Pairs, Vectors, Non-immediate Type Predicates, Non-immediate Datatypes  @node Pairs
770  @subsubsection Pairs  @subsubsection Pairs
771    
772  Pairs are the essential building block of list structure in Scheme.  A  Pairs are the essential building block of list structure in Scheme.  A
# Line 852  Return the @sc{car} of the @sc{car} of @ Line 851  Return the @sc{car} of the @sc{car} of @
851  @end deftypefn  @end deftypefn
852    
853    
854  @node Vectors, Procedures, Pairs, Non-immediate Datatypes  @node Vectors
855  @subsubsection Vectors, Strings, and Symbols  @subsubsection Vectors, Strings, and Symbols
856    
857  Vectors, strings, and symbols have some properties in common.  They all  Vectors, strings, and symbols have some properties in common.  They all
# Line 899  There are also a few magic values stuffe Line 898  There are also a few magic values stuffe
898  characters, but you don't want to know about those.  What cruft!  characters, but you don't want to know about those.  What cruft!
899    
900    
901  @node Procedures, Closures, Vectors, Non-immediate Datatypes  @node Procedures
902  @subsubsection Procedures  @subsubsection Procedures
903    
904  Guile provides two kinds of procedures: @dfn{closures}, which are the  Guile provides two kinds of procedures: @dfn{closures}, which are the
# Line 916  any sort.  Otherwise, return @code{SCM_B Line 915  any sort.  Otherwise, return @code{SCM_B
915  @end deftypefun  @end deftypefun
916    
917    
918  @node Closures, Subrs, Procedures, Non-immediate Datatypes  @node Closures
919  @subsubsection Closures  @subsubsection Closures
920    
921  [FIXME: this needs to be further subbed, but texinfo has no subsubsub]  [FIXME: this needs to be further subbed, but texinfo has no subsubsub]
# Line 965  connected with the interpreter's impleme Line 964  connected with the interpreter's impleme
964  @end deftypefn  @end deftypefn
965    
966    
967  @node Subrs, Ports, Closures, Non-immediate Datatypes  @node Subrs
968  @subsubsection Subrs  @subsubsection Subrs
969    
970  [FIXME: this needs to be further subbed, but texinfo has no subsubsub]  [FIXME: this needs to be further subbed, but texinfo has no subsubsub]
# Line 1016  object instead of a subr object. Line 1015  object instead of a subr object.
1015  @end deftypefun  @end deftypefun
1016    
1017    
1018  @node Ports,  , Subrs, Non-immediate Datatypes  @node Ports
1019  @subsubsection Ports  @subsubsection Ports
1020    
1021  Haven't written this yet, 'cos I don't understand ports yet.  Haven't written this yet, 'cos I don't understand ports yet.
1022    
1023    
1024  @node Signalling Type Errors,  , Non-immediate Datatypes, How Guile does it  @node Signalling Type Errors
1025  @subsection Signalling Type Errors  @subsection Signalling Type Errors
1026    
1027  Every function visible at the Scheme level should aggressively check the  Every function visible at the Scheme level should aggressively check the
# Line 1083  Signal an error complaining that @var{ob Line 1082  Signal an error complaining that @var{ob
1082  @end deftypefn  @end deftypefn
1083    
1084    
1085  @node Defining New Types (Smobs),  , How Guile does it, Top  @node Defining New Types (Smobs)
1086  @section Defining New Types (Smobs)  @section Defining New Types (Smobs)
1087    
1088  @dfn{Smobs} are Guile's mechanism for adding new non-immediate types to  @dfn{Smobs} are Guile's mechanism for adding new non-immediate types to
# Line 1104  you can build a complete interactive Gui Line 1103  you can build a complete interactive Gui
1103  datatypes described here.)  datatypes described here.)
1104    
1105  @menu  @menu
1106  * Describing a New Type::        * Describing a New Type::
1107  * Creating Instances::            * Creating Instances::
1108  * Typechecking::                  * Typechecking::
1109  * Garbage Collecting Smobs::      * Garbage Collecting Smobs::
1110  * A Common Mistake In Allocating Smobs::    * A Common Mistake In Allocating Smobs::
1111  * Garbage Collecting Simple Smobs::    * Garbage Collecting Simple Smobs::
1112  * A Complete Example::            * A Complete Example::
1113  @end menu  @end menu
1114    
1115  @node Describing a New Type, Creating Instances, Defining New Types (Smobs), Defining New Types (Smobs)  @node Describing a New Type
1116  @subsection Describing a New Type  @subsection Describing a New Type
1117    
1118  To define a new type, the programmer must write four functions to  To define a new type, the programmer must write four functions to
# Line 1140  non-zero) using @code{scm_must_free} and Line 1139  non-zero) using @code{scm_must_free} and
1139  struct.  @xref{Garbage Collecting Smobs}, for more details.  struct.  @xref{Garbage Collecting Smobs}, for more details.
1140    
1141  @item print  @item print
1142  @c GJB:FIXME:: @var{exp} and @var{port} need to refer to a prototype of  @c GJB:FIXME:: @var{exp} and @var{port} need to refer to a prototype of
1143  @c the print function.... where is that, or where should it go?  @c the print function.... where is that, or where should it go?
1144  Guile will apply this function to each instance of the new type to print  Guile will apply this function to each instance of the new type to print
1145  the value, as for @code{display} or @code{write}.  The function should  the value, as for @code{display} or @code{write}.  The function should
1146  write a printed representation of @var{exp} on @var{port}, in accordance  write a printed representation of @var{exp} on @var{port}, in accordance
1147  with the parameters in @var{pstate}.  (For more information on print  with the parameters in @var{pstate}.  (For more information on print
1148  states, see @ref{Ports}.)  The default print function prints @code{#<NAME ADDRESS>}  states, see @ref{Ports}.)  The default print function prints @code{#<NAME ADDRESS>}
1149  where @code{NAME} is the first argument passed to @code{scm_make_smob_type} or  where @code{NAME} is the first argument passed to @code{scm_make_smob_type} or
1150  @code{scm_make_smob_type_mfpe}.  @code{scm_make_smob_type_mfpe}.
1151    
1152  @item equalp  @item equalp
# Line 1209  type@footnote{Warning: There is an ongoi Line 1208  type@footnote{Warning: There is an ongoi
1208  may result in deprecating @code{scm_make_smob_type_mfpe} in next release  may result in deprecating @code{scm_make_smob_type_mfpe} in next release
1209  of Guile.}:  of Guile.}:
1210    
1211  @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))  @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))
1212  This function invokes @code{scm_make_smob_type} on its first two arguments  This function invokes @code{scm_make_smob_type} on its first two arguments
1213  to add a new smob type named @var{name}, with instance size @var{size} to the system.    to add a new smob type named @var{name}, with instance size @var{size} to the system.
1214  It also registers the @var{mark}, @var{free}, @var{print}, @var{equalp} smob  It also registers the @var{mark}, @var{free}, @var{print}, @var{equalp} smob
1215  special functions for that new type.  Any of these parameters can be @code{NULL}  special functions for that new type.  Any of these parameters can be @code{NULL}
1216  to have that special function use the default behaviour for guile.  to have that special function use the default behaviour for guile.
# Line 1236  init_image_type () Line 1235  init_image_type ()
1235  @end example  @end example
1236    
1237    
1238  @node Creating Instances, Typechecking, Describing a New Type, Defining New Types (Smobs)  @node Creating Instances
1239  @subsection Creating Instances  @subsection Creating Instances
1240    
1241  Like other non-immediate types, smobs start with a cell whose @sc{car}  Like other non-immediate types, smobs start with a cell whose @sc{car}
1242  contains typing information, and whose @code{cdr} is free for any use.  For smobs,  contains typing information, and whose @code{cdr} is free for any use.  For smobs,
1243  the @code{cdr} stores a pointer to the internal C structure holding the  the @code{cdr} stores a pointer to the internal C structure holding the
1244  smob-specific data.  smob-specific data.
1245  To create an instance of a smob type following these standards, you should  To create an instance of a smob type following these standards, you should
1246  use @code{SCM_NEWSMOB}:  use @code{SCM_NEWSMOB}:
1247    
1248  @deftypefn Macro void SCM_NEWSMOB(SCM value,long tag,void *data)  @deftypefn Macro void SCM_NEWSMOB (SCM value, long tag, void *data)
1249  Make @var{value} contain a smob instance of the type with tag @var{tag}  Make @var{value} contain a smob instance of the type with tag @var{tag}
1250  and smob data @var{data}.  @var{value} must be previously declared  and smob data @var{data}.  @var{value} must be previously declared
1251  as C type @code{SCM}.  as C type @code{SCM}.
# Line 1256  Since it is often the case (e.g., in smo Line 1255  Since it is often the case (e.g., in smo
1255  create a smob instance and return it, there is also a slightly specialized  create a smob instance and return it, there is also a slightly specialized
1256  macro for this situation:  macro for this situation:
1257    
1258  @deftypefn Macro fn_returns SCM_RETURN_NEWSMOB(long tab, void *data)  @deftypefn Macro fn_returns SCM_RETURN_NEWSMOB (long tab, void *data)
1259  This macro expands to a block of code that creates a smob instance of  This macro expands to a block of code that creates a smob instance of
1260  the type with tag @var{tag} and smob data @var{data}, and returns  the type with tag @var{tag} and smob data @var{data}, and returns
1261  that @code{SCM} value.  It should be the last piece of code in  that @code{SCM} value.  It should be the last piece of code in
1262  a block.  a block.
1263  @end deftypefn  @end deftypefn
1264    
# Line 1336  make_image (SCM name, SCM s_width, SCM s Line 1335  make_image (SCM name, SCM s_width, SCM s
1335    
1336    width = SCM_INUM (s_width);    width = SCM_INUM (s_width);
1337    height = SCM_INUM (s_height);    height = SCM_INUM (s_height);
1338      
1339    image = (struct image *) scm_must_malloc (sizeof (struct image), "image");    image = (struct image *) scm_must_malloc (sizeof (struct image), "image");
1340    image->width = width;    image->width = width;
1341    image->height = height;    image->height = height;
# Line 1349  make_image (SCM name, SCM s_width, SCM s Line 1348  make_image (SCM name, SCM s_width, SCM s
1348  @end example  @end example
1349    
1350    
1351  @node Typechecking, Garbage Collecting Smobs, Creating Instances, Defining New Types (Smobs)  @node Typechecking
1352  @subsection Typechecking  @subsection Typechecking
1353    
1354  Functions that operate on smobs should aggressively check the types of  Functions that operate on smobs should aggressively check the types of
# Line 1401  Note that checking types is a little mor Line 1400  Note that checking types is a little mor
1400  collection; see the description of @code{SCM_GCTYP16} in @ref{Garbage  collection; see the description of @code{SCM_GCTYP16} in @ref{Garbage
1401  Collecting Smobs}.  Collecting Smobs}.
1402    
1403  @c GJB:FIXME:: should talk about guile-snarf somewhere!  @node Garbage Collecting Smobs
   
 @node Garbage Collecting Smobs, A Common Mistake In Allocating Smobs, Typechecking, Defining New Types (Smobs)  
1404  @subsection Garbage Collecting Smobs  @subsection Garbage Collecting Smobs
1405    
1406  Once a smob has been released to the tender mercies of the Scheme  Once a smob has been released to the tender mercies of the Scheme
# Line 1544  very simple.  Since collections occur at Line 1541  very simple.  Since collections occur at
1541  for any unusual activity to interfere with normal code.  for any unusual activity to interfere with normal code.
1542    
1543    
1544  @node A Common Mistake In Allocating Smobs, Garbage Collecting Simple Smobs, Garbage Collecting Smobs, Defining New Types (Smobs)  @node A Common Mistake In Allocating Smobs
1545  @subsection A Common Mistake In Allocating Smobs  @subsection A Common Mistake In Allocating Smobs
1546    
1547  When constructing new objects, you must be careful that the garbage  When constructing new objects, you must be careful that the garbage
# Line 1566  make_image (SCM name, SCM s_width, SCM s Line 1563  make_image (SCM name, SCM s_width, SCM s
1563    
1564    width = SCM_INUM (s_width);    width = SCM_INUM (s_width);
1565    height = SCM_INUM (s_height);    height = SCM_INUM (s_height);
1566      
1567    image = (struct image *) scm_must_malloc (sizeof (struct image), "image");    image = (struct image *) scm_must_malloc (sizeof (struct image), "image");
1568    image->width = width;    image->width = width;
1569    image->height = height;    image->height = height;
# Line 1616  traverse @code{image}, so any objects @c Line 1613  traverse @code{image}, so any objects @c
1613  preserved.  preserved.
1614    
1615    
1616  @node Garbage Collecting Simple Smobs, A Complete Example, A Common Mistake In Allocating Smobs, Defining New Types (Smobs)  @node Garbage Collecting Simple Smobs
1617  @subsection Garbage Collecting Simple Smobs  @subsection Garbage Collecting Simple Smobs
1618    
1619  It is often useful to define very simple smob types --- smobs which have  It is often useful to define very simple smob types --- smobs which have
# Line 1644  other than the smob's header cell. Line 1641  other than the smob's header cell.
1641  @end deftypefun  @end deftypefun
1642    
1643    
1644  @node A Complete Example,  , Garbage Collecting Simple Smobs, Defining New Types (Smobs)  @node A Complete Example
1645  @subsection A Complete Example  @subsection A Complete Example
1646    
1647  Here is the complete text of the implementation of the image datatype,  Here is the complete text of the implementation of the image datatype,
# Line 1692  make_image (SCM name, SCM s_width, SCM s Line 1689  make_image (SCM name, SCM s_width, SCM s
1689    
1690    width = SCM_INUM (s_width);    width = SCM_INUM (s_width);
1691    height = SCM_INUM (s_height);    height = SCM_INUM (s_height);
1692      
1693    image = (struct image *) scm_must_malloc (sizeof (struct image), "image");    image = (struct image *) scm_must_malloc (sizeof (struct image), "image");
1694    image->width = width;    image->width = width;
1695    image->height = height;    image->height = height;
# Line 1795  guile> (clear-image 4) Line 1792  guile> (clear-image 4)
1792  ERROR: In procedure clear-image in expression (clear-image 4):  ERROR: In procedure clear-image in expression (clear-image 4):
1793  ERROR: Wrong type argument in position 1: 4  ERROR: Wrong type argument in position 1: 4
1794  ABORT: (wrong-type-arg)  ABORT: (wrong-type-arg)
1795    
1796  Type "(backtrace)" to get more information.  Type "(backtrace)" to get more information.
1797  guile>  guile>
1798  @end example  @end example
1799    
1800  @bye  @c essay @bye

Legend:
Removed from v.1.11  
changed lines
  Added in v.1.11.2.1

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26