external/cffi.darcs/doc/shareable-vectors.txt

   1
   2 # Shareable Byte Vectors
   3
   4 Function: make-shareable-byte-vector size
   5
   6 Create a vector of element type (UNSIGNED-BYTE 8) suitable for passing
   7 to WITH-POINTER-TO-VECTOR-DATA.
   8
   9 ;; Minimal implementation:
  10 (defun make-shareable-byte-vector (size)
  11   (make-array size :element-type '(unsigned-byte 8)))
  12
  13
  14 Macro: with-pointer-to-vector-data (ptr-var vector) &body body
  15
  16 Bind PTR-VAR to a pointer to the data contained in a shareable byte
  17 vector.
  18
  19 VECTOR must be a shareable vector created by MAKE-SHAREABLE-BYTE-VECTOR.
  20
  21 PTR-VAR may point directly into the Lisp vector data, or it may point
  22 to a temporary block of foreign memory which will be copied to and
  23 from VECTOR.
  24
  25 Both the pointer object in PTR-VAR and the memory it points to have
  26 dynamic extent.  The results are undefined if foreign code attempts to
  27 access this memory outside this dynamic contour.
  28
  29 The implementation must guarantee the memory pointed to by PTR-VAR
  30 will not be moved during the dynamic contour of this operator, either
  31 by creating the vector in a static area or temporarily disabling the
  32 garbage collector.
  33
  34 ;; Minimal (copying) implementation:
  35 (defmacro with-pointer-to-vector-data ((ptr-var vector) &body body)
  36   (let ((vector-var (gensym))
  37         (size-var (gensym)))
  38     `(let* ((,vector-var ,vector)
  39             (,size-var (length ,vector-var)))
  40        (with-foreign-ptr (,ptr-var ,size-var)
  41          (mem-write-vector ,vector-var ,ptr :uint8)
  42          (prog1
  43              (progn ,@body)
  44            (mem-read-vector ,vector-var ,ptr-var :uint8 ,size-var))))))