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

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

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

revision 1.3 by ttn, Tue Jan 8 08:29:00 2002 UTC revision 1.4 by mvo, Thu Feb 28 20:58:50 2002 UTC
# Line 1410  refers to.  The default smob mark functi Line 1410  refers to.  The default smob mark functi
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
# Line 1557  macro for this situation: Line 1557  macro for this situation:
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}
# Line 1634  make_image (SCM name, SCM s_width, SCM s Line 1598  make_image (SCM name, SCM s_width, SCM s
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    
# Line 1645  make_image (SCM name, SCM s_width, SCM s Line 1609  make_image (SCM name, SCM s_width, SCM s
1609  @}  @}
1610  @end example  @end example
1611    
   
1612  @node Type checking  @node Type checking
1613  @subsection Type checking  @subsection Type checking
1614    
# Line 1794  as its only argument. Line 1757  as its only argument.
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:
# Line 1806  size_t Line 1768  size_t
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    
# Line 1850  make_image (SCM name, SCM s_width, SCM s Line 1811  make_image (SCM name, SCM s_width, SCM s
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);
# Line 1981  make_image (SCM name, SCM s_width, SCM s Line 1942  make_image (SCM name, SCM s_width, SCM s
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    
# Line 2025  static size_t Line 1986  static size_t
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

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4

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