source_manager.h

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <lxsameer@lxsameer.com>
 *
 * 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
 
/** @file
Source manager is what that read the source files and own the buffer that contains the data.
Notes:
- We use manual memory management for buffers since the size of buffers are not known in advance and
they might be bigger than block sizes, also the lifecycle of buffers are known and we can avoidarena
allocation completely.
 
- Each buffer is assigned a stable integer ID on first load. That ID is the canonical handle for all
later references and never changes for a given file path.
 
- A hashmap from file path to ID prevents duplicate reads. Passing an already loaded path to
`srn_sm_read_buffer_file` returns the existing ID without reopening the file.
- When `reread` is true, the freshly read buffer is prepended to the existing buffer's chain rather
than replacing it. The slot ID stays the same. The previous buffer remains reachable via
`buffer->next` this way expressions that are previously loaded will continue to have valid
locations.
 
- An empty file produces a valid buffer slot with `data == nullptr` and `len == 0`. Callers must
treat a null `data` field as a valid zero length source rather than an error.
 
- File content is read through `srn_fiber_read`, so the call suspends the current fiber instead of
blocking the OS thread.
 
- A single write lock serialises all insertions and updates. A new file is read outside the lock
and the map is checked again under it before the slot is inserted, so two fibers loading the same
path end up sharing one slot. The path lookup snapshots the map under the lock; `srn_sm_get_buffer`
is unsynchronised, callers must not call it concurrently with a write.
 
- The source manager itself is allocated in the immortal pool and lives for the entire lifetime of
the context.
 */
 
#include <stddef.h>
 
#include "serene/rt/fiber/mutex.h"
#include "serene/rt/fiber/thread.h"
#include "serene/rt/impl/array_list.h"
#include "serene/rt/impl/hashmap.h"
#include "serene/utils.h"
 
#define SRN_SM_NO_ID UINTPTR_MAX
 
#define SM_TRACEPOINT(...) SRN_TRACEPOINT_WITH_GROUP(source_manager __VA_OPT__(, ) __VA_ARGS__)
 
typedef struct srn_context_t srn_context_t;
typedef size_t srn_sm_buffer_id_t;
 
typedef struct srn_sm_maybe_id_t {
  ERROR_HEADER;
  srn_sm_buffer_id_t id;
} srn_sm_maybe_id_t;
 
typedef struct srn_sm_buffer_t {
  const char *filename;
  /// nullptr when the source file was empty (no mapping exists)
  unsigned char *data;
  size_t len;
  struct srn_sm_buffer_t *next;
} srn_sm_buffer_t;
 
typedef struct srn_sm_maybe_buffer_t {
  ERROR_HEADER;
  srn_sm_buffer_t *buffer;
} srn_sm_maybe_buffer_t;
 
typedef struct srn_sm_t {
  srn_context_t *ctx;
  array_list_t buffers;
  size_t buffer_counts;
 
  hmap_t file_to_id_map;
  srn_fiber_mutex_t write_lock;
} srn_sm_t;
 
/**
 * Initialize the source manager, as an immortal data structure. The buffers
 * themselves will NOT be managed by the the memory manager.
 */
[[gnu::nonnull(1)]]
srn_sm_t *srn_sm_init(srn_context_t *ctx);
 
/**
 * Shutdown the source manager freeing all the buffers. After this call all the
 * pointers into the buffers will be invalid.
 */
[[gnu::nonnull(1)]]
void srn_sm_shutdown(srn_sm_t *sm);
 
/**
 * Return the buffer pointer of the given `id`, `nullptr` if the id does not exists.
 */
[[gnu::nonnull(1)]]
srn_sm_buffer_t *srn_sm_get_buffer(srn_sm_t *sm, srn_sm_buffer_id_t id);
 
/**
 * Read and buffer the given `filepath` into the source manager and return the buffer id.
 * If the file already exists, it will just return the buffer id, unless the `reread` is true,
 * which will reread the file and populate the buffer. It will NOT overwrite the old buffer.
 */
[[gnu::nonnull(1, 2)]]
srn_sm_maybe_id_t srn_sm_read_buffer_file(srn_sm_t *sm, const char *filepath, bool reread);
 
/**
 * Read and buffer the given `filepath` into the source manager and return a `srn_sm_maybe_buffer_t`
 * which either fails or has a pointer to the buffer containing the content of the file. A `nullptr`
 * for the buffer means an empty file.
 */
[[gnu::nonnull(1, 2)]]
srn_sm_maybe_buffer_t srn_sm_buffer_file(srn_sm_t *sm, const char *filepath, bool reread);
 
static inline const unsigned char *srn_sm_buffer_data(srn_sm_buffer_t *buf) { return buf->data; }
static inline size_t srn_sm_buffer_len(srn_sm_buffer_t *buf) { return buf->len; }