utils.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
 
// Global master switch for local debugging (default off).
// Read more on this further down
#include <stdatomic.h>
#include <stdint.h>
#ifndef SERENE_DEBUG
#  define SERENE_DEBUG 0
#endif
 
#include <stdarg.h>
#include <stddef.h>
#include <stdio.h>
 
// SSE2 intrinsic instructions.
// while this is not portable, if __SSE2__ is defined then the compiler
// and platform already supports it
#if defined(__SSE2__)
#  include <emmintrin.h>
#endif
 
typedef struct srn_context_t srn_context_t;
typedef struct srn_mm_t srn_mm_t;
 
#define UNUSED(x) (void)(x)
 
// -----------------------------------------------------------------------------
// Panic Helpers
// -----------------------------------------------------------------------------
[[noreturn]] void srn_panic(const char *msg, const char *file, size_t line,
                            const char *fn);
 
#define PANIC(msg) srn_panic(msg, __FILE__, __LINE__, __func__)
#define TODO(msg)  PANIC(msg)
#define PANIC_WITH_CTX(ctx, msg) \
  srn_context_release(ctx);      \
  PANIC(msg)
 
#define PANIC_IF(cond, msg) \
  do {                      \
    if (cond) {             \
      PANIC(msg);           \
    }                       \
  } while (0)
 
#define PANIC_IF_NULL(ptr) PANIC_IF((ptr) == nullptr, "Null pointer")
 
#define SNPRINTF(buf, s, f, ...)                                \
  do {                                                          \
    int i = snprintf(buf, (s) + 1, f, __VA_ARGS__);             \
    if (i < 0) {                                                \
      PANIC("[snprintf] A negative return value");              \
    }                                                           \
    if (i >= (int)(s)) {                                        \
      PANIC("[snprintf] Written bytes are more than expected"); \
    }                                                           \
  } while (0)
 
#define SHOULD_NOT_HAPPEN PANIC("This should not happen")
#define PANIC_ON_ERR(interr) \
  if ((interr) < 0) {        \
    SHOULD_NOT_HAPPEN;       \
  }
 
// -----------------------------------------------------------------------------
// Development Debugging helpers
// These helpers are for local development only and can be turned on by setting
// the `SERENE_DEBUG` flag to `1`.
//
// These helpers are pretty much manual, meaning that developers should edit
// the values if they want different behaviour.
//
// Each module should define their own debug wrapper macro for example, in gc.h:
//
// #define GC_LOG(FMT, ...) DBG("GC", FMT __VA_OPT__(, ) __VA_ARGS__)
//
// IMPORTANT NOTES:
//  - DO NOT USE THE FUNCTIONS DIRECTLY, instead use the debugging macros.
//  - These functions are NOT thread safe, just because we don't need them to.
// -----------------------------------------------------------------------------
#if defined(__clang__) || defined(__GNUC__)
#  define SRN_ATTR_COLD      [[gnu::cold]]
#  define SRN_ATTR_FMT(a, b) [[gnu::format(__printf__, a, b)]]
#else
#  define SRN_ATTR_COLD
#  define SRN_ATTR_FMT(a, b)
#endif
 
// These helpers are available only in debug mode
#if SERENE_DEBUG
 
/// default output
#  define SRN_DBG_OUT stdout
 
SRN_ATTR_COLD static inline void srn_dbg_prefix(FILE *out, const char *prefix,
                                                const char *file, int line,
                                                const char *func) {
 
  int res = fprintf(out, "[%s]%s:%d:(%s): ", prefix == nullptr ? "SRN" : prefix,
                    file, line, func);
  if (res < 0) {
    SHOULD_NOT_HAPPEN;
  }
}
 
SRN_ATTR_COLD static inline void srn_dbg_vlog(FILE *out, const char *prefix,
                                              const char *file, int line,
                                              const char *func, const char *fmt,
                                              va_list ap) {
  // atomic line writes
  srn_dbg_prefix(out, prefix, file, line, func);
  PANIC_ON_ERR(vfprintf(out, fmt, ap));
  PANIC_ON_ERR(fputc('\n', out));
}
 
SRN_ATTR_COLD SRN_ATTR_FMT(6, 7) static inline void srn_dbg_log(
    FILE *out, const char *prefix, const char *file, int line, const char *func,
    const char *fmt, ...) {
 
  va_list ap;
  va_start(ap, fmt);
  srn_dbg_vlog(out, prefix, file, line, func, fmt, ap);
  va_end(ap);
}
 
SRN_ATTR_COLD static inline void
srn_dbg_hexdump_here(FILE *out, const char *file, int line, const char *func,
                     const void *data, size_t len) {
  const unsigned char *p = (const unsigned char *)data;
  srn_dbg_prefix(out, "Hexdump", file, line, func);
  UNUSED(fprintf(out, "hexdump %zu bytes\n", len));
  for (size_t i = 0; i < len; i += 16) {
    UNUSED(fprintf(out, "  %08zx  ", i));
    for (size_t j = 0; j < 16; ++j) {
      if (i + j < len) {
        UNUSED(fprintf(out, "%02x ", p[i + j]));
      } else {
        UNUSED(fputs("   ", out));
      }
    }
 
    UNUSED(fputs(" ", out));
    for (size_t j = 0; j < 16 && i + j < len; ++j) {
      unsigned char c = p[i + j];
      UNUSED(fputc((c >= 32 && c < 127) ? c : '.', out));
    }
    UNUSED(fputc('\n', out));
  }
}
 
#  define DBG(PREFIX, FMT, ...)                                    \
    srn_dbg_log(SRN_DBG_OUT, PREFIX, __FILE__, __LINE__, __func__, \
                FMT __VA_OPT__(, ) __VA_ARGS__)
#  define DBG_HEX(PTR, LEN)                                                \
    srn_dbg_hexdump_here(SRN_DBG_OUT, __FILE__, __LINE__, __func__, (PTR), \
                         (LEN))
 
#else // if SERENE_DEBUG
#  define DBG(...) \
    do {           \
    } while (0)
#  define DBG_HEX(...) \
    do {               \
    } while (0)
#  define DBG_ASSERT(x) \
    do {                \
      (void)sizeof(x);  \
    } while (0)
#endif // if SERENE_DEBUG
 
// -----------------------------------------------------------------------------
// Popcount helpers
// -----------------------------------------------------------------------------
static inline uint32_t srn_popcnt32(uint32_t x) {
#if defined(__clang__) || defined(__GNUC__)
  return (uint32_t)__builtin_popcount(x);
#else
  x = x - ((x >> 1) & 0x55555555u);
  x = (x & 0x33333333u) + ((x >> 2) & 0x33333333u);
  return (((x + (x >> 4)) & 0x0F0F0F0Fu) * 0x01010101u) >> 24;
#endif
}
 
static inline uint64_t srn_popcnt64(uint64_t x) {
#if defined(__GNUC__) || defined(__clang__)
  return (uint64_t)__builtin_popcountll(x);
#else
  unsigned c = 0;
  while (x) {
    x &= x - 1;
    ++c;
  }
  return c;
#endif
}
 
// -----------------------------------------------------------------------------
// Generic Helpers
// -----------------------------------------------------------------------------
/// A portable way to use pasue instructions.
/// The long list of preprocessors is there thanks to:
/// https://github.com/goodcleanfun/cpu_relax
static inline void cpu_relax(void) {
#if defined(_M_IX86) || defined(__I86__) || defined(i686) ||  \
    defined(__i686) || defined(__i686__) || defined(i586) ||  \
    defined(__i586) || defined(__i586__) || defined(i486) ||  \
    defined(__i486) || defined(__i486__) || defined(i386) ||  \
    defined(__i386) || defined(__i386__) || defined(_X86_) || \
    defined(__X86__) || defined(__THW_INTEL__)
#  if defined(__SSE2__)
  _mm_pause();
#  elif defined(_MSC_VER)
  __asm pause;
#  else
  __asm__ __volatile__("pause");
#  endif
#elif defined(__amd64__) || defined(__amd64) || defined(__x86_64__) || \
    defined(__x86_64) || defined(_M_X64) || defined(_M_AMD64)
#  if defined(__SSE2__)
  _mm_pause();
#  endif
#elif defined(__aarch64__) || defined(_M_ARM64)
#  if defined(_MSC_VER)
  __isb(_ARM64_BARRIER_SY);
#  else
  __asm__ __volatile__("isb\n");
#  endif
#elif defined(__ARM_ARCH) || defined(_M_ARM) || defined(__arm__) || \
    defined(__thumb__) || defined(__TARGET_ARCH_ARM) || defined(_ARM)
#  if defined(_MSC_VER)
  __yield();
#  else
  __asm__ __volatile__("yield");
#  endif
#elif defined(__powerpc) || defined(__powerpc__) || defined(__POWERPC__) || \
    defined(__ppc__) || defined(__PPC__) || defined(_ARCH_PPC) ||           \
    defined(__ppc)
  __asm__ __volatile__("or 27,27,27" ::: "memory");
#elif defined(__riscv) || defined(__riscv__)
#  if defined(__riscv_pause)
  __builtin_riscv_pause();
#  else
  __asm__ __volatile__("nop");
#  endif
#elif defined(__loongarch32) || defined(__loongarch64)
  __asm__ __volatile__("nop");
#elif defined(__wasm__)
  __asm__ __volatile__("nop");
#endif
}
 
// -----------------------------------------------------------------------------
// Simple spinlock
// -----------------------------------------------------------------------------
typedef struct srn_spinlock_t {
  atomic_flag flag;
} srn_spinlock_t;
 
static inline void srn_spinlock_unlock(srn_spinlock_t *lock) {
  atomic_flag_clear_explicit(&lock->flag, memory_order_release);
}
 
static inline void srn_spinlock_init(srn_spinlock_t *lock) {
  lock->flag = (atomic_flag)ATOMIC_FLAG_INIT;
  srn_spinlock_unlock(lock);
}
 
static inline void srn_spinlock_lock(srn_spinlock_t *lock) {
  while (atomic_flag_test_and_set_explicit(&lock->flag, memory_order_acquire)) {
    // Keep busy for the lock to get unlocked
    cpu_relax();
  }
}
 
// -----------------------------------------------------------------------------
// Strings and buffers related helpers
// -----------------------------------------------------------------------------
char *srn_copy_bytes(srn_context_t *ctx, const char *src, size_t len,
                     size_t alignment);
 
/// Copy a null terminated C string into a fresh allocation made through
/// `mm`. Returns nullptr on allocation failure.
[[gnu::nonnull(1, 2)]] char *srn_dup_str(srn_mm_t *mm, const char *s);