interface.h

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <[email protected]>
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <https://www.gnu.org/licenses/>.
 */
#pragma once
 
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
 
#include "serene/rt/configuration.h"
#include "serene/utils.h"
 
/** @file
 
    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.
*/
 
#define FALLBACK_PAGE_SIZE 4096U
 
// TODO(lxsameer): Since we want to move fast, at this stage a static
/// 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.
#define MAX_NUMBER_OF_BLOCKS 256U
 
/// We strictly use 16 bytes alignment for blocks.
#define DEFAULT_BLOCK_ALIGNMENT 16U
 
typedef struct srn_mm_t srn_mm_t;
 
/// The block id is effectively just an index in the blocks array in `srn_mm_t`.
/// NOTE: We use the value `SIZE_MAX` to indicate NO BLOCK ID. For example, when
/// embedding a `srn_block_id_t` field in a data structure. If the value
/// of the field is `SIZE_MAX` ((size_t) -1), it indicates that no block id
/// is present.
typedef size_t srn_block_id_t;
#define SRN_BLOCK_NO_ID SIZE_MAX
 
/// 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.
typedef struct srn_memory_provider_t {
  void *(*allocate)(size_t size, size_t alignment);
  void (*release)(void *p);
} srn_memory_provider_t;
 
typedef struct srn_block_t {
  /// when the block does not have space to allocate a request, we will
  /// allocate a new block and point to it here, a simple link list.
  struct srn_block_t *next;
 
  /// This is the TOTAL size of the block, header + payloud. Basically the same
  /// as `srn_mm_t.block_size`. We have a copy here just for a few cases that
  /// one might use a block outside of the memory manager.
  size_t size;
 
  /// Offset from the base
  size_t offset;
  /// Where the data area starts. Blocks carry no lock of their own; the
  /// owning chain's lock lives in `srn_mm_t.chain_locks`, outside the memory
  /// being freed on release.
  alignas(DEFAULT_BLOCK_ALIGNMENT) uint8_t base[];
} srn_block_t;
 
_Static_assert(offsetof(srn_block_t, base) % 16 == 0, "srn_block_t::base must be 16-byte aligned");
 
#if SERENE_DEBUG
typedef struct srn_allocation_stats_t {
  size_t total_allocations;
  size_t total_os_allocations;
  size_t allocated_pages;
  size_t total_blocks;
} srn_allocation_stats_t;
#endif
 
/// 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`.
typedef struct srn_mm_t {
#if SERENE_DEBUG
  srn_allocation_stats_t stats;
#endif
  /// This spinlock is here to protect the srn_mm_t when allocating/deallocating
  /// new blocks. It is NOT used to protect blocks themselves. For block level
  /// operations we use a block level spinlock
  srn_spinlock_t lock;
 
  /// An abstraction over a memory provider like the malloc/free pair.
  srn_memory_provider_t *provider;
  /// This is a 256bit bitmap we treat it as a whole.
  /// 1 means that bit position in the blocks array
  /// is occupied for allocation. otherwise it is free.
  uint64_t block_bitmap[4];
  size_t block_size;
  /// Number of live chains. Incremented on block allocation and decremented
  /// on release, both under `lock`.
  size_t block_count;
  srn_block_t *blocks[MAX_NUMBER_OF_BLOCKS];
 
  /// One lock per chain, keyed by block id. Held for the whole allocation
  /// walk and by release before freeing the chain. Living here rather than
  /// inside the blocks keeps the lock valid while the chain is being freed.
  srn_spinlock_t chain_locks[MAX_NUMBER_OF_BLOCKS];
 
  /// The immortal chain has no block id, so it gets its own chain lock.
  srn_spinlock_t immortal_lock;
 
  /// Immortal block is a chain of blocks which will never die. We will
  /// free the chain at exit. it is there to allocate objects that will
  /// be around for the duration of the program.
  srn_block_t *immortal_block;
} srn_mm_t;
 
/**
 * Retutrns the OS page size
 */
size_t srn_mm_get_os_page_size(void);
/**
 * 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
 */
[[nodiscard]] [[gnu::nonnull(1)]]
srn_block_id_t srn_mm_allocate_block(srn_mm_t *mm);
 
/**
 * Release the given block id and free the memory for later allocations.
 */
[[gnu::nonnull(1)]]
void srn_mm_release_block(srn_mm_t *mm, srn_block_id_t id);
 
/**
 * Return the block object associated by the given `block_id`
 */
[[gnu::nonnull(1)]]
srn_block_t *srn_mm_get_block(srn_mm_t *mm, srn_block_id_t block_id);
 
/**
 * Allocate memory on a block with the given `block_id`.
 */
[[nodiscard]] [[gnu::nonnull(1)]]
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 the importal block which will never gets freed.
 */
[[nodiscard]] [[gnu::nonnull(1)]]
void *srn_mm_immortal_allocate_aligned(srn_mm_t *mm, size_t size, size_t alignment);
 
#define srn_mm_allocate_in_block(mm, id, T) \
  (T *)srn_mm_allocate_in_block_aligned(mm, id, sizeof(T), alignof(T))
 
#define srn_mm_immortal_allocate(mm, T) \
  (T *)srn_mm_immortal_allocate_aligned(mm, sizeof(T), alignof(T))
 
/**
 * 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`.
 */
srn_mm_t *srn_mm_init(const srn_configuration_t *config);
 
/**
 * 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.
 */
[[gnu::nonnull(1)]]
void srn_mm_shutdown(srn_mm_t *mm);
 
/**
 * Unocks the memory manager.
 */
[[gnu::nonnull(1)]]
void srn_unlock_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?
 */
[[gnu::nonnull(1)]]
void srn_lock_memory_manager(srn_mm_t *mm);
 
// ---------------------------------------------------------------------------
// Manual allocation
// ---------------------------------------------------------------------------
 
/**
 * 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.
 */
[[nodiscard]] [[gnu::nonnull(1)]]
void *srn_mm_malloc(srn_mm_t *mm, size_t size);
 
[[nodiscard]] [[gnu::nonnull(1)]]
void *srn_mm_reallocate(srn_mm_t *mm, void *ptr, size_t new_size);
 
/**
 * 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.
 */
[[gnu::nonnull(1)]]
void srn_mm_free(srn_mm_t *mm, void *ptr);
 
#if SERENE_DEBUG
void srn_mm_print_block_summary(srn_mm_t *mm, srn_block_id_t id);
void srn_mm_print_blocks_summary(srn_mm_t *mm);
#endif