Function

Summary

Allocates memory for an instance of a foreign object.

Package

fli

Signature

allocate-foreign-object &key type pointer-type initial-element initial-contents fill nelems size-slot => pointer

Arguments

type

a FLI type specifying the type of the object to be allocated. If type is supplied, pointer-type must not be supplied.

pointer-type

A FLI pointer type specifying the type of the pointer object to be allocated. If pointer-type is supplied, type must not be supplied.

initial-element

A keyword setting the initial value of every element in the newly allocated object to initial-element .

initial-contents

A list of forms which initialize the contents of each element in the newly allocated object.

fill

An integer between 0 to 255.

nelems

An integer specifying how many copies of the object should be allocated. The default value is 1.

size-slot

A symbol naming a slot in the object.

Values

pointer

A pointer to the specified type or pointer-type .

Description

The function allocate-foreign-object allocates memory for a new instance of an object of type type or an instance of a pointer object of type pointer-type . Memory allocated in this manner must be explicitly freed using free-foreign-object once the object is no longer needed.

An integer value of fill is initializes all the bytes of the object. If fill is not supplied, the object is not initialized unless initial-element or initial-contents is passed.

A supplied value of size-slot applies if the type is a struct or union type. The slot size-slot is set to the size of the object in bytes. This occurs after the fill , initial-element and initial-contents arguments are processed. If nelems is greater than 1, then the slot size-slot is initialized in each element. If size-slot is not supplied, then no such setting occurs.

Note: memory allocated by allocate-foreign-object is in the C heap. Therefore pointer (and any copy) cannot be used after save-image or deliver .

Example

In the following example a structure is defined and an instance with a specified initial value of 10 is created with memory allocated using allocate-foreign-object . The dereference function is then used to get the value that point points to, and finally it is freed.

(fli:define-c-typedef LONG :long)

(setq point (fli:allocate-foreign-object

             :type 'LONG

             :initial-element 10))

(fli:dereference point) (fli:free-foreign-object point)

See also

allocate-dynamic-foreign-object
free-foreign-object