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 |
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 |
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, |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
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. |
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 |
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 |
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 |
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 |
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 |
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 |
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] |
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] |
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 |
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 |
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 |
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 |
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. |
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}. |
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 |
|
|
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; |
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 |
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 |
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 |
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; |
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 |
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, |
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; |
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 |