Defines functions for memory allocation, alignment, copying, and comparing.
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.
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().
The bitwise OR of these flags should be passed to SbMemoryMap to indicate how the mapped memory can be used.
kSbMemoryMapProtectReserved
No flags set: Reserves virtual address space. SbMemoryProtect() can later make it accessible.
kSbMemoryMapProtectRead
kSbMemoryMapProtectWrite
kSbMemoryMapProtectExec
kSbMemoryMapProtectReadWrite
Rounds size up to kSbMemoryPageSize.
static size_t SbMemoryAlignToPageSize(size_t size)
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.
void* SbMemoryAllocate(size_t size)
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.
void* SbMemoryAllocateAligned(size_t alignment, size_t size)
Same as SbMemoryAllocateAlignedUnchecked, but will abort() in the case of an allocation failure.
DO NOT CALL. Call SbMemoryAllocateAligned(...) instead.
void* SbMemoryAllocateAlignedChecked(size_t alignment, size_t size)
This is the implementation of SbMemoryAllocateAligned that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryAllocateAligned(...) instead.
void* SbMemoryAllocateAlignedUnchecked(size_t alignment, size_t size)
Same as SbMemoryAllocateUnchecked, but will abort() in the case of an allocation failure.
DO NOT CALL. Call SbMemoryAllocate(...) instead.
void* SbMemoryAllocateChecked(size_t size)
Same as SbMemoryAllocate() but will not report memory to the tracker. Avoid using this unless absolutely necessary.
void* SbMemoryAllocateNoReport(size_t size)
This is the implementation of SbMemoryAllocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryAllocate(...) instead.
void* SbMemoryAllocateUnchecked(size_t size)
A wrapper that implements a drop-in replacement for calloc, which is used in some packages.
static void* SbMemoryCalloc(size_t count, size_t size)
Compares the contents of the first count bytes of buffer1 and buffer2. This function returns:
-1 if buffer1 is “less-than” buffer2
0 if buffer1 and buffer2 are equal
1 if buffer1 is “greater-than” buffer2.
This function is meant to be a drop-in replacement for memcmp.
buffer1: The first buffer to be compared. buffer2: The second buffer to be compared. count: The number of bytes to be compared.
int SbMemoryCompare(const void *buffer1, const void *buffer2, size_t count)
Copies count sequential bytes from source to destination, without support for the source and destination regions overlapping. This function is meant to be a drop-in replacement for memcpy.
The function's behavior is undefined if destination or source are NULL, and the function is a no-op if count is 0. The return value is destination.
destination: The destination of the copied memory. source: The source of the copied memory. count: The number of sequential bytes to be copied.
void* SbMemoryCopy(void *destination, const void *source, size_t count)
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.
void SbMemoryDeallocate(void *memory)
memory: The chunk of memory to be freed. If memory is NULL, then the function is a no-op.
void SbMemoryDeallocateAligned(void *memory)
Same as SbMemoryDeallocate() but will not report memory deallocation to the tracker. This function must be matched with SbMemoryAllocateNoReport().
void SbMemoryDeallocateNoReport(void *memory)
Finds the lower 8-bits of value in the first count bytes of buffer and returns either a pointer to the first found occurrence or NULL if the value is not found. This function is meant to be a drop-in replacement for memchr.
const void* SbMemoryFindByte(const void *buffer, int value, size_t count)
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.
void SbMemoryFlush(void *virtual_address, int64_t size_bytes)
This is the implementation of SbMemoryDeallocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryDeallocate(...) instead.
void SbMemoryFree(void *memory)
This is the implementation of SbMemoryFreeAligned that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead.
void SbMemoryFreeAligned(void *memory)
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.
void SbMemoryGetStackBounds(void **out_high, void **out_low)
Checks whether memory is aligned to alignment bytes.
static bool SbMemoryIsAligned(const void *memory, size_t alignment)
Returns true if the first count bytes of buffer are set to zero.
static bool SbMemoryIsZero(const void *buffer, size_t count)
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.
void* SbMemoryMap(int64_t size_bytes, int flags, const char *name)
Copies count sequential bytes from source to destination, with support for the source and destination regions overlapping. This function is meant to be a drop-in replacement for memmove.
The function's behavior is undefined if destination or source are NULL, and the function is a no-op if count is 0. The return value is destination.
destination: The destination of the copied memory. source: The source of the copied memory. count: The number of sequential bytes to be copied.
void* SbMemoryMove(void *destination, const void *source, size_t count)
Change the protection of size_bytes of memory regions, starting from virtual_address, to flags, returning true on success.
bool SbMemoryProtect(void *virtual_address, int64_t size_bytes, int flags)
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.
void* SbMemoryReallocate(void *memory, size_t size)
Same as SbMemoryReallocateUnchecked, but will abort() in the case of an allocation failure.
DO NOT CALL. Call SbMemoryReallocate(...) instead.
void* SbMemoryReallocateChecked(void *memory, size_t size)
This is the implementation of SbMemoryReallocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryReallocate(...) instead.
void* SbMemoryReallocateUnchecked(void *memory, size_t size)
Fills count sequential bytes starting at destination, with the unsigned char coercion of byte_value. This function is meant to be a drop-in replacement for memset.
The function's behavior is undefined if destination is NULL, and the function is a no-op if count is 0. The return value is destination.
destination: The destination of the copied memory. count: The number of sequential bytes to be set.
void* SbMemorySet(void *destination, int byte_value, size_t count)
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.
bool SbMemoryUnmap(void *virtual_address, int64_t size_bytes)