All Manuals > Foreign Language Interface User Guide and Reference Manual > 3 FLI Pointers

3.1 Creating and copying pointers

This section discusses how to create a FLI pointer, how to copy it, and where the memory is actually allocated.

3.1.1 Creating pointers

Many FLI functions when called return a pointer to the object created. For example, a form such as:

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

will return something similar to the following:

#<Pointer to type :INT = #x007608A0>

This is a FLI pointer object, pointing to an object at address #x007608A0 of type :int. Note that the memory address is printed in hexadecimal format, but when you use the FLI pointer functions and macros discussed in this chapter, numeric values are interpreted as base 10 unless you use Lisp reader syntax such as #x.

To use the pointer in the future it needs to be bound to a Lisp variable. This can be done by using setq.

(setq point1 (fli:allocate-foreign-object :type :int)

A pointer can be explicitly created, rather than being returned during the allocation of memory for a FLI object, by using make-pointer. In the next example a pointer is made pointing to an :int type at the address 100, and is bound to the Lisp variable point2.

(setq point2 (fli:make-pointer :address 100 :type :int))

For convenience you may wish to define your own pointer types, for example:

(fli:define-foreign-pointer my-pointer-type :int)
(setq point3 
      (fli:make-pointer :address 100 
                        :pointer-type 'my-pointer-type))

point3 contains the same type and address information as point2.

A pointer which holds the address of a foreign symbol, either one which is defined in foreign code or one that is defined in Lisp using define-foreign-callable, can be created either by make-pointer with :symbol-name or foreign-function-pointer.

3.1.2 Copying pointers

Suppose the Lisp variable point3 is bound to a FLI pointer as in 3.1.1 Creating pointers. To make a copy of the pointer it is not sufficient to do the following:

(setq point4 point3)

This simply sets point4 to contain the same pointer object as point3. Thus if the pointer is changed using point3, a similar change is observed when looking in point4. To create a distinct copy of the pointer object you should use copy-pointer, which returns a new pointer object with the same address and type as the old one, as the following example shows.

(setq point5 (fli:copy-pointer point3))

3.1.3 Allocation of FLI memory

Foreign objects do take up memory. If a foreign object is no longer needed, it should be deallocated using free-foreign-object. This should be done only once for each foreign object, regardless of the number of pointer objects that contain its address. After freeing a foreign object, any pointers or copies of pointers containing its address will give unpredictable results if the memory is accessed.

FLI memory is allocated using malloc() so it comes from the C heap.

The FLI pointer object itself is a Lisp object, but the memory it points to does not show up in the output of room. Therefore you must use Operating System tools to see the virtual address size of the program.

Foreign Language Interface User Guide and Reference Manual - 01 Dec 2021 19:34:57