GNU Info

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

(g-wrap.info)Pointer Arrays


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

Pointer Arrays
..............

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

Pointer arrays provide a method for handling arrays of C pointers to
structures.  At the moment, pointer arrays presume null terminated
arrays of pointers at the C level.  This is a result of the fact that
they were originally implemented to handle an interface that uses null
terminated arrays heavily.  Eventually pointer arrays will be extended
to handle both null terminated and non-null terminated arrays, probably
with two separate types.  This may mean backward-incompatible API
renaming/changes, so be warned.

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

As an example, pretend you have a C function that takes as an argument
an array of Lead* items (i.e. it has an argument of C type Lead**) and
returns an array of Gold* items, you can tell g-wrap how to handle these
pointers and related functions like this:

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

The calls to `make-pointer-array-type' tell g-wrap to create a Scheme
level object for each type that can hold the lower level C pointer
array at the Scheme level.  At the Scheme level, pointer array 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, but you can't directly
create pointer arrays at the Scheme level.  Right now, they're only
created as the return values of C level functions.

The pointer array 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** array objects.
This will usually be handled by some sequence like this:

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

G-wrap will handle arranging for the Scheme level pointer wrappers to be
cleaned up by the garbage collector.

In addition to passing pointer arrays as parameters and receiving them
as return values, the following functions are available at the Scheme
level.  Note that right now, as mentioned above, all of the code
presumes that the pointer arrays are null terminated, so if your C
code's not set up to work thi way, then you can't use this functionality
just yet.

 - Function: pointer-array-ref pointer-array index
     Returns a pointer-token representing the C level pointer at the
     given index in the pointer-array (uses zero-indexing).

     Right now there is no range checking on the index, so you can ask
     for a bogus pointer.


 - Function: pointer-array-length pointer-array
     Returns the number of items in the pointer-array.


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