Function

Summary

Creates and returns a new array which, in addition to the standard functionality, can be a weak array or statically allocated.

Package

common-lisp

Signature

make-array dimensions &key element-type initial-element initial-contents adjustable fill-pointer displaced-to displaced-index-offset weak allocation single-thread => new-array

Arguments

weak

A generalized boolean.

allocation

nil or one of the keywords :new, :static, :old and :long-lived.

single-thread

A generalized boolean.

Description

The standard definition of make-array is extended to accept the keyword arguments :weak, :allocation and :single-thread.

If weak is non-nil, then displaced-to must be nil and if element-type is supplied it must have upgraded-array-element-type t, otherwise an error is signaled. That is, you cannot make a weak array which is displaced or has array-element-type other than t. When weak is non-nil, it makes new-array weak.

If weak is nil, then make-array behaves in the standard way, and new-array is not weak. The value weak defaults to nil. In 64-bit LispWorks, allocation cannot be used with weak and the length of a weak array must be less than 4194304 (2 22 ) elements.

See set-array-weak for a description of weak arrays.

The possible values for allocation have the following meanings:

:new

Allocate the array normally.

nil

Same meaning as :new. This is the default value.

:static

Allocate the array in a static segment.

:long-lived

Allocate the array assuming it is going to be long-lived.

:old

Same meaning as :long-lived

Arrays (including strings) that are passed by address to foreign functions must be static, and so must should be created with :allocation :static.

Allocation with :old or :long-lived is useful when you know that the array will be long-lived, because your program will avoid the overhead of promoting it to the older generations.

If single-thread is true then the system knows that new-array will always be accessed in a single thread context. That makes some operations faster, in particular vector-pop and vector-push. The default value of single-thread is nil.

Compatibility notes

allocation can also be a fixnum n but this is now deprecated. The intent was to allocate the array in generation n, however the allocation is not actually guaranteed to be in the specified generation (although it will be in almost every call).

See also

array-weak-p
set-array-single-thread-p
set-array-weak
Freeing of objects by the GC