allocate-foreign-object

malloc Functions

Summary

Allocates memory for an instance of a foreign object.

Package

fli

Signatures

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

malloc &key type pointer-type initial-element initial-contents fill nelems size-slot allocation => 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`⇩	The initial value of the newly allocated objects.
`initial-contents`⇩	A list of values to initialize the contents of the newly allocated objects.
`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).

size-slot can be used to initialize a slot in a struct or union type to the size of the object in bytes. If size-slot is supplied then it must be the name of a slot in that type. The slot named by size-slot is set to the size of the object in bytes. This occurs after fill, initial-element and initial-contents are processed. If nelems is greater than 1, then the slot named by size-slot is initialized in each element. If size-slot is not supplied, then no such setting occurs.

The function malloc is a synonym for allocate-foreign-object.

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.

Examples

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)