9.1 Introduction to generalised C buffers

Generalised C buffers are meant to be used in interfaces to foreign C language libraries, when a pointer to raw data is required as argument.

A generalised C buffer is an object capable of holding an array of mutable bytes referenced by a pointer; such Scheme objects are: bytevectors, pointer objects, instances of memory-block.

A generalised C sticky buffer is an object capable of holding an array of mutable bytes referenced by a pointer, whose data area is never moved around by the garbage collector; such Scheme objects are: pointer objects, instances of memory-block. Sticky buffers are meant to be used when calling out to C functions that call back to Scheme.

(vicare-scheme)Memory blocks for details on memory blocks.

Two arguments to function are usually needed to represent a generalised C buffer: the buffer value itself and an optional length.

1. The buffer argument is meant to be either bytevector, or memory-block instance, or pointer object.
2. The length argument is meant to be #f or an exact integer in the range of the C language type size_t. When the buffer argument is a pointer object: the length argument must represent the number of bytes available in the referenced memory block; otherwise the length argument is ignored.

Here is an example function accepting a generalised C buffer argument buf and its optional length argument buf.len:

(define fun
  (case-lambda
    ((buf)
     (fun buf #f))
    ((buf buf.len)
     (define who 'fun)
     (with-arguments-validation (who)
         ((general-c-buffer     buf)
          (general-c-buffer.len buf buf.len))
       (do-something-with buf buf.len)))))