@lucent-lang/lucent 0.0.4 → 0.1.1

package/runtime/cpp/lucent/resource.h

@@ -0,0 +1,75 @@
+// Lucent runtime — resources: what Lucent code opens and must close once.
+//
+// A Resource holds the release of something native (a camera session, a
+// file, a subscription). It is open until it closes, closing while its
+// release runs, then closed. It closes at the first of an explicit
+// close(), the disposal of the scope it belongs to, or its last reference
+// going: finalization is a backstop, never the only way. Its release runs
+// exactly once, on the context the resource requires.
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+#include <functional>
+#include <memory>
+
+#include "execution.h"
+#include "jserror.h"
+#include "jsstring.h"
+#include "scope.h"
+
+namespace lucent {
+
+class Resource : public std::enable_shared_from_this<Resource> {
+ public:
+  enum class State : uint8_t { Open, Closing, Closed };
+
+  /// Opens a resource named `what` in its errors ("Camera is closed").
+  /// `release` runs once, when it closes: on `releaseOn`'s thread if given
+  /// (posted there from any other), else wherever it closes. With a
+  /// `scope`, disposing the scope closes the resource; the scope refers to
+  /// it weakly, so it never keeps the resource alive. Under a scope that is
+  /// no longer active, the resource is closed at once.
+  static std::shared_ptr<Resource> open(String what, std::function<void()> release, ExecutionContext* releaseOn = nullptr,
+                                        const std::shared_ptr<Scope>& scope = nullptr);
+
+  /// Closes it if still open (the backstop). An error from its release is
+  /// reported (reportUncaught).
+  ~Resource();
+
+  Resource(const Resource&) = delete;
+  Resource& operator=(const Resource&) = delete;
+
+  State state() const { return state_.load(std::memory_order_acquire); }
+
+  bool isOpen() const { return state() == State::Open; }
+
+  /// What every ordinary use checks first: throws InvalidStateError
+  /// "<what> is closed" unless the resource is open.
+  void check() const;
+
+  /// Any thread, idempotent. The first call closes the resource and
+  /// returns true; any other returns false at once, without waiting for a
+  /// release in progress. The resource is closed once its release has run,
+  /// even if the release throws: run here, its error reaches the caller;
+  /// posted, it is reported.
+  bool close();
+
+ private:
+  Resource(String what, std::function<void()> release, ExecutionContext* releaseOn);
+
+  /// Forgets the scope's cleanup, if it has not run.
+  void unlink();
+
+  const String what_;
+  ExecutionContext* const releaseOn_;
+
+  /// Taken by whichever closes the resource first.
+  std::function<void()> release_;
+  std::atomic<State> state_{State::Open};
+
+  std::weak_ptr<Scope> scope_;
+  std::atomic<Scope::CleanupId> cleanup_{0};
+};
+
+}  // namespace lucent

package/runtime/cpp/lucent/scheduler.cpp

@@ -1,153 +1,67 @@
 #include "scheduler.h"
 
-#include <cstdio>
-#include <exception>
-#include <string>
-
-#if defined(__ANDROID__)
-#include <android/log.h>
-#elif defined(__APPLE__)
-#include <os/log.h>
-#endif
-
 namespace lucent {
 
-namespace {
-/// Where each platform shows an app's errors: logcat, the unified log, and
-/// stderr (host runs; Android and release iOS apps drop it).
-void writeError(const std::string& message) {
-#if defined(__ANDROID__)
-  __android_log_write(ANDROID_LOG_ERROR, "Lucent", message.c_str());
-#elif defined(__APPLE__)
-  os_log_error(OS_LOG_DEFAULT, "%{public}s", message.c_str());
-#endif
-  std::fprintf(stderr, "%s\n", message.c_str());
-}
-}  // namespace
-
-void logError(const char* message) { writeError(message); }
+Scheduler::Scheduler() : ExecutionContext(&microtaskCount_) {
+  // The module context starts with the first module: tracing asked for by
+  // the environment (LUCENT_TRACE) starts with it.
+  trace::startFromEnvironment();
 
-void reportUncaught(std::exception_ptr e, const char* where) {
-  try {
-    std::rethrow_exception(e);
-  } catch (const std::exception& x) {
-    writeError(std::string("[lucent] uncaught exception in ") + where + ": " + x.what());
-  } catch (...) {
-    writeError(std::string("[lucent] uncaught exception in ") + where);
-  }
+  worker_ = WorkerThread::start([this](Job& job) { runTurn(job); });
 }
 
 namespace {
-void runGuarded(const Scheduler::Job& job) {
-  try {
-    job();
-  } catch (...) {
-    reportUncaught(std::current_exception(), "job");
-  }
-}
+/// The scheduler's owner, leaked on purpose (jobs may still reference the
+/// scheduler during static destruction at process exit), and kept
+/// reachable: a leak checker (LeakSanitizer) reports what it cannot reach.
+std::shared_ptr<Scheduler>* keptScheduler = nullptr;
 }  // namespace
 
-
-Scheduler::Scheduler() {
-  thread_ = std::thread([this] { run(); });
-  threadId_ = thread_.get_id();
+Scheduler& Scheduler::instance() {
+  // The scheduler itself, one load away on the call path.
+  static Scheduler* s = [] {
+    keptScheduler = new std::shared_ptr<Scheduler>(new Scheduler());
+    (*keptScheduler)->makeRoot();
+    return keptScheduler->get();
+  }();
+  return *s;
 }
 
-Scheduler::~Scheduler() {
-  {
-    std::lock_guard<std::mutex> g(queueMutex_);
-    stopping_ = true;
+void Scheduler::runTurn(Job& job) {
+  if (trace::enabled()) [[unlikely]] {
+    LucentScope::lockTraced(lock_);
+  } else {
+    lock_.lock();
   }
-  cv_.notify_all();
-  if (thread_.joinable()) thread_.join();
-}
 
-void Scheduler::post(Job job) {
-  {
-    std::lock_guard<std::mutex> g(queueMutex_);
-    jobs_.push_back(std::move(job));
-  }
-  cv_.notify_one();
-}
+  std::lock_guard<LucentLock> lucent(lock_, std::adopt_lock);
 
-void Scheduler::postDelayed(double ms, Job job) {
-  if (!(ms > 0)) ms = 0;
-  auto at = std::chrono::steady_clock::now() + std::chrono::microseconds(static_cast<int64_t>(ms * 1000));
   {
-    std::lock_guard<std::mutex> g(queueMutex_);
-    timers_.push(Timer{at, timerSeq_++, std::move(job)});
+    Job local = std::move(job);
+    detail::runGuarded(local, "job");
   }
-  cv_.notify_one();
-}
 
-void Scheduler::enqueueMicrotask(Job job) {
-  microtasks_.push_back(std::move(job));
-  pendingMicrotasks_++;
+  drainMicrotasks();
 }
 
-void Scheduler::drainMicrotasks() {
-  while (!microtasks_.empty()) {
-    Job job = std::move(microtasks_.front());
-    microtasks_.pop_front();
-    pendingMicrotasks_--;
-    runGuarded(job);
+void LucentScope::lockTraced(LucentLock& lock) {
+  // Already held here (a nested call): no wait to record.
+  if (lock.heldByCurrentThread()) {
+    lock.lock();
+    return;
   }
-}
-
-size_t Scheduler::pendingWork() {
-  std::lock_guard<std::mutex> g(queueMutex_);
-  return jobs_.size() + timers_.size() + running_;
-}
 
-bool Scheduler::waitIdle(double timeoutMs) {
-  std::unique_lock<std::mutex> g(queueMutex_);
-  return idleCv_.wait_for(g, std::chrono::microseconds(static_cast<int64_t>(timeoutMs * 1000)),
-                          [this] { return jobs_.empty() && timers_.empty() && running_ == 0; });
-}
-
-void Scheduler::run() {
-  std::unique_lock<std::mutex> g(queueMutex_);
-  for (;;) {
-    if (stopping_) return;
-    auto now = std::chrono::steady_clock::now();
-    while (!timers_.empty() && timers_.top().at <= now) {
-      jobs_.push_back(std::move(const_cast<Timer&>(timers_.top()).job));
-      timers_.pop();
-    }
-    if (!jobs_.empty()) {
-      Job job = std::move(jobs_.front());
-      jobs_.pop_front();
-      running_++;
-      g.unlock();
-      {
-        std::lock_guard<LucentLock> lucent(lock_);
-        runGuarded(job);
-        drainMicrotasks();
-      }
-      g.lock();
-      running_--;
-      if (jobs_.empty() && timers_.empty() && running_ == 0) idleCv_.notify_all();
-      continue;
-    }
-    if (timers_.empty()) {
-      cv_.wait(g);
-    } else {
-      // A copy: wait_until reads the deadline after unlocking, when a
-      // postDelayed may have reallocated the heap.
-      const auto deadline = timers_.top().at;
-      cv_.wait_until(g, deadline);
-    }
-  }
+  trace::Mark wait = trace::begin(trace::Category::Lock, "lucent-lock");
+  lock.lock();
+  trace::end(wait, trace::Category::Lock, "lucent-lock", {.parent = trace::currentId()});
 }
 
 void LucentScope::handOffMicrotasks() {
   Scheduler& s = Scheduler::instance();
-  if (s.onLucentThread()) {
-    s.drainMicrotasks();
-  } else {
-    // Continuations run on the Lucent thread, never on the JS thread.
-    s.post([] {});
-  }
+
+  // Continuations run on the Lucent thread, never on the JS thread. There,
+  // the turn this scope is nested in runs them after its job.
+  if (!s.onLucentThread()) s.post([] {});
 }
 
 }  // namespace lucent

package/runtime/cpp/lucent/scheduler.h

@@ -1,160 +1,179 @@
-// Lucent runtime — execution model.
+// Lucent runtime — the legacy module context.
 //
-// Lucent code runs one piece at a time, like JavaScript: every entry into
-// Lucent code (a synchronous call from the JS thread, or a job on the Lucent
-// thread) holds the Lucent lock. Async functions run on the Lucent thread and
-// interleave only at `await`, so Lucent code never races with itself.
+// Module code runs one piece at a time, like JavaScript: every entry into it
+// (a synchronous call from the JS thread, or a job on the Lucent thread)
+// holds the Lucent lock. Async functions run on the Lucent thread and
+// interleave only at `await`, so module code never races with itself.
 //
-// Invariant: the Lucent thread never waits for the JS thread, so the JS
-// thread may always block on the Lucent lock without deadlocking.
+// Invariant: code holding the Lucent lock never waits for another thread,
+// so any thread may block on the lock without deadlocking. The main context
+// and isolated contexts (execution.h) never take it.
 #pragma once
 
 #include <atomic>
-#include <chrono>
-#include <condition_variable>
 #include <cstdint>
-#include <deque>
-#include <exception>
-#include <functional>
+#include <memory>
 #include <mutex>
-#include <queue>
 #include <thread>
-#include <vector>
 
-namespace lucent {
+#include "execution.h"
+#include "report.h"
+#include "trace.h"
 
-/// The one place errors no Lucent code can catch are reported: thrown by a
-/// job, or by a callback the platform made.
-void reportUncaught(std::exception_ptr e, const char* where);
-/// Logs an error where the platform shows an app's errors (logcat, the
-/// unified log) and to stderr.
-void logError(const char* message);
+namespace lucent {
 
 /// The Lucent lock: recursive, as a Lucent call may call back into
 /// JavaScript that calls Lucent again. Every synchronous call from
-/// JavaScript takes it, so the uncontended path is one compare-and-swap;
-/// std::recursive_mutex (a pthread mutex) cost a third of a call. Waiters
+/// JavaScript takes it, so the uncontended path is one atomic increment
+/// and a load; std::recursive_mutex (a pthread mutex) cost a third of a
+/// call.
+///
+/// It is fair: a ticket lock, serving threads in the order they asked. A
+/// thread that releases it and asks again (the Lucent thread between the
+/// turns of a loop that yields) queues behind the threads already waiting,
+/// so a waiter gets in within one turn per thread ahead of it. Waiters
 /// block in atomic::wait (a futex, or __ulock on Apple platforms).
 class LucentLock {
  public:
   void lock() {
     std::thread::id self = std::this_thread::get_id();
+
     // Only this thread stores its own id, so a relaxed read that sees it is
     // exact; any other value means another owner or none.
     if (owner_.load(std::memory_order_relaxed) == self) {
       depth_++;
       return;
     }
-    uint32_t c = kFree;
-    if (!state_.compare_exchange_strong(c, kLocked, std::memory_order_acquire, std::memory_order_relaxed)) {
-      if (c != kContended) c = state_.exchange(kContended, std::memory_order_acquire);
-      while (c != kFree) {
-        state_.wait(kContended, std::memory_order_relaxed);
-        c = state_.exchange(kContended, std::memory_order_acquire);
-      }
+
+    // Sequentially consistent, with unlock(): either it sees this ticket
+    // and wakes the waiters, or this thread sees the ticket it serves.
+    const uint32_t ticket = next_.fetch_add(1, std::memory_order_seq_cst);
+
+    uint32_t serving = serving_.load(std::memory_order_seq_cst);
+    while (serving != ticket) {
+      serving_.wait(serving, std::memory_order_relaxed);
+      serving = serving_.load(std::memory_order_seq_cst);
     }
+
     owner_.store(self, std::memory_order_relaxed);
     depth_ = 1;
   }
 
   bool try_lock() {
     std::thread::id self = std::this_thread::get_id();
+
     if (owner_.load(std::memory_order_relaxed) == self) {
       depth_++;
       return true;
     }
-    uint32_t c = kFree;
-    if (!state_.compare_exchange_strong(c, kLocked, std::memory_order_acquire, std::memory_order_relaxed)) return false;
+
+    // Free is no ticket handed out beyond the one served: take that one.
+    uint32_t serving = serving_.load(std::memory_order_seq_cst);
+    uint32_t expected = serving;
+    if (!next_.compare_exchange_strong(expected, serving + 1, std::memory_order_seq_cst, std::memory_order_relaxed)) {
+      return false;
+    }
+
     owner_.store(self, std::memory_order_relaxed);
     depth_ = 1;
     return true;
   }
 
+  /// Whether the calling thread holds the lock.
+  bool heldByCurrentThread() const { return owner_.load(std::memory_order_relaxed) == std::this_thread::get_id(); }
+
   void unlock() {
     if (--depth_ > 0) return;
+
     owner_.store(std::thread::id(), std::memory_order_relaxed);
-    if (state_.exchange(kFree, std::memory_order_release) == kContended) state_.notify_one();
+
+    // Only the owner moves `serving_`, so it may read it relaxed.
+    const uint32_t next = serving_.load(std::memory_order_relaxed) + 1;
+    serving_.store(next, std::memory_order_seq_cst);
+
+    // A ticket beyond the one now served: someone waits. Every waiter
+    // wakes, and the one holding `next` goes in.
+    if (next_.load(std::memory_order_seq_cst) != next) serving_.notify_all();
   }
 
  private:
-  static constexpr uint32_t kFree = 0, kLocked = 1, kContended = 2;
-  std::atomic<uint32_t> state_{kFree};
+  /// The next ticket to hand out, and the one that holds the lock (or may
+  /// take it). Equal: free.
+  std::atomic<uint32_t> next_{0};
+  std::atomic<uint32_t> serving_{0};
+
   std::atomic<std::thread::id> owner_{};
   unsigned depth_ = 0;
 };
 
-class Scheduler {
+/// The legacy module context: every module's code, serialized by the Lucent
+/// lock. Its turns run on the Lucent thread; synchronous calls from other
+/// threads (JavaScript's, or a platform callback's) enter it by taking the
+/// lock, which is what makes it current (ExecutionContext::current).
+class Scheduler final : public ExecutionContext {
  public:
-  using Job = std::function<void()>;
-
-  static Scheduler& instance() {
-    // Leaked on purpose: jobs may still reference the scheduler during
-    // static destruction at process exit.
-    static Scheduler* s = new Scheduler();
-    return *s;
-  }
+  static Scheduler& instance();
 
-  /// Static, like the pending count: a call from JavaScript reaches both
+  /// Static, like microtasksPending(): a call from JavaScript reaches both
   /// without the scheduler's function-local static.
   static LucentLock& lock() { return lock_; }
 
-  /// Runs `job` on the Lucent thread, holding the lock, then drains
-  /// microtasks.
-  void post(Job job);
-  void postDelayed(double ms, Job job);
-  /// Queues a promise continuation. Callers hold the lock.
-  void enqueueMicrotask(Job job);
-  /// Runs queued microtasks. Callers hold the lock.
-  void drainMicrotasks();
-  static bool hasMicrotasks() { return pendingMicrotasks_ > 0; }
-
-  bool onLucentThread() const { return std::this_thread::get_id() == threadId_; }
+  /// Whether microtasks are queued here. Callers hold the lock.
+  static bool microtasksPending() { return microtaskCount_ > 0; }
+
+  bool onLucentThread() const { return worker_->isCurrent(); }
+
   /// Jobs queued or running, and timers pending (for tests and shutdown).
-  size_t pendingWork();
+  size_t pendingWork() { return worker_->pendingWork(); }
+
   /// Blocks until no jobs or timers are pending, or the timeout elapses.
-  bool waitIdle(double timeoutMs);
+  bool waitIdle(double timeoutMs) { return worker_->waitIdle(timeoutMs); }
 
  private:
   Scheduler();
-  ~Scheduler();
-  void run();
 
-  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; }
-  };
+  bool dispatch(Job job) override { return worker_->post(std::move(job)); }
+  bool dispatchDelayed(double ms, Job job) override { return worker_->postDelayed(ms, std::move(job)); }
+  bool onExecutor() const override { return worker_->isCurrent(); }
+
+  /// Holds the lock for the job and the microtasks after it.
+  void runTurn(Job& job) override;
 
   static inline LucentLock lock_;
-  std::mutex queueMutex_;
-  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;
-  std::deque<Job> microtasks_;
-  static inline size_t pendingMicrotasks_ = 0;  // microtasks_.size(), under the lock
-  bool stopping_ = false;
-  std::thread thread_;
-  std::thread::id threadId_;
+  /// Guarded by the lock.
+  static inline size_t microtaskCount_ = 0;
+  std::shared_ptr<WorkerThread> worker_;
 };
 
-/// Entered for every call from JavaScript into Lucent code. Holds the Lucent
-/// lock; on exit, hands pending microtasks to the Lucent thread.
+/// Entered for every call from JavaScript into Lucent code, and by platform
+/// callbacks into module code (callNow): enters the legacy module context
+/// by holding the Lucent lock. On exit off the Lucent thread, hands pending
+/// microtasks to it; on the Lucent thread, the enclosing turn runs them once
+/// its stack is empty.
 class LucentScope {
  public:
-  LucentScope() : guard_(Scheduler::lock()) {}
+  LucentScope() {
+    if (trace::enabled()) [[unlikely]] {
+      lockTraced(Scheduler::lock());
+    } else {
+      Scheduler::lock().lock();
+    }
+  }
+
   ~LucentScope() {
-    if (Scheduler::hasMicrotasks()) handOffMicrotasks();
+    if (Scheduler::microtasksPending()) handOffMicrotasks();
+
+    Scheduler::lock().unlock();
   }
+
   LucentScope(const LucentScope&) = delete;
   LucentScope& operator=(const LucentScope&) = delete;
 
+  /// Takes `lock`, recording the wait as a span (a call's, or a turn's).
+  static void lockTraced(LucentLock& lock);
+
  private:
   static void handOffMicrotasks();
-  std::unique_lock<LucentLock> guard_;
 };
 
 }  // namespace lucent