interface.h File Reference

Notes: More...

#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include "serene/rt/configuration.h"
#include "serene/rt/trace.h"
#include "serene/utils.h"

Include dependency graph for interface.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	srn_memory_provider_t
	This interface is here to abstract over the allocator. More...
struct	srn_block_t
struct	srn_mm_t
	Main memory manager structure that will own all the allocated blocks and data. More...

Macros
#define	MM_TRACEPOINT(...)
#define	FALLBACK_PAGE_SIZE   4096U
#define	MAX_NUMBER_OF_BLOCKS   256U
	array of blocks is enough for us, we can tweak the size as we see fit.
#define	DEFAULT_BLOCK_ALIGNMENT   16U
	We strictly use 16 bytes alignment for blocks.
#define	SRN_BLOCK_NO_ID   SIZE_MAX
#define	srn_mm_allocate_in_block(mm, id, T)
#define	srn_mm_immortal_allocate(mm, T)
#define	MALLOC(ctx, T)
#define	FREE(ctx, ptr)

Typedefs
typedef struct srn_memory_provider_t	srn_memory_provider_t
	This interface is here to abstract over the allocator.
typedef struct srn_block_t	srn_block_t
typedef struct srn_mm_t	srn_mm_t
	Main memory manager structure that will own all the allocated blocks and data.

Functions
size_t	srn_mm_get_os_page_size (void)
	Retutrns the OS page size.
srn_block_id_t	srn_mm_allocate_block (srn_mm_t *mm)
	Allocate a new block in the memory manager and return its ID.
void	srn_mm_release_block (srn_mm_t *mm, srn_block_id_t id)
	Release the given block id and free the memory for later allocations.
srn_block_t *	srn_mm_get_block (srn_mm_t *mm, srn_block_id_t block_id)
	Return the block object associated by the given block_id.
void *	srn_mm_allocate_in_block_aligned (srn_mm_t *mm, srn_block_id_t block_id, size_t size, size_t alignment)
	Allocate memory on a block with the given block_id.
void *	srn_mm_immortal_allocate_aligned (srn_mm_t *mm, size_t size, size_t alignment)
	Allocate memory on the importal block which will never gets freed.
srn_mm_t *	srn_mm_init (const srn_configuration_t *config)
	Initialize the memory manager, this function will panic on error.
void	srn_mm_shutdown (srn_mm_t *mm)
	Shut down the memory manager and release the resources.
void	srn_unlock_memory_manager (srn_mm_t *mm)
	Unocks the memory manager.
void	srn_lock_memory_manager (srn_mm_t *mm)
	Locks the memory manager.
void *	srn_mm_malloc (srn_mm_t *mm, size_t size)
	Generic allocations that do not participate in the block based pools.
void *	srn_mm_reallocate (srn_mm_t *mm, void *ptr, size_t new_size)
void	srn_mm_free (srn_mm_t *mm, void *ptr)
	Release a pointer previously returned by srn_mm_malloc or srn_mm_reallocate.

Detailed Description

Notes:

• Never give out any pointer to intermediate blocks in a block chain to user.
• Always lock the memory manager when operating only on srn_mm_t.
• Chain locks live in the manager, keyed by block id. An allocation holds the chain's lock for the whole walk; a release holds the manager lock and then the chain lock before freeing, so an allocation racing a release either completes first or resolves the id to nothing.
• To the user a chain of blocks are just one block, so deallocation happens on the chain level not per block
• It's users responsibility to copy the data between different chains.

Definition in file interface.h.

Macro Definition Documentation

DEFAULT_BLOCK_ALIGNMENT

#define DEFAULT_BLOCK_ALIGNMENT   16U

We strictly use 16 bytes alignment for blocks.

Definition at line 58 of file interface.h.

FALLBACK_PAGE_SIZE

#define FALLBACK_PAGE_SIZE   4096U

Definition at line 45 of file interface.h.

FREE

#define FREE	(		ctx,
			ptr )

Value:

srn_mm_free((ctx)->engine->mm, ptr)

Definition at line 247 of file interface.h.

MALLOC

#define MALLOC	(		ctx,
			T )

Value:

(T *)srn_mm_malloc((ctx)->engine->mm, sizeof(T))

Definition at line 235 of file interface.h.

MAX_NUMBER_OF_BLOCKS

#define MAX_NUMBER_OF_BLOCKS   256U

array of blocks is enough for us, we can tweak the size as we see fit.

But we need to change this for the final stage. We should be able to dynamically expand the array of blocks. Notes. Due to my laziness, if you ever change this value, you need to change the popcount functions for the block bitmap as well.

Definition at line 55 of file interface.h.

MM_TRACEPOINT

#define MM_TRACEPOINT

(

...

)

Value:

SRN_TRACEPOINT_WITH_GROUP(mm __VA_OPT__(, ) __VA_ARGS__)

Definition at line 43 of file interface.h.

SRN_BLOCK_NO_ID

#define SRN_BLOCK_NO_ID   SIZE_MAX

Definition at line 68 of file interface.h.

srn_mm_allocate_in_block

#define srn_mm_allocate_in_block	(		mm,
			id,
			T )

Value:

(T *)srn_mm_allocate_in_block_aligned(mm, id, sizeof(T), alignof(T))

Definition at line 185 of file interface.h.

#define srn_mm_allocate_in_block(mm, id, T) \
  (T *)srn_mm_allocate_in_block_aligned(mm, id, sizeof(T), alignof(T))

srn_mm_immortal_allocate

#define srn_mm_immortal_allocate	(		mm,
			T )

Value:

(T *)srn_mm_immortal_allocate_aligned(mm, sizeof(T), alignof(T))

Definition at line 188 of file interface.h.

#define srn_mm_immortal_allocate(mm, T) \
  (T *)srn_mm_immortal_allocate_aligned(mm, sizeof(T), alignof(T))

Typedef Documentation

srn_block_t

typedef struct srn_block_t srn_block_t

srn_memory_provider_t

typedef struct srn_memory_provider_t srn_memory_provider_t

This interface is here to abstract over the allocator.

For instance, malloc/free can be a page provider. This will let us switch to other implementation later on. Eventually we might end up coming up with our own version of malloc/free.

srn_mm_t

typedef struct srn_mm_t srn_mm_t

Main memory manager structure that will own all the allocated blocks and data.

In every instance of the compiler there should be only one instance of this. It should be created via srn_mm_init and destroyed via srn_shutdown_memory_manager.

Function Documentation

srn_lock_memory_manager()

void srn_lock_memory_manager

(

srn_mm_t *

mm

)

Locks the memory manager.

We have to lock the memory manager when allocating blocks. TODO(lxsameer): Do we need to support thread local blocks?

Definition at line 441 of file default.c.

{ srn_spinlock_lock(&mm->lock); }

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mm_allocate_block()

srn_block_id_t srn_mm_allocate_block ( srn_mm_t * mm )

nodiscard

Allocate a new block in the memory manager and return its ID.

The client code can use the ID to allocate memory on the block and when it's done, just use the same ID to release the block

Definition at line 443 of file default.c.

                                                   {
  srn_lock_memory_manager(mm);
  // Ids are reused after release, so exhaustion means every id is live
  // right now, not that this many allocations ever happened.
  int index = find_a_free_block_id(mm);
  PANIC_IF(index == -1, "Out of memory: all block ids are in use");
  srn_block_t *block = alloc_block_internal(mm);
 
  mm->block_count++;
  PANIC_IF(
    !is_block_id_free(mm, (uint16_t)index),
    "Miscalculated the block id. It is not free. This is a bug!"
  );
  allocated_block_id(mm, (uint16_t)index);
  mm->blocks[(srn_block_id_t)index] = block;
 
  srn_unlock_memory_manager(mm);
 
#if SERENE_DEBUG
  mm->stats.total_blocks++;
  mm->stats.total_os_allocations++;
#endif
  return (srn_block_id_t)index;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mm_allocate_in_block_aligned()

void * srn_mm_allocate_in_block_aligned ( srn_mm_t * mm, srn_block_id_t block_id, size_t size, size_t alignment )

nodiscard

Allocate memory on a block with the given block_id.

Definition at line 411 of file default.c.

  {
  MM_LOG("Allocating %zu bytes with %zu bytes alignment in block: %zu", size, alignment, block_id);
  PANIC_IF(block_id >= MAX_NUMBER_OF_BLOCKS, "Block id out of range");
 
  // The id resolves to a block only under the chain lock, so a release
  // cannot free the chain out from under this walk.
  srn_spinlock_t *chain_lock = &mm->chain_locks[block_id];
  srn_spinlock_lock(chain_lock);
 
  srn_block_t *block = get_block(mm, block_id);
  PANIC_IF_NULL(block);
 
  void *ptr = alloc_in_block(mm, block, size, alignment);
  srn_spinlock_unlock(chain_lock);
  MM_TRACEPOINT(mm_alloc, (uint64_t)block_id, (uint64_t)size, ptr);
  return ptr;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mm_free()

void srn_mm_free	(	srn_mm_t *	mm,
		void *	ptr )

Release a pointer previously returned by srn_mm_malloc or srn_mm_reallocate.

ptr may be nullptr, in which case the call is a no-op.

Definition at line 168 of file default.c.

                                          {
  UNUSED(mm);
  MM_TRACEPOINT(mm_free, ptr);
  free(ptr);
}

Here is the caller graph for this function:

srn_mm_get_block()

srn_block_t * srn_mm_get_block	(	srn_mm_t *	mm,
		srn_block_id_t	block_id )

Return the block object associated by the given block_id.

Definition at line 333 of file default.c.

                                                                     {
  return get_block(mm, block_id);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mm_get_os_page_size()

size_t srn_mm_get_os_page_size

(

void

)

Retutrns the OS page size.

Definition at line 318 of file default.c.

                                     {
#if defined(_WIN32)
  SYSTEM_INFO si;
  GetSystemInfo(&si);
  return (size_t)si.dwPageSize;
#elif defined(__unix__) || defined(__APPLE__)
  long sz = sysconf(_SC_PAGESIZE);
  return (sz > 0) ? (size_t)sz : FALLBACK_PAGE_SIZE;
#elif defined(__wasm__)
  return WASM_PAGE_SIZE;
#else
  return FALLBACK_PAGE_SIZE;
#endif
}

Here is the caller graph for this function:

srn_mm_immortal_allocate_aligned()

void * srn_mm_immortal_allocate_aligned ( srn_mm_t * mm, size_t size, size_t alignment )

nodiscard

Allocate memory on the importal block which will never gets freed.

Definition at line 431 of file default.c.

                                                                                    {
  srn_spinlock_lock(&mm->immortal_lock);
  void *ptr = alloc_in_block(mm, mm->immortal_block, size, alignment);
  srn_spinlock_unlock(&mm->immortal_lock);
  MM_TRACEPOINT(mm_immortal_alloc, (uint64_t)size, ptr);
  return ptr;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mm_init()

srn_mm_t * srn_mm_init

(

const srn_configuration_t *

config

)

Initialize the memory manager, this function will panic on error.

config provides the knobs the manager reads at init (mm.block_size_magnitude, the block size is 1 << magnitude); a null config means "use the defaults". The config is read only during the call, so the caller may pass a stack value and reuse it for srn_engine_make.

Definition at line 337 of file default.c.

                                                         {
  if (config != nullptr) {
    srn_config_validate(config);
  }
 
  srn_mm_t *mm = malloc(sizeof(srn_mm_t));
  PANIC_IF_NULL(mm);
 
  mm->provider = &stdlib_provider;
  memset(mm->block_bitmap, 0, sizeof(mm->block_bitmap));
 
  // The block size is the one knob the manager reads at init. It comes as a
  // magnitude, so the size is a power of two and a whole number of pages by
  // construction, with nothing to round.
  const size_t magnitude =
    (config != nullptr) ? config->mm.block_size_magnitude : SRN_CONFIG_DEFAULT_BLOCK_SIZE_MAGNITUDE;
 
  mm->block_count = 0;
  mm->block_size  = (size_t)1 << magnitude;
  memset((void *)mm->blocks, 0, sizeof(mm->blocks));
 
  PANIC_IF(
    mm->block_size <= sizeof(srn_block_t),
    "Wrong block size. Configure mm.block_size_magnitude to a larger number"
  );
  // srn_config_validate only sees a caller provided config, so the default
  // path is checked here too. The page size is only known at run time.
  PANIC_IF(
    mm->block_size % srn_mm_get_os_page_size() != 0, "Block size must be a whole number of OS pages"
  );
 
  srn_spinlock_init(&mm->lock);
  for (size_t i = 0; i < MAX_NUMBER_OF_BLOCKS; i++) {
    srn_spinlock_init(&mm->chain_locks[i]);
  }
  srn_spinlock_init(&mm->immortal_lock);
 
  srn_block_t *immortal =
    (srn_block_t *)mm->provider->allocate(mm->block_size, DEFAULT_BLOCK_ALIGNMENT);
  PANIC_IF_NULL(immortal);
  init_block(mm, immortal);
  mm->immortal_block = immortal;
 
#if SERENE_DEBUG
  mm->stats.allocated_pages      = 0;
  mm->stats.total_allocations    = 0;
  mm->stats.total_os_allocations = 0;
  mm->stats.total_blocks         = 0;
#endif
  return mm;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mm_malloc()

void * srn_mm_malloc ( srn_mm_t * mm, size_t size )

nodiscard

Generic allocations that do not participate in the block based pools.

Equivalent to malloc/realloc/free. Routed through the memory manager so the backend can later be swapped without touching callers. mm is reserved for future per manager routing and is currently unused inside the implementation.

Definition at line 155 of file default.c.

                                               {
  UNUSED(mm);
  void *ptr = malloc(size);
  MM_TRACEPOINT(mm_malloc, (uint64_t)size, ptr);
  return ptr;
}

Here is the caller graph for this function:

srn_mm_reallocate()

void * srn_mm_reallocate ( srn_mm_t * mm, void * ptr, size_t new_size )

nodiscard

Definition at line 162 of file default.c.

                                                                  {
  UNUSED(mm);
  void *out = realloc(ptr, new_size);
  return out;
}

Here is the caller graph for this function:

srn_mm_release_block()

void srn_mm_release_block	(	srn_mm_t *	mm,
		srn_block_id_t	id )

Release the given block id and free the memory for later allocations.

Definition at line 468 of file default.c.

                                                           {
  PANIC_IF_NULL(mm);
  destroy_chain(mm, id);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_mm_shutdown()

void srn_mm_shutdown

(

srn_mm_t *

mm

)

Shut down the memory manager and release the resources.

Will panic on error. Technically it should be the final piece of clean up that we call. Note: Shutdown is not thread safe at has to execute on the main thread.

Definition at line 389 of file default.c.

                                   {
  PANIC_IF_NULL(mm);
  assert(mm->provider != nullptr);
 
  for (size_t i = 0; i < MAX_NUMBER_OF_BLOCKS; i++) {
    if (mm->blocks[i] != nullptr) {
      destroy_chain(mm, i);
    }
  }
 
  srn_block_t *block = mm->immortal_block;
 
  while (block != nullptr) {
    srn_block_t *tmp = block;
    block            = tmp->next;
 
    mm->provider->release(tmp);
  }
 
  mm->provider->release(mm);
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_unlock_memory_manager()

void srn_unlock_memory_manager

(

srn_mm_t *

mm

)

Unocks the memory manager.

Definition at line 439 of file default.c.

{ srn_spinlock_unlock(&mm->lock); }

Here is the call graph for this function:

Here is the caller graph for this function: