Copyright (C) 2000-2012 |
GNU Info (g-wrap.info)Pointer ArraysPointer 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 |