@lucent-lang/lucent 0.0.4 → 0.1.1

package/runtime/cpp/lucent/execution.h

@@ -0,0 +1,270 @@
+// Lucent runtime — execution contexts.
+//
+// An execution context is where Lucent code runs one piece at a time. Its
+// executor (a thread, or the platform's main loop) runs turns in the order
+// they were posted; each turn runs its job, then the context's own
+// microtasks. Its root scope is the ancestor of every scope created for
+// work that lives there. There are three kinds:
+//
+// - the legacy module context (Scheduler, scheduler.h): the Lucent thread,
+//   also entered from any thread by taking the Lucent lock. Every module's
+//   code runs there, serialized as it always was.
+// - the main context: the platform's UI loop. It never takes the Lucent
+//   lock, so it never waits behind module code.
+// - isolated contexts, each with a thread of its own.
+//
+// A context never waits for another: work crosses between them as posted
+// jobs that own what they carry.
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <deque>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <queue>
+#include <thread>
+#include <vector>
+
+#include "report.h"
+#include "scope.h"
+
+namespace lucent {
+
+using Job = std::function<void()>;
+
+/// Process-unique and never reused; 0 is none.
+using ContextId = uint32_t;
+
+/// Runs `job` on the platform's main thread (main queue, main Looper; a
+/// dedicated thread standing in for it on other hosts). Implemented per
+/// platform: lucent/platform, and native.cpp for hosts.
+void postToMain(std::function<void()> job);
+bool onMainThread();
+
+/// A thread that runs posted jobs, and timers once due, one at a time in
+/// order. The thread keeps this object alive until it ends.
+class WorkerThread : public std::enable_shared_from_this<WorkerThread> {
+ public:
+  /// How the thread runs a job (a context's turn).
+  using Run = std::function<void(Job&)>;
+
+  static std::shared_ptr<WorkerThread> start(Run run);
+
+  WorkerThread(const WorkerThread&) = delete;
+  WorkerThread& operator=(const WorkerThread&) = delete;
+
+  /// Any thread. False once stopping: the job is dropped.
+  bool post(Job job);
+  bool postDelayed(double ms, Job job);
+
+  bool isCurrent() const { return std::this_thread::get_id() == id_; }
+
+  /// Jobs queued or running, and timers pending.
+  size_t pendingWork();
+
+  /// Blocks until no jobs or timers are pending, or the timeout elapses.
+  /// For tests and tools: never call it from a context's thread.
+  bool waitIdle(double timeoutMs);
+
+  /// Takes no more work: runs `last` (directly, not through Run) after the
+  /// job running now, destroys what is still queued on this thread, and
+  /// ends it. Returns at once, without waiting for any of that.
+  void stop(Job last = nullptr);
+
+  /// Blocks until the thread has ended, or the timeout elapses (tests).
+  bool waitStopped(double timeoutMs);
+
+ private:
+  explicit WorkerThread(Run run) : run_(std::move(run)) {}
+
+  void loop();
+
+  struct Timer {
+    std::chrono::steady_clock::time_point at;
+    uint64_t seq;
+    Job job;
+
+    bool operator>(const Timer& o) const { return at != o.at ? at > o.at : seq > o.seq; }
+  };
+
+  const Run run_;
+  std::thread::id id_;
+
+  std::mutex m_;
+  std::condition_variable cv_;
+  std::condition_variable idleCv_;
+  std::deque<Job> jobs_;
+  std::priority_queue<Timer, std::vector<Timer>, std::greater<Timer>> timers_;
+  uint64_t timerSeq_ = 0;
+  size_t running_ = 0;
+  bool stopping_ = false;
+  bool stopped_ = false;
+  Job last_;
+};
+
+class ExecutionContext;
+
+/// A context as an owner: null names the legacy module context, which owns
+/// whatever no other context does.
+using ContextRef = std::shared_ptr<ExecutionContext>;
+
+/// Also the owner of its root scope and the scopes under it: their disposal
+/// runs here.
+class ExecutionContext : public Scope::Owner, public std::enable_shared_from_this<ExecutionContext> {
+ public:
+  ExecutionContext(const ExecutionContext&) = delete;
+  ExecutionContext& operator=(const ExecutionContext&) = delete;
+  virtual ~ExecutionContext() = default;
+
+  /// The context the calling thread is in: the legacy module context while
+  /// the thread holds the Lucent lock, else the one it entered (a turn, or
+  /// a ContextEntry); null outside any.
+  static ExecutionContext* current();
+
+  /// current() as an owner reference (null for the legacy module context,
+  /// and outside any context).
+  static ContextRef currentRef();
+
+  /// The legacy module context (Scheduler::instance()).
+  static ExecutionContext& legacy();
+
+  /// The context `ref` names.
+  static ExecutionContext& of(const ContextRef& ref) { return ref ? *ref : legacy(); }
+
+  /// The platform's UI loop (a stand-in thread on hosts without one).
+  static ExecutionContext& main();
+
+  ContextId id() const { return id_; }
+
+  const std::shared_ptr<Scope>& root() const { return root_; }
+
+  bool isCurrent() const override { return current() == this; }
+
+  /// Whether the calling thread is the one this context's turns run on
+  /// (the main thread, for the main context), entered or not.
+  virtual bool onExecutor() const = 0;
+
+  /// Any thread: runs `job` as a turn of this context. False if the
+  /// context has stopped; the job is then destroyed on the calling thread.
+  bool post(Job job) override;
+
+  /// As post(), but the job is dropped, not run, if `owner` was disposed
+  /// before its turn came (it is destroyed on this context).
+  bool post(Job job, const std::shared_ptr<Scope>& owner);
+
+  /// Any thread: runs `job` as a turn of this context after `ms`.
+  bool postDelayed(double ms, Job job);
+
+  /// Queues a microtask. Only on this context: throws std::logic_error
+  /// elsewhere (post instead).
+  void enqueueMicrotask(Job job);
+
+  /// Runs queued microtasks, including those they queue. Only on this
+  /// context.
+  void drainMicrotasks();
+
+  bool hasMicrotasks() const { return *pendingMicrotasks_ > 0; }
+
+ protected:
+  /// `microtaskCount` is where the context counts its microtasks, if not in
+  /// itself: the legacy module context's is a static, which every call from
+  /// JavaScript reads without reaching the instance.
+  explicit ExecutionContext(size_t* microtaskCount = nullptr);
+
+  /// Gives the context its root scope, owned by it. Called once, by the
+  /// factory: the context must already be shared.
+  void makeRoot() { root_ = Scope::createRoot(0, weak_from_this()); }
+
+  /// Hands a turn to the executor; false if it has stopped.
+  virtual bool dispatch(Job job) = 0;
+  virtual bool dispatchDelayed(double ms, Job job) = 0;
+
+  /// Runs `job` as a turn: entered, the job run and destroyed, then the
+  /// microtasks.
+  virtual void runTurn(Job& job);
+
+ private:
+  friend class ContextEntry;
+
+  const ContextId id_;
+  std::shared_ptr<Scope> root_;
+
+  std::deque<Job> microtasks_;
+  size_t ownMicrotasks_ = 0;
+  size_t* const pendingMicrotasks_;
+};
+
+/// Enters a context other than the legacy module context (which is entered
+/// with LucentScope) on the calling thread: for a platform callback that
+/// needs an answer now. The thread must be the context's own (the main
+/// thread for the main context), not holding the Lucent lock. Leaving the
+/// outermost entry runs the context's microtasks.
+class ContextEntry {
+ public:
+  explicit ContextEntry(ExecutionContext& context);
+  ~ContextEntry();
+
+  ContextEntry(const ContextEntry&) = delete;
+  ContextEntry& operator=(const ContextEntry&) = delete;
+
+ private:
+  ExecutionContext& context_;
+  ExecutionContext* previous_;
+};
+
+/// A context with a thread of its own, running until shutdown().
+class IsolatedContext final : public ExecutionContext {
+ public:
+  static std::shared_ptr<IsolatedContext> create();
+
+  /// Shuts down.
+  ~IsolatedContext() override;
+
+  /// Takes no more work, then, on its thread and after the turn running
+  /// now: disposes the root scope and drops whatever is still queued.
+  /// Returns at once.
+  void shutdown();
+
+  size_t pendingWork() { return worker_->pendingWork(); }
+
+  /// For tests: see WorkerThread.
+  bool waitIdle(double timeoutMs) { return worker_->waitIdle(timeoutMs); }
+  bool waitStopped(double timeoutMs) { return worker_->waitStopped(timeoutMs); }
+
+ private:
+  IsolatedContext();
+
+  bool dispatch(Job job) override;
+  bool dispatchDelayed(double ms, Job job) override;
+  bool onExecutor() const override { return worker_->isCurrent(); }
+
+  std::shared_ptr<WorkerThread> worker_;
+  std::atomic<bool> stopping_{false};
+};
+
+/// The scope module code's work belongs to (a compute task, say): the scope
+/// of the JavaScript runtime its modules run for, so tearing that runtime
+/// down (a reload) cancels the work; the legacy module context's root while
+/// no runtime is attached. A torn-down runtime's scope stays the module
+/// scope until another replaces it: nothing more starts for it. Any thread.
+std::shared_ptr<Scope> moduleScope();
+
+/// Makes `scope` the module scope (null: none); Host::create gives it the
+/// new runtime's.
+void setModuleScope(std::shared_ptr<Scope> scope);
+
+namespace detail {
+/// Runs `job`, reporting what it throws.
+void runGuarded(Job& job, const char* where);
+
+/// Runs `job` on the thread `on` runs on: here if that is this thread, or
+/// `on` is null (what it throws reaches the caller); else as a turn there,
+/// where what it throws is reported. Here too if `on` takes no more work.
+void runOn(ExecutionContext* on, Job job);
+}  // namespace detail
+
+}  // namespace lucent

package/runtime/cpp/lucent/extension.cpp

@@ -0,0 +1,97 @@
+#include "extension.h"
+
+#include <cstring>
+
+namespace lucent {
+
+Handle Handle::open(const char* what, void* pointer, void (*destroy)(void*), ExecutionContext* destroyOn) {
+  auto state = std::make_shared<State>();
+  state->pointer = pointer;
+  state->destroy = destroy;
+
+  // The state owns the resource: the release reaches the state through a raw pointer.
+  State* raw = state.get();
+  state->resource = Resource::open(String::fromUtf8(what), [raw] { raw->closing(); }, destroyOn);
+
+  Handle h;
+  h.state_ = std::move(state);
+  return h;
+}
+
+void Handle::State::closing() {
+  {
+    std::lock_guard<std::mutex> lock(mutex);
+
+    if (calls > 0) {
+      deferred = true;
+      return;
+    }
+  }
+
+  destroy(pointer);
+}
+
+void Handle::State::release() {
+  bool last;
+  {
+    std::lock_guard<std::mutex> lock(mutex);
+    last = --calls == 0 && deferred;
+    if (last) deferred = false;
+  }
+
+  if (last) destroy(pointer);
+}
+
+void Handle::acquire() const {
+  if (!state_) throwError(String::fromLatin1("InvalidStateError"), String::fromLatin1("the handle is not open"));
+
+  // Checked and counted together: a close either sees this call or refuses it.
+  std::lock_guard<std::mutex> lock(state_->mutex);
+  state_->resource->check();
+  state_->calls++;
+}
+
+void Handle::close() const {
+  if (state_) state_->resource->close();
+}
+
+namespace ext {
+
+void outOfRange(const char* what, const std::string& low, const std::string& high, const std::string& value) {
+  throwError(String::fromLatin1("RangeError"),
+             String::fromUtf8(std::string(what) + " must be an integer from " + low + " to " + high + ", not " + value));
+}
+
+uint8_t* data(Bytes& bytes) {
+  static uint8_t none = 0;
+
+  return bytes.size() ? bytes.data() : &none;
+}
+
+std::string utf8(const String& s, const char* what) {
+  std::string out = s.toUtf8();
+
+  if (out.find('\0') != std::string::npos)
+    throwError(String::fromLatin1("TypeError"),
+               String::fromUtf8(std::string(what) + " holds a NUL character, which a C string cannot"));
+
+  return out;
+}
+
+static Error failure(const char* function, const char* message) {
+  bool has = message && *message;
+
+  return makeError(has ? String::fromUtf8(std::string_view(message, std::strlen(message)))
+                       : String::fromUtf8(std::string(function) + " failed"));
+}
+
+void fail(const char* function, const char* message) { throwError(failure(function, message)); }
+
+void fail(const char* function, const char* message, long long code) {
+  Error e = failure(function, message);
+  e->code = String::fromUtf8(std::to_string(code));
+  throwError(e);
+}
+
+}  // namespace ext
+}  // namespace lucent

package/runtime/cpp/lucent/extension.h

@@ -0,0 +1,210 @@
+// Lucent runtime — native extensions: C functions a Lucent package declares.
+//
+// A Handle owns an opaque C pointer an extension's create function gave.
+// It closes at the first of close() or its last copy going; the destroy
+// function runs once, on the context the handle requires. After that,
+// every use throws InvalidStateError.
+//
+// The conversions check what crosses into C: numbers into integer
+// parameters as WebIDL's [EnforceRange] does, bigints exactly, byte counts
+// against their length type, and strings as NUL-terminated UTF-8.
+#pragma once
+
+#include <cmath>
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <type_traits>
+
+#include "bigint.h"
+#include "bytes.h"
+#include "execution.h"
+#include "jserror.h"
+#include "jsstring.h"
+#include "number.h"
+#include "resource.h"
+
+namespace lucent {
+
+class Handle {
+  struct State;
+
+ public:
+  /// The pointer, held for one call: a close meanwhile (from another
+  /// thread) destroys it when the call is done, never under it.
+  template <class T>
+  class Use {
+   public:
+    explicit Use(std::shared_ptr<State> state) : state_(std::move(state)) {}
+    Use(const Use&) = delete;
+    Use& operator=(const Use&) = delete;
+    ~Use() { state_->release(); }
+
+    T* get() const { return static_cast<T*>(state_->pointer); }
+
+   private:
+    std::shared_ptr<State> state_;
+  };
+
+  /// Empty: every use throws until a handle is assigned.
+  Handle() = default;
+
+  /// Owns `pointer` (never null); `destroy` takes it once, on `destroyOn`'s
+  /// thread when given. `what` names it in errors ("OrbitFilter is closed").
+  static Handle open(const char* what, void* pointer, void (*destroy)(void*), ExecutionContext* destroyOn = nullptr);
+
+  /// The pointer, for a call: throws InvalidStateError unless open.
+  template <class T>
+  Use<T> use() const {
+    acquire();
+    return Use<T>(state_);
+  }
+
+  /// The pointer, unheld (tests): throws InvalidStateError unless open.
+  template <class T>
+  T* get() const {
+    return use<T>().get();
+  }
+
+  /// Destroys the pointer now (or posts it to its context), or when the
+  /// calls using it are done. Idempotent.
+  void close() const;
+
+  /// The same handle: copies share one.
+  const void* identity() const { return state_.get(); }
+
+ private:
+  struct State {
+    void* pointer = nullptr;
+    void (*destroy)(void*) = nullptr;
+
+    std::mutex mutex;
+    int calls = 0;
+    bool deferred = false;
+
+    /// Last: destroyed first, so a backstop close still finds the fields above.
+    std::shared_ptr<Resource> resource;
+
+    /// The resource's release: destroys now, or leaves it to the last call.
+    void closing();
+    /// A call is done.
+    void release();
+  };
+
+  void acquire() const;
+
+  std::shared_ptr<State> state_;
+};
+
+inline bool strictEquals(const Handle& a, const Handle& b) { return a.identity() == b.identity(); }
+inline String toJsString(const Handle&) { return String::fromLatin1("[object Handle]"); }
+
+namespace ext {
+
+[[noreturn]] void outOfRange(const char* what, const std::string& low, const std::string& high, const std::string& value);
+
+/// A number as C integer type `I`: truncated toward zero; RangeError when
+/// it is not finite or outside `I`. `what` names the parameter.
+template <class I>
+  requires std::is_integral_v<I>
+I integer(double v, const char* what) {
+  using L = std::numeric_limits<I>;
+  double t = std::trunc(v);
+
+  if (!(t >= static_cast<double>(L::min()) && t <= static_cast<double>(L::max())) ||
+      (sizeof(I) == 8 && t == static_cast<double>(L::max())))
+    outOfRange(what, std::to_string(L::min()), std::to_string(L::max()), numberToString(v).toUtf8());
+
+  return static_cast<I>(t);
+}
+
+/// A bigint as C integer type `I`, exactly; RangeError outside `I`.
+template <class I>
+  requires std::is_integral_v<I>
+I integer(const BigInt& v, const char* what) {
+  using L = std::numeric_limits<I>;
+
+  if constexpr (std::is_signed_v<I>) {
+    auto x = v.tryInt64();
+    if (x && *x >= static_cast<int64_t>(L::min()) && *x <= static_cast<int64_t>(L::max())) return static_cast<I>(*x);
+  } else {
+    auto x = v.tryUint64();
+    if (x && *x <= static_cast<uint64_t>(L::max())) return static_cast<I>(*x);
+  }
+
+  outOfRange(what, std::to_string(L::min()), std::to_string(L::max()), v.toString().toUtf8());
+}
+
+/// A number as C floating type `F`, rounded as Math.fround does: infinite
+/// from halfway past float's largest value on (rather than undefined
+/// behavior), the largest below that.
+template <class F>
+  requires std::is_floating_point_v<F>
+F real(double v) {
+  using L = std::numeric_limits<F>;
+
+  if constexpr (sizeof(F) < sizeof(double)) {
+    // The largest plus half its gap to infinity: a tie, which rounds to even (infinity).
+    const double overflow = static_cast<double>(L::max()) + std::ldexp(1.0, L::max_exponent - L::digits - 1);
+
+    if (v >= overflow) return L::infinity();
+    if (v <= -overflow) return -L::infinity();
+  }
+
+  return static_cast<F>(v);
+}
+
+/// The bytes' data for a C pointer: never null, even for none.
+uint8_t* data(Bytes& bytes);
+
+/// A byte count as the C length type `I`; RangeError when it does not fit.
+template <class I>
+  requires std::is_integral_v<I>
+I length(size_t n, const char* what) {
+  if (n > static_cast<std::make_unsigned_t<I>>(std::numeric_limits<I>::max()))
+    throwError(String::fromLatin1("RangeError"),
+               String::fromUtf8(std::string(what) + " is " + std::to_string(n) + " bytes; at most " +
+                                std::to_string(std::numeric_limits<I>::max()) + " fit"));
+
+  return static_cast<I>(n);
+}
+
+/// A C integer result as a number (types of 32 bits or fewer: always exact).
+template <class I>
+  requires std::is_integral_v<I>
+double number(I v) {
+  static_assert(sizeof(I) <= 4, "64-bit C integers cross as bigints");
+  return static_cast<double>(v);
+}
+
+/// A C integer result as a bigint.
+template <class I>
+  requires std::is_integral_v<I>
+BigInt bigint(I v) {
+  if constexpr (std::is_signed_v<I>)
+    return BigInt::fromInt64(static_cast<int64_t>(v));
+  else
+    return BigInt::fromUint64(static_cast<uint64_t>(v));
+}
+
+/// Runs a call into C. An exception escaping it (a C++ implementation that
+/// did not catch) ends the process here instead of unwinding through Lucent
+/// and JSI frames that expect none.
+template <class F>
+decltype(auto) call(F&& f) noexcept {
+  return f();
+}
+
+/// A string argument: NUL-terminated UTF-8 (TypeError if it holds NUL).
+std::string utf8(const String& s, const char* what);
+
+/// Throws the Error a failed call reports: C's message (copied now; the
+/// function's name when it has none) and its code.
+[[noreturn]] void fail(const char* function, const char* message);
+[[noreturn]] void fail(const char* function, const char* message, long long code);
+
+}  // namespace ext
+}  // namespace lucent

package/runtime/cpp/lucent/helpers.h

@@ -19,10 +19,16 @@
 
 namespace lucent {
 
-/// `this` as a strong reference, inside a member function.
+/// `this` as a strong reference, inside a member function. An object a
+/// native object owns (a class extending an iOS class declares
+/// `lucentSelf`) is referenced through that native object.
 template <class T>
 Ref<T> selfRef(T* p) {
-  return std::static_pointer_cast<T>(static_cast<Object*>(p)->shared_from_this());
+  if constexpr (requires { lucentSelf(p); }) {
+    return lucentSelf(p);
+  } else {
+    return std::static_pointer_cast<T>(static_cast<Object*>(p)->shared_from_this());
+  }
 }
 template <class T>
 Ref<T> selfRef(const T* p) {
@@ -217,9 +223,10 @@ String toJsString(const std::tuple<Ts...>& t) {
       t);
   return out;
 }
-template <class... Ts>
-bool strictEquals(const std::tuple<Ts...>& a, const std::tuple<Ts...>& b) {
-  // Tuples are values in Lucent; compare element-wise.
+/// Tuples are values in Lucent: they compare element by element.
+template <class... As, class... Bs>
+  requires(sizeof...(As) == sizeof...(Bs))
+bool strictEquals(const std::tuple<As...>& a, const std::tuple<Bs...>& b) {
   return std::apply([&](const auto&... x) { return std::apply([&](const auto&... y) { return (strictEquals(x, y) && ...); }, b); }, a);
 }
 

package/runtime/cpp/lucent/items.h

@@ -0,0 +1,52 @@
+// Lucent runtime — a toolkit body's list, by key.
+//
+// A SwiftUI or Compose body shows an array its setup computes item by
+// item, each told apart by a key (a string or a number) its key function
+// computes. The setup's effect keeps the latest items by key, so an
+// action a callback of an item calls with the item's key runs with the
+// item itself, or not at all once the item is gone. Keys are unique:
+// two items with one key, or a NaN key, are an error.
+#pragma once
+
+#include <cmath>
+#include <map>
+#include <type_traits>
+
+#include "core.h"
+#include "jserror.h"
+#include "jsstring.h"
+#include "number.h"
+
+namespace lucent::ui {
+
+template <class K, class T>
+class Items {
+ public:
+  /// Forgets the items: a new array is being keyed.
+  void clear() { byKey_.clear(); }
+
+  /// Keeps `item` under `key`, which no other item has.
+  void add(const K& key, const T& item) {
+    if constexpr (std::is_same_v<K, double>) {
+      if (std::isnan(key)) throwError(String::fromLatin1("Error"), String::fromLatin1("a list's key is NaN"));
+    }
+
+    if (!byKey_.emplace(key, item).second)
+      throwError(String::fromLatin1("Error"), String::fromLatin1("two items of a list have the key ") + text(key));
+  }
+
+  /// The item with `key`, if there is one still.
+  Opt<T> find(const K& key) const {
+    auto it = byKey_.find(key);
+
+    return it == byKey_.end() ? Opt<T>() : Opt<T>(it->second);
+  }
+
+ private:
+  std::map<K, T> byKey_;
+
+  static String text(const String& key) { return key; }
+  static String text(double key) { return numberToString(key); }
+};
+
+}  // namespace lucent::ui

package/runtime/cpp/lucent/jserror.cpp

@@ -48,4 +48,13 @@ String errorToString(const Error& e) {
   return e->name + String::fromLatin1(": ") + e->message;
 }
 
+std::exception_ptr suppressedError(std::exception_ptr error, std::exception_ptr suppressed) {
+  auto e = std::make_shared<SuppressedErrorObject>();
+  e->name = String::fromLatin1("SuppressedError");
+  e->message = String::fromLatin1("An error was suppressed during disposal.");
+  e->error = currentError(error);
+  e->suppressed = currentError(suppressed);
+  return std::make_exception_ptr(Exception(e));
+}
+
 }  // namespace lucent