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.

allocation

A keyword, either :dynamic or :static.

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.

If allocation is :static then memory is allocated in the C heap and must be explicitly freed using free-foreign-object once the object is no longer needed.

If allocation is :dynamic, then allocate-foreign-object allocates memory for the object and pointer within the scope of the body of with-dynamic-foreign-objects. This is equivalent to using allocate-dynamic-foreign-object.

The default value of allocation is :static.

An integer value of fill 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.

If initial-contents is supplied and its length is less than nelems, then the remaining elements are not initialized.

If initial-contents is supplied and its length is greater than nelems, then the length of initial-contents overrides nelems. This is a common case where initial-contents is supplied and nelems is omitted (and hence defaults to 1).

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.

Notes

When allocation is :static, 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
FLI Pointers