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 <limits.h>
#include <stdarg.h>
#include <stdatomic.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
 
#ifndef SERENE_DEBUG
#  define SERENE_DEBUG 0
#endif
 
// 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 RETURN_IF_NULL(ptr) \
  if ((ptr) == nullptr) {   \
    return;                 \
  }
 
#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(const 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);
 
// -----------------------------------------------------------------------------
// Time helpers
// -----------------------------------------------------------------------------
/// nanoseconds in one second
#define SRN_NS_PER_SEC 1000000000ULL
/// nanoseconds in one millisecond
#define SRN_NS_PER_MS 1000000ULL
 
/// The current time on the monotonic clock, in nanoseconds. Panics if the clock
/// read fails -- `CLOCK_MONOTONIC` with a valid buffer cannot fail on supported
/// targets, so a failure means something is deeply wrong.
uint64_t srn_now_ns(void);
 
// -----------------------------------------------------------------------------
// Limit finder helpers
// -----------------------------------------------------------------------------
 
#define TYPE_BITS(T)                 (sizeof(T) * CHAR_BIT)
#define MAX_POW2_EXP_FOR_UNSIGNED(T) (TYPE_BITS(T) - 1)