Defines functions for memory allocation, alignment, copying, and comparing.
Porters
All of the "Unchecked" and "Free" functions must be implemented, but they should not be called directly. The Starboard platform wraps them with extra accounting under certain circumstances.
Porters and Application Developers
Nobody should call the "Checked", "Unchecked" or "Free" functions directly because that evades Starboard's memory tracking. In both port implementations and Starboard client application code, you should always call SbMemoryAllocate and SbMemoryDeallocate rather than SbMemoryAllocateUnchecked and SbMemoryFree.
The "checked" functions are SbMemoryAllocateChecked(), SbMemoryReallocateChecked(), and SbMemoryAllocateAlignedChecked().
The "unchecked" functions are SbMemoryAllocateUnchecked(), SbMemoryReallocateUnchecked(), and SbMemoryAllocateAlignedUnchecked().
The "free" functions are SbMemoryFree() and SbMemoryFreeAligned().
Enums
SbMemoryMapFlags
The bitwise OR of these flags should be passed to SbMemoryMap to indicate how the mapped memory can be used.
Values
kSbMemoryMapProtectReserved
No flags set: Reserves virtual address space. SbMemoryProtect() can later make it accessible.
kSbMemoryMapProtectRead
kSbMemoryMapProtectWrite
kSbMemoryMapProtectExec
kSbMemoryMapProtectReadWrite
Functions
SbMemoryAllocate
Allocates and returns a chunk of memory of at least size
bytes. This function
should be called from the client codebase. It is intended to be a drop-in
replacement for malloc
.
Note that this function returns NULL
if it is unable to allocate the memory.
size
: The amount of memory to be allocated. If size
is 0, the function may
return NULL
or it may return a unique pointer value that can be passed to
SbMemoryDeallocate.
Declaration
void* SbMemoryAllocate(size_t size)
SbMemoryAllocateAligned
Allocates and returns a chunk of memory of at least size
bytes, aligned to
alignment
. This function should be called from the client codebase. It is
meant to be a drop-in replacement for memalign
.
The function returns NULL
if it cannot allocate the memory. In addition, the
function's behavior is undefined if alignment
is not a power of two.
alignment
: The way that data is arranged and accessed in memory. The value
must be a power of two. size
: The size of the memory to be allocated. If
size
is 0
, the function may return NULL
or it may return a unique aligned
pointer value that can be passed to SbMemoryDeallocateAligned.
Declaration
void* SbMemoryAllocateAligned(size_t alignment, size_t size)
SbMemoryAllocateAlignedChecked
Same as SbMemoryAllocateAlignedUnchecked, but will abort() in the case of an allocation failure.
DO NOT CALL. Call SbMemoryAllocateAligned(...) instead.
Declaration
void* SbMemoryAllocateAlignedChecked(size_t alignment, size_t size)
SbMemoryAllocateAlignedUnchecked
This is the implementation of SbMemoryAllocateAligned that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryAllocateAligned(...) instead.
Declaration
void* SbMemoryAllocateAlignedUnchecked(size_t alignment, size_t size)
SbMemoryAllocateChecked
Same as SbMemoryAllocateUnchecked, but will abort() in the case of an allocation failure.
DO NOT CALL. Call SbMemoryAllocate(...) instead.
Declaration
void* SbMemoryAllocateChecked(size_t size)
SbMemoryAllocateNoReport
DEPRECATED: Same as SbMemoryAllocate().
Declaration
void* SbMemoryAllocateNoReport(size_t size)
SbMemoryAllocateUnchecked
This is the implementation of SbMemoryAllocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryAllocate(...) instead.
Declaration
void* SbMemoryAllocateUnchecked(size_t size)
SbMemoryCalloc
A wrapper that implements a drop-in replacement for calloc
, which is used in
some packages.
Declaration
static void* SbMemoryCalloc(size_t count, size_t size)
SbMemoryDeallocate
Frees a previously allocated chunk of memory. If memory
is NULL, then the
operation is a no-op. This function should be called from the client codebase.
It is meant to be a drop-in replacement for free
.
memory
: The chunk of memory to be freed.
Declaration
void SbMemoryDeallocate(void *memory)
SbMemoryDeallocateAligned
memory
: The chunk of memory to be freed. If memory
is NULL, then the
function is a no-op.
Declaration
void SbMemoryDeallocateAligned(void *memory)
SbMemoryDeallocateNoReport
DEPRECATED: Same as SbMemoryDeallocate()
Declaration
void SbMemoryDeallocateNoReport(void *memory)
SbMemoryFlush
Flushes any data in the given virtual address range that is cached locally in the current processor core to physical memory, ensuring that data and instruction caches are cleared. This is required to be called on executable memory that has been written to and might be executed in the future.
Declaration
void SbMemoryFlush(void *virtual_address, int64_t size_bytes)
SbMemoryFree
This is the implementation of SbMemoryDeallocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryDeallocate(...) instead.
Declaration
void SbMemoryFree(void *memory)
SbMemoryFreeAligned
This is the implementation of SbMemoryFreeAligned that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead.
Declaration
void SbMemoryFreeAligned(void *memory)
SbMemoryGetStackBounds
Gets the stack bounds for the current thread.
out_high
: The highest addressable byte + 1 for the current thread. out_low
:
The lowest addressable byte for the current thread.
Declaration
void SbMemoryGetStackBounds(void **out_high, void **out_low)
SbMemoryMap
Allocates size_bytes
worth of physical memory pages and maps them into an
available virtual region. This function returns SB_MEMORY_MAP_FAILED
on
failure. NULL
is a valid return value.
size_bytes
: The amount of physical memory pages to be allocated. flags
: The
bitwise OR of the protection flags for the mapped memory as specified in
SbMemoryMapFlags
. Allocating executable memory is not allowed and will fail.
If executable memory is needed, map non-executable memory first and then switch
access to executable using SbMemoryProtect. When kSbMemoryMapProtectReserved is
used, the address space will not be accessible and, if possible, the platform
should not count it against any memory budget. name
: A value that appears in
the debugger on some platforms. The value can be up to 32 bytes.
Declaration
void* SbMemoryMap(int64_t size_bytes, int flags, const char *name)
SbMemoryProtect
Change the protection of size_bytes
of memory regions, starting from
virtual_address
, to flags
, returning true
on success.
Declaration
bool SbMemoryProtect(void *virtual_address, int64_t size_bytes, int flags)
SbMemoryReallocate
Attempts to resize memory
to be at least size
bytes, without touching the
contents of memory.
If the function cannot perform the fast resize, it allocates a new chunk of memory, copies the contents over, and frees the previous chunk, returning a pointer to the new chunk.
If the function cannot perform the slow resize, it returns
NULL
, leaving the given memory chunk unchanged.
This function should be called from the client codebase. It is meant to be a
drop-in replacement for realloc
.
memory
: The chunk of memory to be resized. memory
may be NULL, in which case
it behaves exactly like SbMemoryAllocateUnchecked. size
: The size to which
memory
will be resized. If size
is 0
, the function may return NULL
or it
may return a unique pointer value that can be passed to SbMemoryDeallocate.
Declaration
void* SbMemoryReallocate(void *memory, size_t size)
SbMemoryReallocateChecked
Same as SbMemoryReallocateUnchecked, but will abort() in the case of an allocation failure.
DO NOT CALL. Call SbMemoryReallocate(...) instead.
Declaration
void* SbMemoryReallocateChecked(void *memory, size_t size)
SbMemoryReallocateUnchecked
This is the implementation of SbMemoryReallocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryReallocate(...) instead.
Declaration
void* SbMemoryReallocateUnchecked(void *memory, size_t size)
SbMemoryUnmap
Unmap size_bytes
of physical pages starting from virtual_address
, returning
true
on success. After this function completes, [virtual_address,
virtual_address + size_bytes) will not be read/writable. This function can unmap
multiple contiguous regions that were mapped with separate calls to
SbMemoryMap(). For example, if one call to SbMemoryMap(0x1000)
returns
(void*)0xA000
, and another call to SbMemoryMap(0x1000)
returns
(void*)0xB000
, SbMemoryUnmap(0xA000, 0x2000)
should free both regions.
Declaration
bool SbMemoryUnmap(void *virtual_address, int64_t size_bytes)