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/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 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;
 
  /// Memory manager
  srn_mm_t *mm;
 
#ifdef SRN_WITH_SERENE
  srn_jit_t *jit;
#endif
 
  /// The fiber scheduler, set by srn_sched_init. 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;
 
  /// 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 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
// -----------------------------------------------------------------------------
[[gnu::nonnull(1)]] srn_engine_t *srn_engine_make(srn_mm_t *mm);
[[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