Starboard Module Reference: memory.h

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 Cobalt developers

Nobody should call the "Checked", "Unchecked" or "Free" functions directly because that evades Starboard's memory tracking. In both port implementations and Cobalt 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

  • kSbMemoryMapProtectRead - Mapped memory can be read.
  • kSbMemoryMapProtectWrite - Mapped memory can be written to.
  • kSbMemoryMapProtectExec - Mapped memory can be executed.
  • kSbMemoryMapProtectRead

Macros

SB_MEMORY_MAP_FAILED

Functions

SbAbortIfAllocationFailed

Declaration

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

Parameters
size_t
requested_bytes
void*
address

SbMemoryAlignToPageSize

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

Parameters
size_t
size

SbMemoryAllocate

Description

Allocates and returns a chunk of memory of at least size bytes. This function should be called from the Cobalt 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

Parameters
size_t
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.

SbMemoryAllocateAligned

Description

Allocates and returns a chunk of memory of at least size bytes, aligned to alignment. This function should be called from the Cobalt 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

Parameters
size_t
alignment
The way that data is arranged and accessed in memory. The value must be a power of two.
size_t
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.

SbMemoryAllocateAlignedChecked

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

Parameters
size_t
alignment
size_t
size

SbMemoryAllocateAlignedUnchecked

Description

This is the implementation of SbMemoryAllocateAligned that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryAllocateAligned(...) instead.

Declaration and definitions

    SB_EXPORT void* SbMemoryAllocateAlignedUnchecked(size_t alignment,
                                                     size_t size));

#include "starboard/memory.h"

void* SbMemoryAllocateAlignedUnchecked(size_t /*alignment*/, size_t /*size*/) {
  return NULL;
}

Parameters

Parameters
size_t
alignment
size_t
size

SbMemoryAllocateChecked

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

Parameters
size_t
size

SbMemoryAllocateUnchecked

Description

This is the implementation of SbMemoryAllocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryAllocate(...) instead.

Declaration and definitions

    SB_EXPORT void* SbMemoryAllocateUnchecked(size_t size));

#include "starboard/memory.h"

void* SbMemoryAllocateUnchecked(size_t /*size*/) {
  return NULL;
}

Parameters

Parameters
size_t
size

SbMemoryCalloc

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

Parameters
size_t
count
size_t
size

SbMemoryCompare

Description

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.

Declaration and definitions

SB_EXPORT int SbMemoryCompare(const void* buffer1,
                              const void* buffer2,
                              size_t count);

#include "starboard/memory.h"

int SbMemoryCompare(const void* /*buffer1*/, const void* /*buffer2*/,
                    size_t /*count*/) {
  return 0;
}

Parameters

Parameters
const void*
buffer1
The first buffer to be compared.
const void*
buffer2
The second buffer to be compared.
size_t
count
The number of bytes to be compared.

SbMemoryCopy

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

SB_EXPORT void* SbMemoryCopy(void* destination,
                             const void* source,
                             size_t count);

#include "starboard/memory.h"

void* SbMemoryCopy(void* /*destination*/, const void* /*source*/,
                   size_t /*count*/) {
  return NULL;
}

Parameters

Parameters
void*
destination
The destination of the copied memory.
const void*
source
The source of the copied memory.
size_t
count
The number of sequential bytes to be copied.

SbMemoryDeallocate

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 Cobalt codebase. It is meant to be a drop-in replacement for free.

Declaration

SB_EXPORT void SbMemoryDeallocate(void* memory);

Parameters

Parameters
void*
memory
The chunk of memory to be freed.

SbMemoryDeallocateAligned

Declaration

SB_EXPORT void SbMemoryDeallocateAligned(void* memory);

Parameters

Parameters
void*
memory
The chunk of memory to be freed. If memory is NULL, then the function is a no-op.

SbMemoryFindByte

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

SB_EXPORT const void* SbMemoryFindByte(const void* buffer,
                                       int value,
                                       size_t count);

#include "starboard/memory.h"

const void* SbMemoryFindByte(const void* /*buffer*/, int /*value*/,
                             size_t /*count*/) {
  return 0;
}

Parameters

Parameters
const void*
buffer
int
value
size_t
count

SbMemoryFlush

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

SB_EXPORT void SbMemoryFlush(void* virtual_address, int64_t size_bytes);

#include "starboard/memory.h"

void SbMemoryFlush(void* /*virtual_address*/, int64_t /*size_bytes*/) {}

Parameters

Parameters
void*
virtual_address
int64_t
size_bytes

SbMemoryFree

Description

This is the implementation of SbMemoryDeallocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryDeallocate(...) instead.

Declaration and definitions

    SB_EXPORT void SbMemoryFree(void* memory));

#include "starboard/memory.h"

void SbMemoryFree(void* /*memory*/) {
}

Parameters

Parameters
void*
memory

SbMemoryFreeAligned

Description

This is the implementation of SbMemoryFreeAligned that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryDeallocateAligned(...) instead.

Declaration and definitions

    SB_EXPORT void SbMemoryFreeAligned(void* memory));

#include "starboard/memory.h"

void SbMemoryFreeAligned(void* /*memory*/) {
}

Parameters

Parameters
void*
memory

SbMemoryGetStackBounds

Description

Gets the stack bounds for the current thread.

Declaration and definitions

SB_EXPORT void SbMemoryGetStackBounds(void** out_high, void** out_low);

#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

Parameters
void**
out_high
The highest addressable byte + 1 for the current thread.
void**
out_low
The lowest addressable byte for the current thread.

SbMemoryIsAligned

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

Parameters
const void*
memory
size_t
alignment

SbMemoryMap

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

SB_EXPORT void* SbMemoryMap(int64_t size_bytes, int flags, const char* name);

#include "starboard/memory.h"

void* SbMemoryMap(int64_t /*size_bytes*/, int /*flags*/, const char* /*name*/) {
  return NULL;
}

Parameters

Parameters
int64_t
size_bytes
The amount of physical memory pages to be allocated.
int
flags
The bitwise OR of the protection flags for the mapped memory as specified in SbMemoryMapFlags.
const char*
name
A value that appears in the debugger on some platforms. The value can be up to 32 bytes.

SbMemoryMove

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

SB_EXPORT void* SbMemoryMove(void* destination,
                             const void* source,
                             size_t count);

#include "starboard/memory.h"

void* SbMemoryMove(void* /*destination*/, const void* /*source*/,
                   size_t /*count*/) {
  return NULL;
}

Parameters

Parameters
void*
destination
The destination of the copied memory.
const void*
source
The source of the copied memory.
size_t
count
The number of sequential bytes to be copied.

SbMemoryReallocate

Description

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 Cobalt codebase. It is meant to be a drop-in replacement for realloc.

Declaration

SB_EXPORT void* SbMemoryReallocate(void* memory, size_t size);

Parameters

Parameters
void*
memory
The chunk of memory to be resized. memory may be NULL, in which case it behaves exactly like SbMemoryAllocateUnchecked.
size_t
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.

SbMemoryReallocateChecked

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

Parameters
void*
memory
size_t
size

SbMemoryReallocateUnchecked

Description

This is the implementation of SbMemoryReallocate that must be provided by Starboard ports.
DO NOT CALL. Call SbMemoryReallocate(...) instead.

Declaration and definitions

    SB_EXPORT void* SbMemoryReallocateUnchecked(void* memory, size_t size));

#include "starboard/memory.h"

void* SbMemoryReallocateUnchecked(void* /*memory*/, size_t /*size*/) {
  return NULL;
}

Parameters

Parameters
void*
memory
size_t
size

SbMemorySet

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

SB_EXPORT void* SbMemorySet(void* destination, int byte_value, size_t count);

#include "starboard/memory.h"

void* SbMemorySet(void* /*destination*/, int /*byte_value*/, size_t /*count*/) {
  return NULL;
}

Parameters

Parameters
void*
destination
The destination of the copied memory.
int
byte_value
size_t
count
The number of sequential bytes to be set.

SbMemoryUnmap

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

SB_EXPORT bool SbMemoryUnmap(void* virtual_address, int64_t size_bytes);

#include "starboard/memory.h"

bool SbMemoryUnmap(void* /*virtual_address*/, int64_t /*size_bytes*/) {
  return false;
}

Parameters

Parameters
void*
virtual_address
int64_t
size_bytes