mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-09 21:40:33 +02:00
Code Activity

Update doc of `scm_gc_protect_object ()' and SMOB mark/free.

Browse source 
* doc/ref/api-memory.texi (Garbage Collection
  Functions)[scm_gc_protect_object]: Explain that it's equivalent to
  storing in a global variable.

* doc/ref/api-smobs.texi (Smobs)[scm_set_smob_free]: Expand on the
  relationship with `scm_gc_malloc ()'.
  [scm_set_smob_mark]: Explain that it's usually not needed.
This commit is contained in:
Ludovic Courtès 2009-09-09 19:14:04 +02:00
parent 56273dea4b
commit f07c349eb3
2 changed files with 45 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

5
doc/ref/api-memory.texi
View file

@ -41,6 +41,11 @@ otherwise might be. When you are done with the object, call
the object remains protected until it has been unprotected as many times
as it was protected. It is an error to unprotect an object more times
than it has been protected. Returns the SCM object it was passed.
Note that storing @var{obj} in a C global variable has the same
effect@footnote{In Guile up to version 1.8, C global variables were not
scanned by the garbage collector; hence, @code{scm_gc_protect_object}
was the only way in C to prevent a Scheme object from being freed.}.
@end deftypefn
@deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj})

57
doc/ref/api-smobs.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@ -8,6 +8,8 @@
@node Smobs
@section Smobs
@cindex smob
This chapter contains reference information related to defining and
working with smobs. See @ref{Defining New Types (Smobs)} for a
tutorial-like introduction to smobs.
@ -33,10 +35,47 @@ immediately followed by calls to one or several of
@code{scm_set_smob_print}, and/or @code{scm_set_smob_equalp}.
@end deftypefun
@cindex finalizer
@cindex finalization
@deftypefn {C Function} void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM obj))
This function sets the smob freeing procedure (sometimes referred to as
a @dfn{finalizer}) for the smob type specified by the tag
@var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
The @var{free} procedure must deallocate all resources that are
directly associated with the smob instance @var{OBJ}. It must assume
that all @code{SCM} values that it references have already been freed
and are thus invalid.
It must also not call any libguile function or macro except
@code{scm_gc_free}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
@code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
The @var{free} procedure must return 0.
Note that defining a freeing procedure is not necessary if the resources
associated with @var{obj} consists only of memory allocated with
@code{scm_gc_malloc} or @code{scm_gc_malloc_pointerless} because this
memory is automatically reclaimed by the garbage collector when it is no
longer needed (@pxref{Memory Blocks, @code{scm_gc_malloc}}).
@end deftypefn
@cindex precise marking
@deftypefn {C Function} void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM obj))
This function sets the smob marking procedure for the smob type specified by
the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
Defining a marking procedure should rarely be necessary because all the
process' memory (with the exception of @code{scm_gc_malloc_pointerless}
or read-only regions) is scanned for live pointers@footnote{Conversely,
in Guile up to the 1.8 series, the marking procedure was required. The
reason is that Guile's GC would only look for pointers in the memory
area used for built-in types (the @dfn{cell heap}), not in
user-allocated or statically allocated memory. This approach is often
referred to as @dfn{precise marking}.}.
The @var{mark} procedure must cause @code{scm_gc_mark} to be called
for every @code{SCM} value that is directly referenced by the smob
instance @var{obj}. One of these @code{SCM} values can be returned
@ -49,22 +88,6 @@ It must not call any libguile function or macro except
@code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
@end deftypefn
@deftypefn {C Function} void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM obj))
This function sets the smob freeing procedure for the smob type
specified by the tag @var{tc}. @var{tc} is the tag returned by
@code{scm_make_smob_type}.
The @var{free} procedure must deallocate all resources that are
directly associated with the smob instance @var{OBJ}. It must assume
that all @code{SCM} values that it references have already been freed
and are thus invalid.
It must also not call any libguile function or macro except
@code{scm_gc_free}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
@code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
The @var{free} procedure must return 0.
@end deftypefn
@deftypefn {C Function} void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM obj, SCM port, scm_print_state* pstate))
This function sets the smob printing procedure for the smob type