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/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`.
/// - Always lock the  block when operating on it
/// - Never lock the memory manager to operate on a block in it.
/// - 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
 
/// This is the value that we want for our blocks but we want it to be
/// a multiple of the page size on the platform as well. So there is no
/// guarantee that we get exactly this number.
/// 128Kib
#define DESIRED_BLOCK_SIZE 131072
 
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 {
  /// This lock will protect only the block level operations and NOT
  /// the memory manager. We lock only the root block when operating on
  /// block chains. Intermediate blocks considered as part of the root
  /// block.
  srn_spinlock_t lock;
 
  /// 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
  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;
  size_t block_count;
  srn_block_t *blocks[MAX_NUMBER_OF_BLOCKS];
 
  /// 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);
/// Calculates and return the block size based on our desired size
/// and the OS page size. Basically the ruturn value will be a number
/// multiple of the OS page size and close or equal to our desired size
size_t srn_mm_get_block_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
srn_mm_t *srn_mm_init(void);
 
/// 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_allocate(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_allocate 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