Application Programming Interface for ArrayAllocators.jl

ArrayAllocators

Defines an array allocator interface and concrete array allocators using malloc, calloc, and memory alignment.

Examples

using ArrayAllocators

Array{UInt8}(malloc, 100)
Array{UInt8}(calloc, 1024, 1024)
Array{UInt8}(MemAlign(2^16), (1024, 1024, 16))

See also NumaAllocators, SafeByteCalculators

calloc

CallocAllocator singleton instance. calloc will allocate memory and guarantee initialization to 0. See the type for details and the C standard library function for further details.

Example

julia> A = Array{UInt8}(calloc, 16, 16);

julia> sum(A)
0x0000000000000000

malloc

MallocAllocator singleton instance. malloc will only allocate memory. It does not initialize memory is is similar in use as undef. See the type and the C standard library function for details.

Example

julia> Array{UInt8}(malloc, 16, 16);

MemAlign([alignment::Integer])

Allocate aligned memory. Alias for platform specific implementations.

alignment must be a power of 2.

On POSIX systems, alignment must be a multiple of sizeof(Ptr). On Windows, alignment must be a multiple of 2^16.

If alignment is not specified, it will be set to min_alignment(MemAlign).

MemAlign is a constant alias for one the following platform specific implementations.

• POSIX (Linux and macOS): POSIX.PosixMemAlign
• Windows: Windows.WinMemAlign.

alignment(alloc::AbstractMemAlign)

Get byte alignment of the AbstractMemAlign array allocator.

min_alignment(::AbstractMemAlign)

Get the minimum byte alignment of the AbstractMemAlign array allocator.

CallocAllocator()

Use Libc.calloc to allocate an array. This is similar to zeros, except that the Libc implementation or the operating system may allocate and zero the memory in a lazy fashion.

See also https://en.cppreference.com/w/c/memory/calloc .

MallocAllocator()

Allocate array using Libc.malloc. This is not meant to be useful but rather just to prototype the concept for a custom array allocator concept. This should be similar to using undef.

See also https://en.cppreference.com/w/c/memory/malloc .

UndefAllocator{B}

Allocate arrays using the builtin undef method. The B parameter is a ByteCalculator

AbstractArrayAllocator{B}

Parent abstract type for array allocators. Parameter B is an AbstractByteCalculator Defines Array{T}(allocator, dims...) where T = Array{T}(allocator, dims)

AbstractMemAlign{B} <: AbstractArrayAllocator{B}

Abstract supertype for aligned memory allocators.

DefaultByteCalculator

Alias for ByteCalculators.CheckedMulByteCalculator representing the byte calculator used with subtypes of AbstractArrayAllocator when one is not specified.

wrap_libc_pointer(::Type{A}, ptr::Ptr{T}, dims) where {T, A <: AbstractArray{T}}
wrap_libc_pointer(ptr::Ptr{T}, dims) where {T, A <: AbstractArray{T}}

Checks to see if ptr is C_NULL for an OutOfMemoryError. Owns the array such that Libc.free is used.

ArrayAllocators.Windows

Defines array allocators on Windows.

Examples

using ArrayAllocators.Windows

Array{UInt8}(WinMemAlign(2^16), 1024)

WinMemAlign([alignment, lowestStartingAddress, highestStartingAddress])

Uses VirtualAlloc2 to allocate aligned memory. alignment must be a power of 2 and larger than 65536.

MemAddressRequirements

See https://docs.microsoft.com/en-us/windows/win32/api/winnt/ns-winnt-memaddressrequirements

MemExtendedParameterAddressRequirements

This is a Julian structure where the requirements field is Base.RefValue{MemAddressRequirements}

See https://docs.microsoft.com/en-us/windows/win32/api/winnt/ns-winnt-memextendedparameter

See also _MemExtendedParameterAddressRequirements

ArrayAllocators.POSIX

Defines ArrayAllocators for POSIX systems such as macOS or Linux.

Example

using ArrayAllocators.POSIX

Array{UInt16}(PosixMemAlign(), 1024)

PosixMemAlign([alignment::Integer])

Uses posix_memalign to allocate aligned memory. alignment must be a power of 2 and larger than sizeof(Ptr).

If alignment is provided, it will be set to min_alignment(PosixMemAlign).

Example

julia> Array{UInt8}(PosixMemAlign(32), 16, 16);