mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-20 11:40:18 +02:00
Code Activity

documentation recommends scm_new_smob instead of SCM_NEWSMOB

Browse source 
* doc/ref/api-smobs.texi (Smobs): Document scm_new_smob and
  scm_new_double_smob instead of the SCM_NEWSMOB / SCM_RETURN_NEWSMOB
  family of macros.

* doc/ref/libguile-smobs.texi (Creating Smob Instances): Use
  scm_new_smob.
This commit is contained in:
Andy Wingo 2013-01-22 11:35:25 +01:00
parent 776491caa2
commit 5b70b4e284
2 changed files with 15 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

26
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, 2009
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2013
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@ -129,12 +129,10 @@ Return true iff @var{exp} is a smob instance of the type indicated by
so it shouldn't contain any side effects.
@end deftypefn
@deftypefn {C Macro} void SCM_NEWSMOB (SCM value, scm_t_bits tag, void *data)
@deftypefnx {C Macro} void SCM_NEWSMOB2 (SCM value, scm_t_bits tag, void *data, void *data2)
@deftypefnx {C Macro} void SCM_NEWSMOB3 (SCM value, scm_t_bits tag, void *data, void *data2, void *data3)
Make @var{value} contain a smob instance of the type with tag
@var{tag} and smob data @var{data}, @var{data2}, and @var{data3}, as
appropriate.
@deftypefn {C Function} SCM scm_new_smob (scm_t_bits tag, void *data)
@deftypefnx {C Function} SCM scm_new_double_smob (scm_t_bits tag, void *data, void *data2, void *data3)
Make a new smob of the type with tag @var{tag} and smob data @var{data},
@var{data2}, and @var{data3}, as appropriate.
The @var{tag} is what has been returned by @code{scm_make_smob_type}.
The initial values @var{data}, @var{data2}, and @var{data3} are of
@ -145,20 +143,6 @@ by using @code{SCM_UNPACK}.
The flags of the smob instance start out as zero.
@end deftypefn
Since it is often the case (e.g., in smob constructors) that you will
create a smob instance and return it, there is also a slightly specialized
macro for this situation:
@deftypefn {C Macro} {} SCM_RETURN_NEWSMOB (scm_t_bits tag, void *data)
@deftypefnx {C Macro} {} SCM_RETURN_NEWSMOB2 (scm_t_bits tag, void *data1, void *data2)
@deftypefnx {C Macro} {} SCM_RETURN_NEWSMOB3 (scm_t_bits tag, void *data1, void *data2, void *data3)
This macro expands to a block of code that creates a smob instance of
the type with tag @var{tag} and smob data @var{data}, @var{data2}, and
@var{data3}, as with @code{SCM_NEWSMOB}, etc., and causes the
surrounding function to return that @code{SCM} value. It should be
the last piece of code in a block.
@end deftypefn
@deftypefn {C Macro} scm_t_bits SCM_SMOB_FLAGS (SCM obj)
Return the 16 extra bits of the smob @var{obj}. No meaning is
predefined for these bits, you can use them freely.

22
doc/ref/libguile-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, 2005, 2010, 2011
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011, 2013
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@ -180,7 +180,7 @@ Initialize these fields with @code{SCM_BOOL_F}.
A valid state is one that can be safely acted upon by the @emph{mark}
and @emph{free} functions of your smob type.
@item
Create the smob using @code{SCM_NEWSMOB}, passing it the initialized
Create the smob using @code{scm_new_smob}, passing it the initialized
memory block. (This step will always succeed.)
@item
Complete the initialization of the memory block by, for example,
@ -223,7 +223,7 @@ make_image (SCM name, SCM s_width, SCM s_height)
/* Step 3: Create the smob.
*/
SCM_NEWSMOB (smob, image_tag, image);
smob = scm_new_smob (image_tag, image);
/* Step 4: Finish the initialization.
*/
@ -254,7 +254,7 @@ After it, @var{smob} contains a valid smob that is properly initialized
and protected, and in turn can properly protect the Scheme values in its
@var{image} struct.
But before the smob is completely created, @code{SCM_NEWSMOB} might
But before the smob is completely created, @code{scm_new_smob} might
cause the garbage collector to run. During this garbage collection, the
@code{SCM} values in the @var{image} struct would be invisible to Guile.
It only gets to know about them via the @code{mark_image} function, but
@ -530,13 +530,11 @@ four-word cells, which are appropriately called @dfn{double cells}.
You can use them for @dfn{double smobs} and get two more immediate
words of type @code{scm_t_bits}.
A double smob is created with @code{SCM_NEWSMOB2} or
@code{SCM_NEWSMOB3} instead of @code{SCM_NEWSMOB}. Its immediate
words can be retrieved as @code{scm_t_bits} with
@code{SCM_SMOB_DATA_2} and @code{SCM_SMOB_DATA_3} in addition to
@code{SCM_SMOB_DATA}. Unsurprisingly, the words can be set to
@code{scm_t_bits} values with @code{SCM_SET_SMOB_DATA_2} and
@code{SCM_SET_SMOB_DATA_3}.
A double smob is created with @code{scm_new_double_smob}. Its immediate
words can be retrieved as @code{scm_t_bits} with @code{SCM_SMOB_DATA_2}
and @code{SCM_SMOB_DATA_3} in addition to @code{SCM_SMOB_DATA}.
Unsurprisingly, the words can be set to @code{scm_t_bits} values with
@code{SCM_SET_SMOB_DATA_2} and @code{SCM_SET_SMOB_DATA_3}.
Of course there are also @code{SCM_SMOB_OBJECT_2},
@code{SCM_SMOB_OBJECT_3}, @code{SCM_SET_SMOB_OBJECT_2}, and
@ -599,7 +597,7 @@ make_image (SCM name, SCM s_width, SCM s_height)
/* Step 3: Create the smob.
*/
SCM_NEWSMOB (smob, image_tag, image);
smob = scm_new_smob (image_tag, image);
/* Step 4: Finish the initialization.
*/