Macro

Summary

Executes forms with a variable bound to a dynamic-extent copy of an FLI pointer, possibly with a different type.

Package

fli

Signature

with-coerced-pointer (coerced-pointer &key type pointer-type) pointer &body body => last

Arguments

coerced-pointer

A variable bound to a copy of pointer.

type

The type of the object pointed to by the temporary pointer. This keyword can be used to access the data at the pointer as a different type.

pointer-type

The pointer type of the temporary pointer.

pointer

A FLI pointer of which a copy is made. The lifetime of the copy is across the scope of the with-coerced-pointer macro.

body

A list of forms to be executed across the scope of the temporary pointer binding.

Values

last

The value of the last form in body.

Description

The macro with-coerced-pointer makes a temporary copy of a pointer, and executes a list of forms which may use the copy across the scope of the macro. Once the macro has terminated the memory allocated to the copy of the pointer is automatically freed.

The macro with-coerced-pointer evaluates body with coerced-pointer bound to a dynamic-extent copy of the FLI pointer pointer.

coerced-pointer points to the same foreign object as pointer.

If type is specified, then it must be a FLI type specifying the type that coerced-pointer points to. Alternatively, if pointer-type is specified, then it must be a FLI pointer type specifying the pointer type of coerced-pointer. If neither type nor pointer-type are specified then the type is the same as pointer.

You can use with-coerced-pointer in a similar way to casting a pointer type in C. You can also use it make a temporary FLI pointer that can be changed using incf-pointer or decf-pointer, without affecting pointer.

Note that coerced-pointer has dynamic-extent, so you should not use it after returning from body.

Example

In the following example an array of ten integers is defined, pointed to by array-obj. The macro with-coerced-pointer is used to return the values stored in the array, without altering array-obj, or permanently tying up memory for a second pointer.

(setf array-obj

      (fli:allocate-foreign-object :type :int

                  :nelems 10

                  :initial-contents 

                  '(0 1 2 3 4 5 6 7 8 9)))

(fli:with-coerced-pointer (temp) array-obj

  (dotimes (x 10)

    (print (fli:dereference temp))

    (fli:incf-pointer temp)))

See also

An example of dynamic pointer allocation
allocate-dynamic-foreign-object
free-foreign-object
with-dynamic-foreign-objects