make-array 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

Values

Description

The function make-array has been extended to accept the keyword arguments :weak, :allocation and :single-thread. Other uses of dimensions, element-type, initial-element, initial-contents, adjustable, fill-pointer, displaced-to, displaced-index-offset are used as specified by ANSI Common Lisp.

LispWorks supports specialized array representations for values of element-type that upgrade to base-char, bmp-char, character, single-float, double-float, (complex single-float), (complex double-float), (unsigned-byte n) and (signed-byte n) where n is 1, 2, 4, 8, 16, 32 or (on 64-bit LispWorks) 64.

If weak is nil (the default), then make-array behaves in the standard way, and new-array is not weak.

If weak is non-nil, then new-array is a weak array. In this case, displaced-to must be nil and if element-type is supplied it must be equivalent to t according to upgraded-array-element-type, otherwise an error is signaled. That is, you cannot make a weak array that is displaced or has array-element-type other than t. In 64-bit LispWorks, allocation cannot be used with weak and the length of a weak array must be less than 4194304 (222) elements.

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

The possible values for allocation have the following meanings:

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

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.

Allocation with :static allocates in the default static generation number, which is set assuming that such objects are long-lived. If you need static arrays that are short-lived, it is better to allocate them with :static-new, or maybe :pinnable.

Allocation with :pinnable is implemented properly only in 64-bit LispWorks. In 32-bit LispWorks, it does the same as :static. In 64-bit, it allocates an array that can be pinned either explicitly by the macro with-pinned-objects or implicitly by the foreign type :lisp-simple-1d-array. Such arrays are useful when you want to pass them to foreign functions, but you do not know if they are long-lived or short-lived. When using :pinnable, the :element-type keyword must be used to specify an element-type that does not upgrade (by upgraded-array-element-type) to t or character. In LispWorks 8.0 that includes integers up to 64 bits, double-float, single-float, (complex double-float) and (complex single-float).

"Pinnable" arrays are handled by the memory management system like ordinary arrays, except that the memory management system will not move them while they are pinned. They are intended to be used for arrays that are passed to foreign functions directly. If the type of the argument in the foreign function call that takes the "pinnable" array is :lisp-simple-1d-array, then the array is pinned automatically during the call. For the foreign type :lisp-array, you need to pin it explcitly around the call using with-pinned-objects. with-pinned-objects can be used to pin the array in an arbitrary dynamic scope, but it adds overhead to the GC, so should be avoided.

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

make-array in the Common Lisp HyperSpec
array-weak-p
set-array-single-thread-p
set-array-weak
upgraded-array-element-type
:lisp-simple-1d-array
with-pinned-objects
11.6.8 Freeing of objects by the GC