@lucent-lang/lucent 0.0.4 → 0.1.1

package/runtime/cpp/lucent/trace.h

@@ -0,0 +1,251 @@
+// Lucent runtime — tracing.
+//
+// Structured events that say why something was slow: how long a job waited
+// for its owner before it ran, how long a call waited for the Lucent lock,
+// how long a compute task waited for a worker, ran and waited to be
+// delivered, how many bytes a copy moved. Events that belong together (a
+// JS call, the job it posted, its completion) share a correlation id; a
+// job posted from another names it as its parent. Native code records its
+// own spans with the .lucent.ts site its #line names (LUCENT_TRACE_SCOPE).
+//
+// Tracing is off by default and costs one relaxed load where it is
+// checked. Started, it keeps the latest events in a bounded buffer
+// (counting those it drops), exportable as a Chrome trace; asked to, it
+// also mirrors spans live into the platform's tooling: os_signpost on
+// Apple platforms (Instruments), ATrace on Android (Perfetto, systrace).
+// The mirror is opt-in: signposts persist even when no tool records them.
+//
+// It starts from the environment too, when the module context starts:
+// LUCENT_TRACE=1 (the buffer), =platform (and the platform's tooling), or
+// =<file>.json (and a Chrome trace written there at exit). On Android the
+// debug.lucent.trace system property says the same, and ATrace, cheap
+// while nothing records, is always mirrored.
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace lucent::trace {
+
+enum class Category : uint8_t {
+  /// A call from JavaScript into Lucent code.
+  Entry,
+  /// Waiting for the Lucent lock.
+  Lock,
+  /// A posted job waiting for its owner to run it.
+  Queue,
+  /// A posted job running on its owner.
+  Run,
+  /// Native work: Lucent code, platform calls.
+  Native,
+  /// A result delivered back to JavaScript.
+  Completion,
+  /// A compute task: waiting for a worker, running, being delivered.
+  Compute,
+  /// Bytes copied (transport, native buffer snapshots).
+  Copy,
+  /// Native allocations.
+  Alloc,
+  /// A build phase (the CLI's build record).
+  Build,
+};
+
+const char* categoryName(Category category);
+
+/// Where native code came from: static, like the events that point at it.
+struct Site {
+  const char* name;
+  const char* file;
+  int line;
+};
+
+struct Event {
+  enum class Phase : char { Span = 'X', Instant = 'i', Counter = 'C' };
+
+  Phase phase = Phase::Span;
+  Category category = Category::Native;
+  /// A static string, like every string an event holds.
+  const char* name = "";
+  /// What the event concerns: a compute task's entry, say.
+  const char* detail = nullptr;
+
+  /// Nanoseconds on the trace clock (steady), and the span's length.
+  uint64_t startNs = 0;
+  uint64_t durationNs = 0;
+
+  /// What it is correlated with, and what it came from (0: nothing).
+  uint64_t id = 0;
+  uint64_t parent = 0;
+
+  /// Bytes copied, a queue's depth, a counter's value; objects copied.
+  int64_t value = 0;
+  int64_t count = 0;
+
+  /// A small number per thread, and the execution context it was in (0:
+  /// none).
+  uint32_t thread = 0;
+  uint32_t context = 0;
+
+  const Site* site = nullptr;
+};
+
+struct Options {
+  /// Events kept: the latest, older ones are dropped and counted.
+  size_t capacity = 1 << 16;
+  /// Mirror spans into os_signpost / ATrace as well.
+  bool platform = false;
+};
+
+namespace detail {
+// Constant-initialized: safe to read during static initialization.
+inline std::atomic<bool> active{false};
+}  // namespace detail
+
+/// Whether tracing is on: one relaxed load.
+inline bool enabled() noexcept { return detail::active.load(std::memory_order_relaxed); }
+
+/// Starts tracing with an empty buffer.
+void start(Options options = {});
+
+/// Stops recording; the buffer stays readable.
+void stop();
+
+/// Starts tracing if the environment asks for it (LUCENT_TRACE, or the
+/// debug.lucent.trace property on Android). Once per process.
+void startFromEnvironment();
+
+/// The events kept, oldest first, and how many were dropped.
+std::vector<Event> events();
+uint64_t dropped();
+
+/// The Chrome trace event format (chrome://tracing, Perfetto's UI), with
+/// flow arrows between events that share an id.
+std::string chromeJson(const std::vector<Event>& events);
+
+/// Writes events() as a Chrome trace; false if the file cannot be written.
+bool writeChromeJson(const std::string& path);
+
+/// Nanoseconds on the trace clock.
+uint64_t now() noexcept;
+uint64_t toNs(std::chrono::steady_clock::time_point at) noexcept;
+
+/// A process-unique correlation id (never 0).
+uint64_t newId() noexcept;
+
+/// What an event adds to its category and name.
+struct Detail {
+  uint64_t id = 0;
+  uint64_t parent = 0;
+  int64_t value = 0;
+  int64_t count = 0;
+  const Site* site = nullptr;
+  const char* detail = nullptr;
+};
+
+/// The start of a span; empty when tracing was off.
+struct Mark {
+  uint64_t startNs = 0;
+  /// Pairs the platform's begin and end, across threads.
+  uint64_t cookie = 0;
+
+  explicit operator bool() const noexcept { return startNs != 0; }
+};
+
+/// Begins a span: now, and live in the platform's tooling. Empty when off.
+Mark begin(Category category, const char* name) noexcept;
+
+/// Ends the span `mark` began (nothing if it is empty, or tracing stopped).
+void end(const Mark& mark, Category category, const char* name, const Detail& detail = {}) noexcept;
+
+/// A span recorded after the fact, from its two times.
+void span(Category category, const char* name, uint64_t startNs, uint64_t endNs, const Detail& detail = {}) noexcept;
+
+void instant(Category category, const char* name, uint64_t id = 0, int64_t value = 0) noexcept;
+void instant(Category category, const char* name, const Detail& detail) noexcept;
+
+void counter(const char* name, int64_t value) noexcept;
+
+/// The correlation id of the traced job running on this thread (0: none).
+uint64_t currentId() noexcept;
+
+/// While it lives, the traced job on this thread is `id`: jobs it posts
+/// name it as their parent.
+class Current {
+ public:
+  explicit Current(uint64_t id) noexcept;
+  ~Current();
+
+  Current(const Current&) = delete;
+  Current& operator=(const Current&) = delete;
+
+ private:
+  uint64_t previous_;
+};
+
+/// While it lives, the next job posted from this thread takes `id` rather
+/// than a new one: a JS call's id carried to the job it posts.
+class Correlate {
+ public:
+  explicit Correlate(uint64_t id) noexcept;
+  ~Correlate();
+
+  Correlate(const Correlate&) = delete;
+  Correlate& operator=(const Correlate&) = delete;
+
+ private:
+  uint64_t previous_;
+};
+
+/// The id a Correlate set for this thread's next post, taken (0: none).
+uint64_t takeCorrelation() noexcept;
+
+/// A span over a scope (native work): LUCENT_TRACE_SCOPE.
+class Scope {
+ public:
+  Scope(Category category, const char* name, const Site* site = nullptr, uint64_t id = 0) noexcept
+      : category_(category), name_(name), site_(site), id_(id) {
+    if (enabled()) [[unlikely]]
+      mark_ = begin(category, name);
+  }
+
+  ~Scope() {
+    if (mark_) [[unlikely]]
+      end(mark_, category_, name_, {.id = id_, .parent = currentId(), .value = value_, .site = site_});
+  }
+
+  Scope(const Scope&) = delete;
+  Scope& operator=(const Scope&) = delete;
+
+  void value(int64_t v) noexcept { value_ = v; }
+
+ private:
+  Mark mark_;
+  Category category_;
+  const char* name_;
+  const Site* site_;
+  uint64_t id_;
+  int64_t value_ = 0;
+};
+
+}  // namespace lucent::trace
+
+#define LUCENT_TRACE_CONCAT_(a, b) a##b
+#define LUCENT_TRACE_CONCAT(a, b) LUCENT_TRACE_CONCAT_(a, b)
+
+/// A static site: `name` at the file and line the code names (under a
+/// #line, the .lucent.ts source), or at `file`:`line` given explicitly.
+#define LUCENT_TRACE_SITE(name) LUCENT_TRACE_SITE_AT(name, __FILE__, __LINE__)
+#define LUCENT_TRACE_SITE_AT(name, file, line)                                                    \
+  ([]() -> const ::lucent::trace::Site* {                                                         \
+    static constexpr ::lucent::trace::Site lucentTraceSite{name, file, line};                    \
+    return &lucentTraceSite;                                                                      \
+  }())
+
+/// A native span over the rest of the scope, named `name`, at its site.
+#define LUCENT_TRACE_SCOPE(name)                                                                  \
+  ::lucent::trace::Scope LUCENT_TRACE_CONCAT(lucentTraceScope, __LINE__)(::lucent::trace::Category::Native, name, \
+                                                                          LUCENT_TRACE_SITE(name))

package/runtime/cpp/lucent/transport.cpp

@@ -0,0 +1,9 @@
+#include "transport.h"
+
+namespace lucent {
+
+void throwDataCloneError(const char* message) {
+  throwError(String::fromLatin1("DataCloneError"), String::fromUtf8(message));
+}
+
+}  // namespace lucent

package/runtime/cpp/lucent/transport.h

@@ -0,0 +1,341 @@
+// Lucent runtime — the values a compute task receives.
+//
+// A task runs on another thread, so it shares nothing mutable with the code
+// that submitted it: its input is copied, at submission, into a graph only
+// the task holds. Every array, map, set, dictionary, byte buffer, date and
+// object reachable from the input is copied once, so two references to one
+// object are two references to one copy, and cycles survive. Strings are
+// immutable, so they cross as they are. The copy is the whole transport:
+// the task runs in the same process, so there is no wire format to unpack.
+//
+// A type crosses if it has a Transport. The runtime's value types have one;
+// the compiler emits one for each struct and class (with transportObject).
+// Anything else (functions, promises, signals, native instances) does not
+// compile. An object whose class is a subclass of the one its type names is
+// refused when copied, with a DataCloneError: its copy would lose fields.
+//
+// A transport may move instead of copying, for something that must have one
+// owner at a time (an owned native buffer): it hands the task the thing
+// itself and registers the move with the graph (CopyGraph::onCommit). Moves
+// commit only once the whole input has been copied, and roll back if the
+// copy fails, so a refused submission leaves the caller's values as they
+// were.
+#pragma once
+
+#include <any>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <tuple>
+#include <type_traits>
+#include <typeinfo>
+#include <unordered_map>
+#include <utility>
+#include <variant>
+#include <vector>
+
+#include "array.h"
+#include "bigint.h"
+#include "bytes.h"
+#include "core.h"
+#include "date.h"
+#include "jserror.h"
+#include "jsstring.h"
+#include "map.h"
+#include "trace.h"
+
+namespace lucent {
+
+/// What a copy refuses to copy: a DataCloneError, as structuredClone throws.
+[[noreturn]] void throwDataCloneError(const char* message);
+
+/// One input's copy in progress: the copies made so far, by the identity of
+/// what they copy, and the moves to commit once it is complete.
+class CopyGraph {
+ public:
+  CopyGraph() = default;
+  CopyGraph(const CopyGraph&) = delete;
+  CopyGraph& operator=(const CopyGraph&) = delete;
+
+  /// The copy already made of the object `identity` names, if any.
+  template <class H>
+  const H* find(const void* identity) const {
+    auto it = copies_.find(identity);
+    if (it == copies_.end()) return nullptr;
+
+    const H* copy = std::any_cast<H>(&it->second);
+    if (!copy) throwDataCloneError("An object reached as two different types cannot be copied");
+
+    return copy;
+  }
+
+  /// Records `copy` as the copy of `identity`: before copying what the
+  /// object holds, so a cycle leads back to the copy.
+  template <class H>
+  void remember(const void* identity, const H& copy) {
+    copies_.emplace(identity, std::any(copy));
+  }
+
+  /// For a transport that moves: `commit` runs once the whole input has
+  /// been copied, `rollback` (if any) instead if the copy fails. Each runs
+  /// on the submitting thread, in the order registered.
+  void onCommit(std::function<void()> commit, std::function<void()> rollback = nullptr) {
+    moves_.push_back({std::move(commit), std::move(rollback)});
+  }
+
+  /// Objects copied (or moved) so far.
+  size_t copied() const { return copies_.size(); }
+
+  /// Bytes of element storage copied so far (arrays, byte buffers): what
+  /// a trace reports for the copy.
+  size_t bytes() const { return bytes_; }
+  void countBytes(size_t n) { bytes_ += n; }
+
+  /// Runs the commits (or, if `failed`, the rollbacks) and forgets them.
+  void finish(bool failed) {
+    auto moves = std::move(moves_);
+    moves_.clear();
+
+    for (auto& [commit, rollback] : moves) {
+      if (!failed) {
+        commit();
+      } else if (rollback) {
+        rollback();
+      }
+    }
+  }
+
+ private:
+  std::unordered_map<const void*, std::any> copies_;
+  std::vector<std::pair<std::function<void()>, std::function<void()>>> moves_;
+  size_t bytes_ = 0;
+};
+
+/// How a `T` crosses to a task: `static T copy(const T&, CopyGraph&)`.
+/// Specialized for the runtime's value types here and, by the compiler, for
+/// each struct and class. Unspecialized, the type cannot cross.
+template <class T>
+struct Transport {};
+
+template <class T>
+concept Transportable = requires(const T& value, CopyGraph& graph) {
+  { Transport<T>::copy(value, graph) } -> std::same_as<T>;
+};
+
+/// Copies one part of an input: what a Transport calls for what it holds.
+template <class T>
+T transport(const T& value, CopyGraph& graph) {
+  static_assert(Transportable<T>, "This type cannot cross to a compute task: it has no lucent::Transport");
+
+  return Transport<T>::copy(value, graph);
+}
+
+/// Copies `value` for a task, committing the moves it registered; if the
+/// copy throws, they roll back and the error reaches the caller.
+template <class T>
+T transportCopy(const T& value) {
+  CopyGraph graph;
+  trace::Mark mark = trace::begin(trace::Category::Copy, "transport.copy");
+
+  try {
+    T copy = transport(value, graph);
+    graph.finish(false);
+
+    trace::end(mark, trace::Category::Copy, "transport.copy",
+               {.parent = trace::currentId(), .value = static_cast<int64_t>(graph.bytes()), .count = static_cast<int64_t>(graph.copied())});
+    return copy;
+  } catch (...) {
+    graph.finish(true);
+    trace::end(mark, trace::Category::Copy, "transport.copy", {.parent = trace::currentId(), .count = -1});
+    throw;
+  }
+}
+
+/// A Transport for a struct or class `T` (the compiler emits one per type):
+/// refuses an object of a subclass, makes one copy per object, remembers it
+/// before `fields(from, to, graph)` copies what it holds. `T` must be
+/// default-constructible.
+template <class T, class Fields>
+Ref<T> transportObject(const Ref<T>& source, CopyGraph& graph, Fields&& fields) {
+  if (!source) return source;
+
+  // Most derived: the same object reached through any base is one.
+  const void* identity = dynamic_cast<const void*>(source.get());
+  if (auto* copy = graph.find<Ref<T>>(identity)) return *copy;
+
+  if (typeid(*source) != typeid(T)) throwDataCloneError("An object of a subclass cannot be copied as its base class");
+
+  auto copy = std::make_shared<T>();
+  graph.remember(identity, copy);
+
+  fields(*source, *copy, graph);
+  return copy;
+}
+
+// --- the runtime's values -----------------------------------------------------
+
+namespace detail {
+
+/// Values that cross as they are: plain data, and immutable strings and
+/// bigints.
+template <class T>
+concept CrossesAsIs = std::is_arithmetic_v<T> || std::is_enum_v<T> || std::is_same_v<T, String> ||
+                      std::is_same_v<T, BigInt> || std::is_same_v<T, Undefined> || std::is_same_v<T, Null>;
+
+}  // namespace detail
+
+template <class T>
+  requires detail::CrossesAsIs<T>
+struct Transport<T> {
+  static T copy(const T& value, CopyGraph&) { return value; }
+};
+
+template <Transportable T>
+struct Transport<Opt<T>> {
+  static Opt<T> copy(const Opt<T>& value, CopyGraph& graph) {
+    if (value.has()) return Opt<T>(transport(value.get(), graph));
+
+    return value;
+  }
+};
+
+template <Transportable... Ts>
+struct Transport<std::variant<Ts...>> {
+  using V = std::variant<Ts...>;
+
+  static V copy(const V& value, CopyGraph& graph) { return copyAt<0>(value, graph); }
+
+  /// By index, not type: an alternative's type may repeat.
+  template <size_t I>
+  static V copyAt(const V& value, CopyGraph& graph) {
+    if constexpr (I + 1 < sizeof...(Ts)) {
+      if (value.index() != I) return copyAt<I + 1>(value, graph);
+    }
+
+    return V(std::in_place_index<I>, transport(*std::get_if<I>(&value), graph));
+  }
+};
+
+template <Transportable... Ts>
+struct Transport<std::tuple<Ts...>> {
+  static std::tuple<Ts...> copy(const std::tuple<Ts...>& value, CopyGraph& graph) {
+    // Braced: the parts are copied in order.
+    return std::apply([&](const Ts&... parts) { return std::tuple<Ts...>{transport(parts, graph)...}; }, value);
+  }
+};
+
+template <Transportable T>
+struct Transport<Array<T>> {
+  static Array<T> copy(const Array<T>& source, CopyGraph& graph) {
+    if (auto* copy = graph.find<Array<T>>(source.identity())) return *copy;
+
+    Array<T> copy;
+    graph.remember(source.identity(), copy);
+
+    if constexpr (detail::CrossesAsIs<T>) {
+      copy.items() = source.items();
+      graph.countBytes(source.size() * sizeof(typename Array<T>::Elem));
+    } else {
+      auto& items = copy.items();
+      items.reserve(source.size());
+      graph.countBytes(source.size() * sizeof(typename Array<T>::Elem));
+
+      for (const auto& item : source.items()) items.push_back(transport(item, graph));
+    }
+
+    return copy;
+  }
+};
+
+template <Transportable K, Transportable V>
+struct Transport<Map<K, V>> {
+  static Map<K, V> copy(const Map<K, V>& source, CopyGraph& graph) {
+    if (auto* copy = graph.find<Map<K, V>>(source.identity())) return *copy;
+
+    Map<K, V> copy;
+    graph.remember(source.identity(), copy);
+
+    auto& table = source.table();
+    for (size_t i = 0; i < table.slotCount(); i++) {
+      if (!table.slotLive(i)) continue;
+
+      const auto& entry = table.slot(i);
+      copy.set(transport(entry.key, graph), transport(entry.value, graph));
+    }
+
+    return copy;
+  }
+};
+
+template <Transportable T>
+struct Transport<Set<T>> {
+  static Set<T> copy(const Set<T>& source, CopyGraph& graph) {
+    if (auto* copy = graph.find<Set<T>>(source.identity())) return *copy;
+
+    Set<T> copy;
+    graph.remember(source.identity(), copy);
+
+    auto& table = source.table();
+    for (size_t i = 0; i < table.slotCount(); i++) {
+      if (table.slotLive(i)) copy.add(transport(table.slot(i).key, graph));
+    }
+
+    return copy;
+  }
+};
+
+template <Transportable V>
+struct Transport<Dict<V>> {
+  static Dict<V> copy(const Dict<V>& source, CopyGraph& graph) {
+    if (auto* copy = graph.find<Dict<V>>(source.identity())) return *copy;
+
+    Dict<V> copy;
+    graph.remember(source.identity(), copy);
+
+    auto& table = source.table();
+    for (size_t i = 0; i < table.slotCount(); i++) {
+      if (!table.slotLive(i)) continue;
+
+      const auto& entry = table.slot(i);
+      copy.set(entry.key, transport(entry.value, graph));
+    }
+
+    return copy;
+  }
+};
+
+/// Views of one buffer stay views of one (copied) buffer, as
+/// structuredClone keeps them: a view carries its whole buffer, so slice()
+/// a small view of a large buffer before submitting it.
+template <>
+struct Transport<Bytes> {
+  using Buffer = std::shared_ptr<std::vector<uint8_t>>;
+
+  static Bytes copy(const Bytes& source, CopyGraph& graph) {
+    const Buffer& buffer = source.buffer();
+
+    const Buffer* copied = graph.find<Buffer>(buffer.get());
+    if (!copied) {
+      graph.remember(buffer.get(), std::make_shared<std::vector<uint8_t>>(*buffer));
+      graph.countBytes(buffer->size());
+      copied = graph.find<Buffer>(buffer.get());
+    }
+
+    return Bytes::view(*copied, source.offset(), source.size());
+  }
+};
+
+template <>
+struct Transport<Date> {
+  static Date copy(const Date& source, CopyGraph& graph) {
+    if (!source) return source;
+
+    if (auto* copy = graph.find<Date>(source.get())) return *copy;
+
+    Date copy = makeDate(source->getTime());
+    graph.remember(source.get(), copy);
+    return copy;
+  }
+};
+
+}  // namespace lucent