1410 |
@xref{Garbage Collecting Smobs}, for more details. |
@xref{Garbage Collecting Smobs}, for more details. |
1411 |
|
|
1412 |
@item free |
@item free |
1413 |
Guile will apply this function to each instance of the new type it could |
Guile will apply this function to each instance of the new type it |
1414 |
not find any live pointers to. The function should release all |
could not find any live pointers to. The function should release all |
1415 |
resources held by the object and return the number of bytes released. |
resources held by the object and return the number of bytes released. |
1416 |
This is analogous to the Java finalization method-- it is invoked at an |
This is analogous to the Java finalization method-- it is invoked at |
1417 |
unspecified time (when garbage collection occurs) after the object is |
an unspecified time (when garbage collection occurs) after the object |
1418 |
dead. The default free function frees the smob data (if the size of the |
is dead. The default free function frees the smob data (if the size |
1419 |
struct passed to @code{scm_make_smob_type} is non-zero) using |
of the struct passed to @code{scm_make_smob_type} is non-zero) using |
1420 |
@code{scm_must_free} and returns the size of that struct. @xref{Garbage |
@code{scm_gc_free}. @xref{Garbage Collecting Smobs}, for more |
1421 |
Collecting Smobs}, for more details. |
details. |
1422 |
|
|
1423 |
@item print |
@item print |
1424 |
@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 |
1557 |
@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_t_bits tag, void *data1, void *data2, void *data3) |
@deftypefnx Macro fn_returns SCM_RETURN_NEWSMOB3(scm_t_bits tag, void *data1, void *data2, void *data3) |
1558 |
This macro expands to a block of code that creates a smob instance of |
This macro expands to a block of code that creates a smob instance of |
1559 |
the type with tag @var{tag} and smob data @var{data} (or @var{data1}, |
the type with tag @var{tag} and smob data @var{data} (or @var{data1}, |
1560 |
@var{data2}, and @var{data3}), and returns that @code{SCM} value. It |
@var{data2}, and @var{data3}), and causes the surrounding function to |
1561 |
should be the last piece of code in a block. |
return that @code{SCM} value. It should be the last piece of code in |
1562 |
|
a block. |
1563 |
@end deftypefn |
@end deftypefn |
1564 |
|
|
1565 |
Guile provides the following functions for managing memory, which are |
Guile provides some functions for managing memory, which are often |
1566 |
often helpful when implementing smobs: |
helpful when implementing smobs. @xref{Memory Blocks}. |
|
|
|
|
@deftypefun {char *} scm_must_malloc (size_t @var{len}, char *@var{what}) |
|
|
Allocate @var{len} bytes of memory, using @code{malloc}, and return a |
|
|
pointer to them. |
|
|
|
|
|
If there is not enough memory available, invoke the garbage collector, |
|
|
and try once more. If there is still not enough, signal an error, |
|
|
reporting that we could not allocate @var{what}. |
|
|
|
|
|
This function also helps maintain statistics about the size of the heap. |
|
|
@end deftypefun |
|
|
|
|
|
@deftypefun {char *} scm_must_realloc (char *@var{addr}, size_t @var{olen}, size_t @var{len}, char *@var{what}) |
|
|
Resize (and possibly relocate) the block of memory at @var{addr}, to |
|
|
have a size of @var{len} bytes, by calling @code{realloc}. Return a |
|
|
pointer to the new block. |
|
|
|
|
|
If there is not enough memory available, invoke the garbage collector, |
|
|
and try once more. If there is still not enough, signal an error, |
|
|
reporting that we could not allocate @var{what}. |
|
|
|
|
|
The value @var{olen} should be the old size of the block of memory at |
|
|
@var{addr}; it is only used for keeping statistics on the size of the |
|
|
heap. |
|
|
@end deftypefun |
|
|
|
|
|
@deftypefun void scm_must_free (char *@var{addr}) |
|
|
Free the block of memory at @var{addr}, using @code{free}. If |
|
|
@var{addr} is zero, signal an error, complaining of an attempt to free |
|
|
something that is already free. |
|
|
|
|
|
This does no record-keeping; instead, the smob's @code{free} function |
|
|
must take care of that. |
|
|
|
|
|
This function isn't usually sufficiently different from the usual |
|
|
@code{free} function to be worth using. |
|
|
@end deftypefun |
|
1567 |
|
|
1568 |
|
|
1569 |
Continuing the above example, if the global variable @code{image_tag} |
Continuing the above example, if the global variable @code{image_tag} |
1598 |
width = SCM_INUM (s_width); |
width = SCM_INUM (s_width); |
1599 |
height = SCM_INUM (s_height); |
height = SCM_INUM (s_height); |
1600 |
|
|
1601 |
image = (struct image *) scm_must_malloc (sizeof (struct image), "image"); |
image = (struct image *) scm_gc_malloc (sizeof (struct image), "image"); |
1602 |
image->width = width; |
image->width = width; |
1603 |
image->height = height; |
image->height = height; |
1604 |
image->pixels = scm_must_malloc (width * height, "image pixels"); |
image->pixels = scm_gc_malloc (width * height, "image pixels"); |
1605 |
image->name = name; |
image->name = name; |
1606 |
image->update_func = SCM_BOOL_F; |
image->update_func = SCM_BOOL_F; |
1607 |
|
|
1609 |
@} |
@} |
1610 |
@end example |
@end example |
1611 |
|
|
|
|
|
1612 |
@node Type checking |
@node Type checking |
1613 |
@subsection Type checking |
@subsection Type checking |
1614 |
|
|
1757 |
|
|
1758 |
The @code{free} function must release any resources used by the smob. |
The @code{free} function must release any resources used by the smob. |
1759 |
However, it need not free objects managed by the collector; the |
However, it need not free objects managed by the collector; the |
1760 |
collector will take care of them. The return type of the @code{free} |
collector will take care of them. For historical reasons, the return |
1761 |
function should be @code{size_t}, an unsigned integral type; the |
type of the @code{free} function should be @code{size_t}, an unsigned |
1762 |
@code{free} function should return the number of bytes released, to help |
integral type; the @code{free} function should always return zero. |
|
the collector maintain statistics on the size of the heap. |
|
1763 |
|
|
1764 |
Here is how we might write the @code{free} function for the image smob |
Here is how we might write the @code{free} function for the image smob |
1765 |
type: |
type: |
1768 |
free_image (SCM image_smob) |
free_image (SCM image_smob) |
1769 |
@{ |
@{ |
1770 |
struct image *image = (struct image *) SCM_SMOB_DATA (image_smob); |
struct image *image = (struct image *) SCM_SMOB_DATA (image_smob); |
|
size_t size = image->width * image->height + sizeof (*image); |
|
1771 |
|
|
1772 |
free (image->pixels); |
scm_gc_free (image->pixels, image->width * image->height, "image pixels"); |
1773 |
free (image); |
scm_gc_free (image, sizeof (struct image), "image"); |
1774 |
|
|
1775 |
return size; |
return 0; |
1776 |
@} |
@} |
1777 |
@end example |
@end example |
1778 |
|
|
1811 |
width = SCM_INUM (s_width); |
width = SCM_INUM (s_width); |
1812 |
height = SCM_INUM (s_height); |
height = SCM_INUM (s_height); |
1813 |
|
|
1814 |
image = (struct image *) scm_must_malloc (sizeof (struct image), "image"); |
image = (struct image *) scm_gc_malloc (sizeof (struct image), "image"); |
1815 |
image->width = width; |
image->width = width; |
1816 |
image->height = height; |
image->height = height; |
1817 |
image->pixels = scm_must_malloc (width * height, "image pixels"); |
image->pixels = scm_gc_malloc (width * height, "image pixels"); |
1818 |
|
|
1819 |
/* THESE TWO LINES HAVE CHANGED: */ |
/* THESE TWO LINES HAVE CHANGED: */ |
1820 |
image->name = scm_string_copy (name); |
image->name = scm_string_copy (name); |
1942 |
width = SCM_INUM (s_width); |
width = SCM_INUM (s_width); |
1943 |
height = SCM_INUM (s_height); |
height = SCM_INUM (s_height); |
1944 |
|
|
1945 |
image = (struct image *) scm_must_malloc (sizeof (struct image), "image"); |
image = (struct image *) scm_gc_malloc (sizeof (struct image), "image"); |
1946 |
image->width = width; |
image->width = width; |
1947 |
image->height = height; |
image->height = height; |
1948 |
image->pixels = scm_must_malloc (width * height, "image pixels"); |
image->pixels = scm_gc_malloc (width * height, "image pixels"); |
1949 |
image->name = name; |
image->name = name; |
1950 |
image->update_func = SCM_BOOL_F; |
image->update_func = SCM_BOOL_F; |
1951 |
|
|
1986 |
free_image (SCM image_smob) |
free_image (SCM image_smob) |
1987 |
@{ |
@{ |
1988 |
struct image *image = (struct image *) SCM_SMOB_DATA (image_smob); |
struct image *image = (struct image *) SCM_SMOB_DATA (image_smob); |
|
size_t size = image->width * image->height + sizeof (struct image); |
|
1989 |
|
|
1990 |
free (image->pixels); |
scm_gc_free (image->pixels, image->width * image->height, "image pixels"); |
1991 |
free (image); |
scm_gc_free (image, sizeof (struct image), "image"); |
1992 |
|
|
1993 |
return size; |
return 0; |
1994 |
@} |
@} |
1995 |
|
|
1996 |
static int |
static int |