1.8 Allocating and deallocating C storage

make subclass(<C-pointer>)

G.f. method

Summary

Allocates a C object on the heap.

Signature

make subclass(<c-pointer>) #key allocator element-count 
                             extra-bytes address => C-pointer

Arguments

subclass: A subclass of <C-pointer>.
allocator: An instance of <function>.
element-count: An instance of <integer>.
extra-bytes: An instance of <integer>.
address: An instance of <integer> or <machine-word>.

Values

c-pointer: An instance of type <c-pointer> pointing to the object.

Library

c-ffi

Module

c-ffi

Description

Allocates a C object on the heap, using whatever standard C allocation function is in use on the target platform (typically malloc) to allocate the storage. This method is applicable to subclasses of <C-pointer> and returns an instance of its argument class.

If the address option is provided, no new storage is allocated, but instead, a new pointer with the given machine word address is returned.

The allocator argument should be a Dylan function that can serve as an allocator. It must accept a single integer argument -- the number of bytes to be allocated -- and return a Dylan <machine-word> that represents the address of the memory it allocated.

The amount of storage allocated by default is the result of:

  size-of(pointer-wrapper-class.referenced-type)

If a positive integer is passed as an extra-bytes option, that number of extra bytes is also allocated.

If a positive integer is passed as a element-count option, space for element-count copies of the referenced type is allocated, taking into account the extra-bytes option for each of them. The element-count argument can be used for allocating arrays of sizes that are not known statically. The keyword element-count is used for this option rather than size in order to avoid conflict with the size collection keyword. The logical size of a collection represented by a pointer wrapper and the number of array elements that implement it may differ; a null-terminated string is an example of such a case.

This make method calls initialize on the wrapper object it generates before returning it.

? define variable *space-for-one-int* = make(<C-int*>);

? *space-for-one-int*[0];
97386437634   // Could have been anything unless the
              // default

// allocator guarantees to zero new memory.

? *space-for-one-int*[0] := 0;
0

? *space-for-one-int*[0];
0

? define variable *space-for-ten-ints* 
    = make(<C-int*>, element-count: 10);

? define C-struct <Z-properties>
    slot type :: <C-int>;
    array slot properties :: <C-int>, 
  end C-struct <Z-properties>;

? define variable *props* = 
    make(<Z-properties>, 
         extra-bytes: 10 * size-of(<C-int>));