doc/ref/api-foreign-objects.texi

   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
   7 @node Foreign Objects
   8 @section Foreign Objects
   9
  10 @cindex foreign object
  11
  12 This chapter contains reference information related to defining and
  13 working with foreign objects.  @xref{Defining New Foreign Object Types},
  14 for a tutorial-like introduction to foreign objects.
  15
  16 @deftp {C Type} scm_t_struct_finalize
  17 This function type returns @code{void} and takes one @code{SCM}
  18 argument.
  19 @end deftp
  20
  21 @deftypefn {C Function} SCM scm_make_foreign_object_type (SCM name, SCM slots, scm_t_struct_finalize finalizer)
  22 Create a fresh foreign object type.  @var{name} is a symbol naming the
  23 type.  @var{slots} is a list of symbols, each one naming a field in the
  24 foreign object type.  @var{finalizer} indicates the finalizer, and may
  25 be @code{NULL}.
  26 @end deftypefn
  27
  28 @cindex finalizer
  29 @cindex finalization
  30
  31 We recommend that finalizers be avoided if possible.  @xref{Foreign
  32 Object Memory Management}.  Finalizers must be async-safe and
  33 thread-safe.  Again, @pxref{Foreign Object Memory Management}.  If you
  34 are embedding Guile in an application that is not thread-safe, and you
  35 define foreign object types that need finalization, you might want to
  36 disable automatic finalization, and arrange to call
  37 @code{scm_manually_run_finalizers ()} yourself.
  38
  39 @deftypefn {C Function} int scm_set_automatic_finalization_enabled (int enabled_p)
  40 Enable or disable automatic finalization.  By default, Guile arranges to
  41 invoke object finalizers automatically, in a separate thread if
  42 possible.  Passing a zero value for @var{enabled_p} will disable
  43 automatic finalization for Guile as a whole.  If you disable automatic
  44 finalization, you will have to call @code{scm_run_finalizers ()}
  45 periodically.
  46
  47 Unlike most other Guile functions, you can call
  48 @code{scm_set_automatic_finalization_enabled} before Guile has been
  49 initialized.
  50
  51 Return the previous status of automatic finalization.
  52 @end deftypefn
  53
  54 @deftypefn {C Function} int scm_run_finalizers (void)
  55 Invoke any pending finalizers.  Returns the number of finalizers that
  56 were invoked.  This function should be called when automatic
  57 finalization is disabled, though it may be called if it is enabled as
  58 well.
  59 @end deftypefn
  60
  61 @deftypefn {C Function} void scm_assert_foreign_object_type (SCM type, SCM val)
  62 When @var{val} is a foreign object of the given @var{type}, do nothing.
  63 Otherwise, signal an error.
  64 @end deftypefn
  65
  66 @deftypefn {C Function} SCM scm_make_foreign_object_0 (SCM type)
  67 @deftypefnx {C Function} SCM scm_make_foreign_object_1 (SCM type, void *val0)
  68 @deftypefnx {C Function} SCM scm_make_foreign_object_2 (SCM type, void *val0, void *val1)
  69 @deftypefnx {C Function} SCM scm_make_foreign_object_3 (SCM type, void *val0, void *val1, void *val2)
  70 @deftypefnx {C Function} SCM scm_make_foreign_object_n (SCM type, size_t n, void *vals[])
  71 Make a new foreign object of the type with type @var{type} and
  72 initialize the first @var{n} fields to the given values, as appropriate.
  73
  74 The number of fields for objects of a given type is fixed when the type
  75 is created.  It is an error to give more initializers than there are
  76 fields in the value.  It is perfectly fine to give fewer initializers
  77 than needed; this is convenient when some fields are of non-pointer
  78 types, and would be easier to initialize with the setters described
  79 below.
  80 @end deftypefn
  81
  82 @deftypefn {C Function} void* scm_foreign_object_ref (SCM obj, size_t n);
  83 @deftypefnx {C Function} scm_t_bits scm_foreign_object_unsigned_ref (SCM obj, size_t n);
  84 @deftypefnx {C Function} scm_t_signed_bits scm_foreign_object_signed_ref (SCM obj, size_t n);
  85 Return the value of the @var{n}th field of the foreign object @var{obj}.
  86 The backing store for the fields is as wide as a @code{scm_t_bits}
  87 value, which is at least as wide as a pointer.  The different variants
  88 handle casting in a portable way.
  89 @end deftypefn
  90
  91 @deftypefn {C Function} void scm_foreign_object_set_x (SCM obj, size_t n, void *val);
  92 @deftypefnx {C Function} void scm_foreign_object_unsigned_set_x (SCM obj, size_t n, scm_t_bits val);
  93 @deftypefnx {C Function} void scm_foreign_object_signed_set_x (SCM obj, size_t n, scm_t_signed_bits val);
  94 Set the value of the @var{n}th field of the foreign object @var{obj} to
  95 @var{val}, after portably converting to a @code{scm_t_bits} value, if
  96 needed.
  97 @end deftypefn
  98
  99 One can also access foreign objects from Scheme.  @xref{Foreign Objects
 100 and Scheme}, for some examples.
 101
 102 @example
 103 (use-modules (system foreign-object))
 104 @end example
 105
 106 @deffn {Scheme Procedure} make-foreign-object-type name slots [#:finalizer=#f]
 107 Make a new foreign object type.  See the above documentation for
 108 @code{scm_make_foreign_object_type}; these functions are exactly
 109 equivalent, except for the way in which the finalizer gets attached to
 110 instances (an internal detail).
 111
 112 The resulting value is a GOOPS class.  @xref{GOOPS}, for more on classes
 113 in Guile.
 114 @end deffn
 115
 116 @deffn {Scheme Syntax} define-foreign-object-type name constructor (slot ...) [#:finalizer=#f]
 117 A convenience macro to define a type, using
 118 @code{make-foreign-object-type}, and bind it to @var{name}.  A
 119 constructor will be bound to @var{constructor}, and getters will be
 120 bound to each of @var{slot...}.
 121 @end deffn
 122
 123 @c Local Variables:
 124 @c TeX-master: "guile.texi"
 125 @c End: