GNU Info

Info Node: (g-wrap.info)Pointer Tokens

(g-wrap.info)Pointer Tokens


Next: Pointer Arrays Prev: Pointer Tokens and Pointer Arrays Up: Pointer Tokens and Pointer Arrays
Enter node , (file) or (file)node

Pointer Tokens
..............

Before deciding to use pointer tokens, please see the warning here
Note: Pointer Tokens and Pointer Arrays.

Pointer tokens provide a method for handling pointers to C structures.
For example, if you had a C function that took as an argument a Lead*
and returned a Gold*, you could tell g-wrap how to handle these pointers
and related functions.

     (make-pointer-token-type 'Lead* "Lead*")
     (make-pointer-token-type 'Gold* "Gold*")
     (new-function
      'frobnicate
      'Gold* "frobnicate" '((Lead* lead))
      "Frobnicate.")

The calls to `make-pointer-token-type' tell g-wrap to create a Scheme
level object for each type that can hold the lower level C pointer at
the Scheme level.  Pointer token objects are represented as opaque
objects (SMOBs actually).  You can pass them around to wrapped C
functions, and there are some support functions for manipulating them
that are detailed below.  You can't directly create pointer tokens at
the Scheme level.  Right now, they're only created as the return values
of C level functions.

Null pointers are just represented by #f.  If a wrapped function tries
to return a null pointer, g-wrap will convert it to #f, and if you pass
in #f to a function that expects a pointer token then g-wrap will
arrange for a null pointer to be passed to the underlying wrapped
function.

The pointer token items themselves are garbage collected, as you would
expect, but the pointers they contain are never touched directly by the
g-wrap subsystems, so it's up to you (or the functions being called) to
handle de-allocation of the associated C-level Foo* pointers.  This will
usually be handled by some sequence like this:

     (define bar (c-func-to-create-foo-pointer))
     (c-func-to-manipulate-foo-pointer bar)
     (c-func-to-destroy-foo-pointer bar)

FIXME: There are also some functions available at the C level for
manuipulating pointer tokens from there, but at the moment those
functions are not documented.


automatically generated by info2www version 1.2.2.9