engine.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 "serene/rt/configuration.h"
#include "serene/rt/impl/hashmap.h"
#include "serene/utils.h"
 
#define SRN_HASH_TYPE uint32_t
#define SRN_SEED_TYPE uint32_t
 
typedef struct srn_jit_t srn_jit_t;
typedef struct srn_mm_t srn_mm_t;
typedef struct hmap_t hmap_t;
typedef struct srn_namespace_t srn_namespace_t;
typedef struct srn_error_t srn_error_t;
typedef struct srn_context_t srn_context_t;
typedef struct srn_value_t srn_value_t;
typedef struct srn_metadata_t srn_metadata_t;
typedef struct srn_scheduler_t srn_scheduler_t;
typedef struct srn_reactor_t srn_reactor_t;
 
typedef uint64_t srn_object_id_t;
/// Start allocating IDs from 100, earlier IDs are reserved
#define ENGINE_FIRST_OBJECT_ID 100
 
typedef SRN_HASH_TYPE srn_hash_t;
typedef SRN_SEED_TYPE srn_seed_t;
 
/// Engine is a structure to own the long living and main pieces of the
/// compiler. There will be only oe instance of the engine at anytime.
typedef struct srn_engine_t {
  /// An unsigned counter to allocate object ids atomically. Any object in
  /// Serene must have a unique id, this id is not guaranteed to be the same on
  /// each run. We use this id as the routing key on the context level to
  /// connect different pieces of information related to the same object
  /// together. ONLY INTERACT WITH THIS VIA `allocate_object_id`.
  _Atomic srn_object_id_t object_id_counter;
 
  /// The runtime's tunable knobs, the single source for every configurable
  /// value (see configuration.h). Held by value, read-only once the engine is
  /// up.
  srn_configuration_t config;
 
  /// Memory manager
  srn_mm_t *mm;
 
#ifdef SRN_WITH_SERENE
  srn_jit_t *jit;
#endif
 
  /// The fiber scheduler, that is the entry point of the fiber subsystem.
  /// It's here so any fiber can reach it through its context as
  /// fiber->ctx->engine->scheduler, which is how srn_fiber_ready works from a
  /// thread that is not a worker.
  srn_scheduler_t *scheduler;
 
  /// The I/O reactor, that is in charge of handling everything I/O.
  srn_reactor_t *reactor;
 
  /// We use the seed for hashing and the value will be generated at random
  /// for each new context. There's concern about hashmap collioson DoS attacks
  /// but as far as I can see other compilers are doing a similar thing with
  /// a non-cryptographic hashing function. we use xxHash but others are
  /// using the non-cryptographic version of SipHash with a random seed as
  /// well.
  srn_seed_t seed;
 
#ifdef SRN_WITH_SERENE
  /// A context owned by the engine itself, alive from engine creation to
  /// engine shutdown. The engine wide registries below are pinned to it, so
  /// every trie node they retain lives in its block chain rather than in
  /// whatever transient context performed the insert. It is shared across
  /// threads; allocate through it only while holding the lock that guards
  /// the map being updated.
  srn_context_t *root_context;
 
  /// A hashmap that maps namespace names to their value. When operating on
  /// this map, e.g. inserting a namespace which will lead to a new `hmap_t`
  /// make sure to lock the spinlock.
  hmap_t namespaces;
  srn_spinlock_t ns_lock;
 
  /// Engine wide intern table for keywords. Keys are the keyword name bytes;
  /// values are the interned srn_value_t* (with tag VKeyword). Lock before
  /// any lookup-then-insert.
  hmap_t keywords;
  srn_spinlock_t keywords_lock;
#endif
 
} srn_engine_t;
 
// -----------------------------------------------------------------------------
// Engine's LifeCycle
// -----------------------------------------------------------------------------
/// Create the engine over `mm`, copying `config` (the runtime's knobs) into it.
/// Pass `nullptr` for `config` to use the defaults. `config` is read only
/// during the call, so the caller may pass a stack value.
[[gnu::nonnull(1)]]
srn_engine_t *srn_engine_make(srn_mm_t *mm, const srn_configuration_t *config);
[[gnu::nonnull(1)]]
void srn_engine_shutdown(srn_engine_t *engine);
 
// -----------------------------------------------------------------------------
// IDs
// -----------------------------------------------------------------------------
[[gnu::nonnull(1)]]
srn_object_id_t srn_allocate_object_id(srn_engine_t *engine);
 
// -----------------------------------------------------------------------------
// Hashing
// -----------------------------------------------------------------------------
[[gnu::nonnull(1)]]
srn_hash_t srn_hash(const srn_engine_t *engine, const void *data, size_t len);
 
// -----------------------------------------------------------------------------
// Keyword interning
// -----------------------------------------------------------------------------
#ifdef SRN_WITH_SERENE
/// Return the canonical interned keyword value for `name`. If a keyword with
/// the same name has been interned in this engine before, the same
/// srn_value_t* is returned. Otherwise the value is built, registered in the
/// engine wide keyword table, and returned. This function is thread safe, via
/// the `keywords_lock`.
[[gnu::nonnull(1, 2)]]
srn_value_t *
srn_engine_intern_keyword(srn_context_t *ctx, srn_metadata_t *metadata, const char *name);
#endif