core.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
 
#include <stddef.h>
#include <stdint.h>
 
#include "llvm-c/Core.h"
#include "llvm-c/Types.h"
#include "serene/rt/impl/seq.h"
 
typedef struct srn_context_t srn_context_t;
typedef struct srn_expr_t srn_expr_t;
typedef struct srn_value_t srn_value_t;
typedef struct srn_closure_t srn_closure_t;
typedef struct srn_error_t srn_error_t;
typedef struct srn_namespace_t srn_namespace_t;
typedef struct srn_string_t srn_string_t;
typedef struct srn_symbol_t srn_symbol_t;
typedef struct srn_list_t srn_list_t;
typedef struct srn_keyword_t srn_keyword_t;
typedef struct srn_seq_t srn_seq_t;
typedef struct srn_map_t srn_map_t;
 
typedef struct array_list_t array_list_t;
typedef struct hmap_t hmap_t;
typedef struct srn_fiber_mutex_t srn_fiber_mutex_t;
 
// -----------------------------------------------------------------------------
// Internal ABI
// In C we can't mark fastcc portably; we treat codeptrs as plain fn ptrs.
// LLVM IR will set calling convention = fastcc on definitions & calls.
// `argv` is an array of `argc` value pointers.
// -----------------------------------------------------------------------------
typedef srn_value_t *(*srn_fnptr_t)(srn_context_t *ctx, srn_value_t **argv, uint32_t argc);
 
typedef struct srn_src_location_t {
  /// ID of the source buffer that is registered with the source manager. If we ever need to
  /// increase this limit we have to adjust the guard at the `source_manager.c` where we check
  /// the buffer id to be less that `UINT16_MAX`
  uint16_t buffer_id;
  /// Byte offset of the form's first byte in the buffer.
  uint32_t offset;
  /// Length of the form in bytes. Same width as `offset`, so any span the
  /// reader can measure fits.
  uint32_t len;
} srn_src_location_t;
 
typedef enum srn_ir_type_t : size_t {
  IR_TYPE_IR_READER = 0,
  IR_TYPE_KLEENE,
  /// IR_TYPE_Error should be last
  IR_TYPE_Error,
} srn_ir_type_t;
 
typedef struct srn_metadata_t {
  /// `nullptr` is a valid value and represents an unknown location.
  srn_src_location_t *loc;
  /// An optional pointer to the original and raw expression. We use this
  /// to track what value/expression is a descendant of which expression.
  void *raw_expr;
  /// The type or better to say the category of the `raw_expr` above
  srn_ir_type_t ir_type;
} srn_metadata_t;
 
/// We use this for testing. Defined once in core.c.
extern srn_metadata_t absurd_metadata;
 
// -----------------------------------------------------------------------------
// Values
// This is type will be represented in LLVM like:
// %srn_value_t = type { i64, ptr, i64 } ; { tag, loc, payload }
// -----------------------------------------------------------------------------
typedef enum srn_value_tag_e : size_t {
  VNil = 0,
  VTrue,
  VFalse,
  VI64,
  VF64,
  VList,
  VSeq,
  VQuote,
  VClosure,
  VNamespace,
  VString,
  VSymbol,
  VKeyword,
  VMap,
  /// VError should be last
  VError,
} srn_value_tag_t;
 
typedef struct srn_value_t {
  srn_value_tag_t type;
  srn_metadata_t *metadata;
  /// IMPORTANT NOTE: The size of this union should never be larger than a word
  union {
    /// We represent all the immidiate numbers with this field and cast as we
    /// to an appropriate type. It might change in the future.
    int64_t i64;
    double f64;
    srn_closure_t *closure;
    srn_namespace_t *ns;
    srn_string_t *string;
    srn_symbol_t *symbol;
    srn_error_t *error;
    srn_list_t *list;
    srn_keyword_t *keyword;
    srn_seq_t *seq;
    srn_map_t *map;
  } as;
} srn_value_t;
 
#define SIZE_OF_VALUE_PALYLOAD 8
_Static_assert(
  sizeof(((srn_value_t *)0)->as) == SIZE_OF_VALUE_PALYLOAD, "srn_value_t's union has the wrong size"
);
 
// Shared tag-only sentinels, defined once in core.c. Declared extern (rather
// than defined here) so every TU shares one instance with a stable address --
// these are compared by address (e.g. `x == &false_v`), which per-TU copies
// would break.
extern srn_value_t nil_v;
extern srn_value_t true_v;
extern srn_value_t false_v;
 
#define TYPE(value_ref)        ((value_ref)->type)
#define METADATA(value_ref)    ((value_ref)->metadata)
#define IS_A(value_ref, field) (TYPE(value_ref) == (field))
#define IS_TRUE(value_ref)     (TYPE(value_ref) == VTrue)
#define IS_FALSE(value_ref)    (TYPE(value_ref) == VFalse)
#define IS_NIL(value_ref)      (TYPE(value_ref) == VNil)
 
#define AS_I64(value_ref)     ((value_ref)->as.i64)
#define AS_F64(value_ref)     ((value_ref)->as.f64)
#define AS_CLOSURE(value_ref) ((value_ref)->as.closure)
#define AS_NS(value_ref)      ((value_ref)->as.ns)
#define AS_STRING(value_ref)  ((value_ref)->as.string)
#define AS_SYMBOL(value_ref)  ((value_ref)->as.symbol)
#define AS_ERROR(value_ref)   ((value_ref)->as.error)
#define AS_LIST(value_ref)    ((value_ref)->as.list)
#define AS_KEYWORD(value_ref) ((value_ref)->as.keyword)
#define AS_SEQ(value_ref)     ((value_ref)->as.seq)
#define AS_MAP(value_ref)     ((value_ref)->as.map)
 
/// Creates a new serene value. We always heap allocate the values. So, ANY
/// value creation should go through this function
[[nodiscard]] [[gnu::nonnull(1)]] [[gnu::returns_nonnull]]
srn_value_t *
srn_value_make(srn_context_t *ctx, srn_value_tag_t tag, srn_metadata_t *metadata, void *payload);
 
/// LLVM type for srn_value_t in LLVM IR. { i64, ptr, i64 }
static inline LLVMTypeRef srn_llvm_value_t(LLVMContextRef llctx) {
  LLVMTypeRef i64t = LLVMInt64TypeInContext(llctx);
 
  // opaque ptr
  LLVMTypeRef i8t  = LLVMInt8TypeInContext(llctx);
  LLVMTypeRef ptrt = LLVMPointerType(i8t, 0);
 
  LLVMTypeRef fields[3];
  fields[0] = i64t; // type tag (srn_value_tag_t as i64)
  fields[1] = ptrt; // loc pointer
  fields[2] = i64t; // payload (the union)
 
  LLVMTypeRef st = LLVMStructCreateNamed(llctx, "srn_value_t");
  LLVMStructSetBody(st, fields, 3, 0);
  return st;
}
 
// -----------------------------------------------------------------------------
// Source/Value Graph
// This graph forms the fundamental data layer to do graph reduction.
// -----------------------------------------------------------------------------
typedef size_t srn_node_type_t;
 
typedef struct srn_term_t {
  /// This type field is a bare number value that we split into a few ranges.
  ///
  /// Each range is dedicated to a certain level or better to say phase of the evaluation.
  /// For example:
  ///
  /// - SIZE_MAX: Means the node is containing an `srn_error_t`, so the `data` pointer is pointing
  /// to a `srn_error_t`.
  /// - 0..1000: Is reserved to the first layer of IR (see `serene/ir/reader.h`).
  ///
  /// And so on. Each layer/phase of the compiler that needs to walk/transform the graph can add
  /// its own range.
  srn_node_type_t type;
  srn_metadata_t *metadata;
 
  /// An opaque pointer that depending on the `type` might point to totally different type of
  /// data.
  void *data;
  /// Since multiple fibers can work on the same node at the same time, writers have to acquire the
  /// lock.
  srn_fiber_mutex_t *lock;
} srn_term_t;
 
typedef struct srn_graph_t {
  // Root nodes of the tree. Each IR has a dedicated root node
 
  /// A hashmap that maps namespace names to their value. When operating on
  /// this map, e.g. setting the new `hmap` after inserting a namespace which will lead to a new
  /// `hmap_t` make sure to lock `ns_map_lock`.
  hmap_t *namespaces;
  srn_fiber_mutex_t *ns_map_lock;
  // TODO(lxsameer): Do we need a lock per namespace here? or should we have one
  // in the namespace itself?
} srn_graph_t;