api-smobs.texi 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222
  1. @c -*-texinfo-*-
  2. @c This is part of the GNU Guile Reference Manual.
  3. @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2013, 2014
  4. @c Free Software Foundation, Inc.
  5. @c See the file guile.texi for copying conditions.
  6. @node Smobs
  7. @section Smobs
  8. @cindex smob
  9. A @dfn{smob} is a ``small object''. Before foreign objects were
  10. introduced in Guile 2.0.12 (@pxref{Foreign Objects}), smobs were the
  11. preferred way to for C code to define new kinds of Scheme objects. With
  12. the exception of the so-called ``applicable SMOBs'' discussed below,
  13. smobs are now a legacy interface and are headed for eventual
  14. deprecation. @xref{Deprecation}. New code should use the foreign
  15. object interface.
  16. This section contains reference information related to defining and
  17. working with smobs. For a tutorial-like introduction to smobs, see
  18. ``Defining New Types (Smobs)'' in previous versions of this manual.
  19. @deftypefun scm_t_bits scm_make_smob_type (const char *name, size_t size)
  20. This function adds a new smob type, named @var{name}, with instance size
  21. @var{size}, to the system. The return value is a tag that is used in
  22. creating instances of the type.
  23. If @var{size} is 0, the default @emph{free} function will do nothing.
  24. If @var{size} is not 0, the default @emph{free} function will
  25. deallocate the memory block pointed to by @code{SCM_SMOB_DATA} with
  26. @code{scm_gc_free}. The @var{what} parameter in the call to
  27. @code{scm_gc_free} will be @var{name}.
  28. Default values are provided for the @emph{mark}, @emph{free},
  29. @emph{print}, and @emph{equalp} functions. If you want to customize any
  30. of these functions, the call to @code{scm_make_smob_type} should be
  31. immediately followed by calls to one or several of
  32. @code{scm_set_smob_mark}, @code{scm_set_smob_free},
  33. @code{scm_set_smob_print}, and/or @code{scm_set_smob_equalp}.
  34. @end deftypefun
  35. @cindex finalizer
  36. @cindex finalization
  37. @deftypefn {C Function} void scm_set_smob_free (scm_t_bits tc, size_t (*free) (SCM obj))
  38. This function sets the smob freeing procedure (sometimes referred to as
  39. a @dfn{finalizer}) for the smob type specified by the tag
  40. @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
  41. The @var{free} procedure must deallocate all resources that are
  42. directly associated with the smob instance @var{obj}. It must assume
  43. that all @code{SCM} values that it references have already been freed
  44. and are thus invalid.
  45. It must also not call any libguile function or macro except
  46. @code{scm_gc_free}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
  47. @code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
  48. The @var{free} procedure must return 0.
  49. Note that defining a freeing procedure is not necessary if the resources
  50. associated with @var{obj} consists only of memory allocated with
  51. @code{scm_gc_malloc} or @code{scm_gc_malloc_pointerless} because this
  52. memory is automatically reclaimed by the garbage collector when it is no
  53. longer needed (@pxref{Memory Blocks, @code{scm_gc_malloc}}).
  54. @end deftypefn
  55. Smob free functions must be thread-safe. @xref{Foreign Object Memory
  56. Management}, for a discussion on finalizers and concurrency. If you are
  57. embedding Guile in an application that is not thread-safe, and you
  58. define smob types that need finalization, you might want to disable
  59. automatic finalization, and arrange to call
  60. @code{scm_manually_run_finalizers ()} yourself. @xref{Foreign Objects}.
  61. @deftypefn {C Function} void scm_set_smob_mark (scm_t_bits tc, SCM (*mark) (SCM obj))
  62. This function sets the smob marking procedure for the smob type specified by
  63. the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}.
  64. Defining a marking procedure is almost always the wrong thing to do. It
  65. is much, much preferable to allocate smob data with the
  66. @code{scm_gc_malloc} and @code{scm_gc_malloc_pointerless} functions, and
  67. allow the GC to trace pointers automatically.
  68. Any mark procedures you see currently almost surely date from the time
  69. of Guile 1.8, before the switch to the Boehm-Demers-Weiser collector.
  70. Such smob implementations should be changed to just use
  71. @code{scm_gc_malloc} and friends, and to lose their mark function.
  72. If you decide to keep the mark function, note that it may be called on
  73. objects that are on the free list. Please read and digest the comments
  74. from the BDW GC's @code{gc/gc_mark.h} header.
  75. The @var{mark} procedure must cause @code{scm_gc_mark} to be called
  76. for every @code{SCM} value that is directly referenced by the smob
  77. instance @var{obj}. One of these @code{SCM} values can be returned
  78. from the procedure and Guile will call @code{scm_gc_mark} for it.
  79. This can be used to avoid deep recursions for smob instances that form
  80. a list.
  81. It must not call any libguile function or macro except
  82. @code{scm_gc_mark}, @code{SCM_SMOB_FLAGS}, @code{SCM_SMOB_DATA},
  83. @code{SCM_SMOB_DATA_2}, and @code{SCM_SMOB_DATA_3}.
  84. @end deftypefn
  85. @deftypefn {C Function} void scm_set_smob_print (scm_t_bits tc, int (*print) (SCM obj, SCM port, scm_print_state* pstate))
  86. This function sets the smob printing procedure for the smob type
  87. specified by the tag @var{tc}. @var{tc} is the tag returned by
  88. @code{scm_make_smob_type}.
  89. The @var{print} procedure should output a textual representation of
  90. the smob instance @var{obj} to @var{port}, using information in
  91. @var{pstate}.
  92. The textual representation should be of the form @code{#<name ...>}.
  93. This ensures that @code{read} will not interpret it as some other
  94. Scheme value.
  95. It is often best to ignore @var{pstate} and just print to @var{port}
  96. with @code{scm_display}, @code{scm_write}, @code{scm_simple_format},
  97. and @code{scm_puts}.
  98. @end deftypefn
  99. @deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj2))
  100. This function sets the smob equality-testing predicate for the smob
  101. type specified by the tag @var{tc}. @var{tc} is the tag returned by
  102. @code{scm_make_smob_type}.
  103. The @var{equalp} procedure should return @code{SCM_BOOL_T} when
  104. @var{obj1} is @code{equal?} to @var{obj2}. Else it should return
  105. @code{SCM_BOOL_F}. Both @var{obj1} and @var{obj2} are instances of the
  106. smob type @var{tc}.
  107. @end deftypefn
  108. @deftypefn {C Function} void scm_assert_smob_type (scm_t_bits tag, SCM val)
  109. When @var{val} is a smob of the type indicated by @var{tag}, do nothing.
  110. Else, signal an error.
  111. @end deftypefn
  112. @deftypefn {C Macro} int SCM_SMOB_PREDICATE (scm_t_bits tag, SCM exp)
  113. Return true if @var{exp} is a smob instance of the type indicated by
  114. @var{tag}, or false otherwise. The expression @var{exp} can be
  115. evaluated more than once, so it shouldn't contain any side effects.
  116. @end deftypefn
  117. @deftypefn {C Function} SCM scm_new_smob (scm_t_bits tag, void *data)
  118. @deftypefnx {C Function} SCM scm_new_double_smob (scm_t_bits tag, void *data, void *data2, void *data3)
  119. Make a new smob of the type with tag @var{tag} and smob data @var{data},
  120. @var{data2}, and @var{data3}, as appropriate.
  121. The @var{tag} is what has been returned by @code{scm_make_smob_type}.
  122. The initial values @var{data}, @var{data2}, and @var{data3} are of
  123. type @code{scm_t_bits}; when you want to use them for @code{SCM}
  124. values, these values need to be converted to a @code{scm_t_bits} first
  125. by using @code{SCM_UNPACK}.
  126. The flags of the smob instance start out as zero.
  127. @end deftypefn
  128. @deftypefn {C Macro} scm_t_bits SCM_SMOB_FLAGS (SCM obj)
  129. Return the 16 extra bits of the smob @var{obj}. No meaning is
  130. predefined for these bits, you can use them freely.
  131. @end deftypefn
  132. @deftypefn {C Macro} scm_t_bits SCM_SET_SMOB_FLAGS (SCM obj, scm_t_bits flags)
  133. Set the 16 extra bits of the smob @var{obj} to @var{flags}. No
  134. meaning is predefined for these bits, you can use them freely.
  135. @end deftypefn
  136. @deftypefn {C Macro} scm_t_bits SCM_SMOB_DATA (SCM obj)
  137. @deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_2 (SCM obj)
  138. @deftypefnx {C Macro} scm_t_bits SCM_SMOB_DATA_3 (SCM obj)
  139. Return the first (second, third) immediate word of the smob @var{obj}
  140. as a @code{scm_t_bits} value. When the word contains a @code{SCM}
  141. value, use @code{SCM_SMOB_OBJECT} (etc.) instead.
  142. @end deftypefn
  143. @deftypefn {C Macro} void SCM_SET_SMOB_DATA (SCM obj, scm_t_bits val)
  144. @deftypefnx {C Macro} void SCM_SET_SMOB_DATA_2 (SCM obj, scm_t_bits val)
  145. @deftypefnx {C Macro} void SCM_SET_SMOB_DATA_3 (SCM obj, scm_t_bits val)
  146. Set the first (second, third) immediate word of the smob @var{obj} to
  147. @var{val}. When the word should be set to a @code{SCM} value, use
  148. @code{SCM_SMOB_SET_OBJECT} (etc.) instead.
  149. @end deftypefn
  150. @deftypefn {C Macro} SCM SCM_SMOB_OBJECT (SCM obj)
  151. @deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_2 (SCM obj)
  152. @deftypefnx {C Macro} SCM SCM_SMOB_OBJECT_3 (SCM obj)
  153. Return the first (second, third) immediate word of the smob @var{obj}
  154. as a @code{SCM} value. When the word contains a @code{scm_t_bits}
  155. value, use @code{SCM_SMOB_DATA} (etc.) instead.
  156. @end deftypefn
  157. @deftypefn {C Macro} void SCM_SET_SMOB_OBJECT (SCM obj, SCM val)
  158. @deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_2 (SCM obj, SCM val)
  159. @deftypefnx {C Macro} void SCM_SET_SMOB_OBJECT_3 (SCM obj, SCM val)
  160. Set the first (second, third) immediate word of the smob @var{obj} to
  161. @var{val}. When the word should be set to a @code{scm_t_bits} value, use
  162. @code{SCM_SMOB_SET_DATA} (etc.) instead.
  163. @end deftypefn
  164. @deftypefn {C Macro} {SCM *} SCM_SMOB_OBJECT_LOC (SCM obj)
  165. @deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_2_LOC (SCM obj)
  166. @deftypefnx {C Macro} {SCM *} SCM_SMOB_OBJECT_3_LOC (SCM obj)
  167. Return a pointer to the first (second, third) immediate word of the
  168. smob @var{obj}. Note that this is a pointer to @code{SCM}. If you
  169. need to work with @code{scm_t_bits} values, use @code{SCM_PACK} and
  170. @code{SCM_UNPACK}, as appropriate.
  171. @end deftypefn
  172. @deftypefun SCM scm_markcdr (SCM @var{x})
  173. Mark the references in the smob @var{x}, assuming that @var{x}'s first
  174. data word contains an ordinary Scheme object, and @var{x} refers to no
  175. other objects. This function simply returns @var{x}'s first data word.
  176. @end deftypefun
  177. @c Local Variables:
  178. @c TeX-master: "guile.texi"
  179. @c End: