diff options
-rw-r--r-- | doc/ref/api-smobs.texi | 26 | ||||
-rw-r--r-- | doc/ref/libguile-smobs.texi | 22 |
2 files changed, 15 insertions, 33 deletions
diff --git a/doc/ref/api-smobs.texi b/doc/ref/api-smobs.texi index 6b042367e..cb2034ce1 100644 --- a/doc/ref/api-smobs.texi +++ b/doc/ref/api-smobs.texi @@ -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. diff --git a/doc/ref/libguile-smobs.texi b/doc/ref/libguile-smobs.texi index eb938f099..6f7c0f45f 100644 --- a/doc/ref/libguile-smobs.texi +++ b/doc/ref/libguile-smobs.texi @@ -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. */ |