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 bitwise OR of these flags should be passed to SbMemoryMap to indicate how the mapped memory can be used.
Values
kSbMemoryMapProtectRead - Mapped memory can be read.kSbMemoryMapProtectWrite - Mapped memory can be written to.kSbMemoryMapProtectExec - Mapped memory can be executed.kSbMemoryMapProtectReadDeclaration
static SB_C_FORCE_INLINE void SbAbortIfAllocationFailed(size_t requested_bytes,
void* address) {
if (SB_UNLIKELY(requested_bytes > 0 && address == NULL)) {
// Will abort the program if no debugger is attached.
SbSystemBreakIntoDebugger();
}
}
Parameters
Description
Rounds size up to SB_MEMORY_PAGE_SIZE.
Declaration
static SB_C_FORCE_INLINE size_t SbMemoryAlignToPageSize(size_t size) {
return (size + SB_MEMORY_PAGE_SIZE - 1) & ~(SB_MEMORY_PAGE_SIZE - 1);
}
Parameters
Description
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.
Declaration
SB_EXPORT void* SbMemoryAllocate(size_t size);
Parameters
Description
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.
Declaration
SB_EXPORT void* SbMemoryAllocateAligned(size_t alignment, size_t size);
Parameters
Description
Same as SbMemoryAllocateAlignedUnchecked, but will abort() in the case of an allocation failure.
DO NOT CALL. Call SbMemoryAllocateAligned(...) instead.
Declaration
SB_EXPORT void* SbMemoryAllocateAlignedChecked(size_t alignment,
size_t size));
Parameters
Description
This is the implementation of SbMemoryAllocateAligned that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryAllocateAligned(...) instead.
Declaration and definitions
#include "starboard/memory.h"
void* SbMemoryAllocateAlignedUnchecked(size_t /*alignment*/, size_t /*size*/) {
return NULL;
}
Parameters
Description
Same as SbMemoryAllocateUnchecked, but will abort() in the case of an allocation failure.
DO NOT CALL. Call SbMemoryAllocate(...) instead.
Declaration
SB_EXPORT void* SbMemoryAllocateChecked(size_t size));
Parameters
Description
Same as SbMemoryAllocate() but will not report memory to the tracker. Avoid using this unless absolutely necessary.
Declaration
SB_EXPORT void* SbMemoryAllocateNoReport(size_t size);
Parameters
Description
This is the implementation of SbMemoryAllocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryAllocate(...) instead.
Declaration and definitions
#include "starboard/memory.h"
void* SbMemoryAllocateUnchecked(size_t /*size*/) {
return NULL;
}
Parameters
Description
A wrapper that implements a drop-in replacement for calloc, which is used in some packages.
Declaration
static SB_C_INLINE void* SbMemoryCalloc(size_t count, size_t size) {
size_t total = count * size;
void* result = SbMemoryAllocate(total);
if (result) {
SbMemorySet(result, 0, total);
}
return result;
}
Parameters
Description
Compares the contents of the first count bytes of buffer1 and buffer2. This function returns:
Declaration and definitions
#include "starboard/memory.h"
int SbMemoryCompare(const void* /*buffer1*/, const void* /*buffer2*/,
size_t /*count*/) {
return 0;
}
Parameters
Description
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.
Declaration and definitions
#include "starboard/memory.h"
void* SbMemoryCopy(void* /*destination*/, const void* /*source*/,
size_t /*count*/) {
return NULL;
}
Parameters
Description
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.
Declaration
SB_EXPORT void SbMemoryDeallocate(void* memory);
Parameters
Declaration
SB_EXPORT void SbMemoryDeallocateAligned(void* memory);
Parameters
Description
Same as SbMemoryDeallocate() but will not report memory deallocation to the tracker. This function must be matched with SbMemoryAllocateNoReport().
Declaration
SB_EXPORT void SbMemoryDeallocateNoReport(void* memory);
Parameters
Description
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.
Declaration and definitions
#include "starboard/memory.h"
const void* SbMemoryFindByte(const void* /*buffer*/, int /*value*/,
size_t /*count*/) {
return 0;
}
Parameters
Description
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 and definitions
#include "starboard/memory.h"
void SbMemoryFlush(void* /*virtual_address*/, int64_t /*size_bytes*/) {}
Parameters
Description
This is the implementation of SbMemoryDeallocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryDeallocate(...) instead.
Declaration and definitions
#include "starboard/memory.h"
void SbMemoryFree(void* /*memory*/) {
}
Parameters
Description
This is the implementation of SbMemoryFreeAligned that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead.
Declaration and definitions
#include "starboard/memory.h"
void SbMemoryFreeAligned(void* /*memory*/) {
}
Parameters
Description
Gets the stack bounds for the current thread.
Declaration and definitions
#include "starboard/memory.h"
void SbMemoryGetStackBounds(void** /*out_high*/, void** /*out_low*/) {
}
#include "starboard/memory.h"
#include <pthread.h>
#include <pthread_np.h>
void SbMemoryGetStackBounds(void** out_high, void** out_low) {
pthread_attr_t attr;
pthread_attr_init(&attr);
pthread_attr_get_np(pthread_self(), &attr);
void* stack_address;
size_t stack_size;
pthread_attr_getstack(&attr, &stack_address, &stack_size);
*out_high = static_cast<uint8_t*>(stack_address) + stack_size;
*out_low = stack_address;
pthread_attr_destroy(&attr);
}
#include "starboard/memory.h"
#include <pthread.h>
#include "starboard/log.h"
void SbMemoryGetStackBounds(void** out_high, void** out_low) {
void* stackBase = 0;
size_t stackSize = 0;
pthread_t thread = pthread_self();
pthread_attr_t sattr;
pthread_attr_init(&sattr);
pthread_getattr_np(thread, &sattr);
int rc = pthread_attr_getstack(&sattr, &stackBase, &stackSize);
SB_DCHECK(rc == 0);
SB_DCHECK(stackBase);
pthread_attr_destroy(&sattr);
*out_high = static_cast<char*>(stackBase) + stackSize;
*out_low = stackBase;
}
Parameters
Description
Checks whether memory is aligned to alignment bytes.
Declaration
static SB_C_FORCE_INLINE bool SbMemoryIsAligned(const void* memory,
size_t alignment) {
return ((uintptr_t)memory) % alignment == 0;
}
Parameters
Description
Returns true if the first count bytes of buffer are set to zero.
Declaration
static SB_C_INLINE bool SbMemoryIsZero(const void* buffer, size_t count) {
if (count == 0) {
return true;
}
const char* char_buffer = (const char*)(buffer);
return char_buffer[0] == 0 &&
SbMemoryCompare(char_buffer, char_buffer + 1, count - 1) == 0;
}
Parameters
Description
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.
Declaration and definitions
#include "starboard/memory.h"
void* SbMemoryMap(int64_t /*size_bytes*/, int /*flags*/, const char* /*name*/) {
return NULL;
}
Parameters
Description
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.
Declaration and definitions
#include "starboard/memory.h"
void* SbMemoryMove(void* /*destination*/, const void* /*source*/,
size_t /*count*/) {
return NULL;
}
Parameters
Description
Attempts to resize memory to be at least size bytes, without touching the contents of memory.
Declaration
SB_EXPORT void* SbMemoryReallocate(void* memory, size_t size);
Parameters
Description
Same as SbMemoryReallocateUnchecked, but will abort() in the case of an allocation failure.
DO NOT CALL. Call SbMemoryReallocate(...) instead.
Declaration
SB_EXPORT void* SbMemoryReallocateChecked(void* memory, size_t size));
Parameters
Description
This is the implementation of SbMemoryReallocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryReallocate(...) instead.
Declaration and definitions
#include "starboard/memory.h"
void* SbMemoryReallocateUnchecked(void* /*memory*/, size_t /*size*/) {
return NULL;
}
Parameters
Description
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.
Declaration and definitions
#include "starboard/memory.h"
void* SbMemorySet(void* /*destination*/, int /*byte_value*/, size_t /*count*/) {
return NULL;
}
Parameters
Description
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 and definitions
#include "starboard/memory.h"
bool SbMemoryUnmap(void* /*virtual_address*/, int64_t /*size_bytes*/) {
return false;
}
Parameters