@lucent-lang/lucent 0.0.4 → 0.1.1

package/runtime/cpp/lucent/jserror.h

@@ -26,6 +26,13 @@ struct ErrorObject : Object {
 };
 using Error = Ref<ErrorObject>;
 
+/// What a `using` declaration throws when disposing fails while an error is
+/// pending: JavaScript's SuppressedError, with both.
+struct SuppressedErrorObject : ErrorObject {
+  Error error;
+  Error suppressed;
+};
+
 Error makeError(const String& name, const String& message);
 inline Error makeError(const String& message) { return makeError(String::fromLatin1("Error"), message); }
 
@@ -63,4 +70,8 @@ Error currentError(std::exception_ptr ex);
 
 String errorToString(const Error& e);
 
+/// A SuppressedError of `error` (thrown while disposing) and `suppressed` (the
+/// error pending then), as an exception to rethrow.
+std::exception_ptr suppressedError(std::exception_ptr error, std::exception_ptr suppressed);
+
 }  // namespace lucent

package/runtime/cpp/lucent/jsi/convert.cpp

@@ -27,6 +27,28 @@ void throwBoundaryError(jsi::Runtime& rt, const Path& path, const char* expected
   throw jsi::JSError(rt, jsi::Value(rt, err));
 }
 
+BigInt Convert<BigInt>::fromJs(jsi::Runtime& rt, const jsi::Value& v, const Path& p) {
+  if (!v.isBigInt()) throwBoundaryError(rt, p, "a bigint", v);
+
+  jsi::BigInt b = v.getBigInt(rt);
+
+  if (b.isInt64(rt)) return BigInt::fromInt64(b.getInt64(rt));
+  if (b.isUint64(rt)) return BigInt::fromUint64(b.getUint64(rt));
+
+  // Beyond 64 bits: its hex digits, after a "-" when negative.
+  return BigInt::fromDigits(b.toString(rt, 16).utf8(rt), 16);
+}
+
+jsi::Value Convert<BigInt>::toJs(jsi::Runtime& rt, Host&, const BigInt& v) {
+  if (auto i = v.tryInt64()) return jsi::Value(jsi::BigInt::fromInt64(rt, *i));
+  if (auto u = v.tryUint64()) return jsi::Value(jsi::BigInt::fromUint64(rt, *u));
+
+  // Beyond 64 bits: BigInt(string) builds it. Decimal, since BigInt()
+  // takes no sign before a 0x prefix.
+  jsi::Function make = rt.global().getPropertyAsFunction(rt, "BigInt");
+  return make.call(rt, jsi::String::createFromAscii(rt, v.toString().toUtf8()));
+}
+
 String stringFromJs(jsi::Runtime& rt, const jsi::String& s) {
   // Hermes hands most strings over in one chunk: an ASCII one becomes the
   // String directly (inline when short). Later chunks go to the accumulator.
@@ -100,6 +122,23 @@ class OwnedBuffer : public jsi::MutableBuffer {
  private:
   std::vector<uint8_t> data_;
 };
+
+/// Bytes no Lucent code holds (a fresh copy), lent to an ArrayBuffer as they are.
+class FreshBytes : public jsi::MutableBuffer {
+ public:
+  explicit FreshBytes(Bytes bytes) : bytes_(std::move(bytes)) {}
+  size_t size() const override { return bytes_.size(); }
+  uint8_t* data() override { return bytes_.data(); }
+  const Bytes& bytes() const { return bytes_; }
+
+ private:
+  Bytes bytes_;
+};
+
+jsi::Value uint8ArrayOver(jsi::Runtime& rt, const std::shared_ptr<FreshBytes>& bytes) {
+  jsi::ArrayBuffer ab(rt, bytes);
+  return rt.global().getPropertyAsFunction(rt, "Uint8Array").callAsConstructor(rt, ab);
+}
 }  // namespace
 
 Bytes Convert<Bytes>::fromJs(jsi::Runtime& rt, const jsi::Value& v, const Path& p) {
@@ -122,6 +161,105 @@ jsi::Value Convert<Bytes>::toJs(jsi::Runtime& rt, Host&, const Bytes& b) {
   return rt.global().getPropertyAsFunction(rt, "Uint8Array").callAsConstructor(rt, ab);
 }
 
+namespace {
+const char* const kBufferPrototype = "lucent:NativeBuffer";
+
+NativeBuffer bufferThis(jsi::Runtime& rt, const jsi::Value& self, const char* method) {
+  return Convert<NativeBuffer>::fromJs(rt, self, Path{method, "this"});
+}
+
+jsi::Function callbackArg(jsi::Runtime& rt, const jsi::Value* args, size_t count, const char* method) {
+  const jsi::Value& f = arg(args, count, 0);
+  if (!f.isObject() || !f.getObject(rt).isFunction(rt)) throwBoundaryError(rt, Path{method, "argument 0"}, "a function", f);
+
+  return f.getObject(rt).getFunction(rt);
+}
+
+/// A method of the handle, calling `body(rt, host, buffer, args, count)`.
+template <class F>
+jsi::Function bufferMethod(jsi::Runtime& rt, const char* name, unsigned argc, F body) {
+  return jsi::Function::createFromHostFunction(
+      rt, jsi::PropNameID::forAscii(rt, name), argc,
+      [name, body](jsi::Runtime& rt, const jsi::Value& self, const jsi::Value* args, size_t count) -> jsi::Value {
+        Host& host = Host::get(rt);
+        return callSync(rt, host, [&] { return body(rt, host, bufferThis(rt, self, name), args, count); });
+      });
+}
+
+void bufferPrototype(jsi::Runtime& rt, Host&, jsi::Object& proto) {
+  defineAccessor(
+      rt, proto, "byteLength",
+      [](jsi::Runtime& rt, const jsi::Value& self, const jsi::Value*, size_t) {
+        return jsi::Value(static_cast<double>(bufferThis(rt, self, "NativeBuffer.byteLength")->size()));
+      },
+      nullptr);
+
+  proto.setProperty(rt, "toUint8Array",
+                    bufferMethod(rt, "toUint8Array", 0, [](jsi::Runtime& rt, Host&, const NativeBuffer& b, const jsi::Value*, size_t) {
+                      return uint8ArrayOver(rt, std::make_shared<FreshBytes>(b->toBytes()));
+                    }));
+
+  proto.setProperty(rt, "withRead",
+                    bufferMethod(rt, "withRead", 1, [](jsi::Runtime& rt, Host&, const NativeBuffer& b, const jsi::Value* args, size_t count) {
+                      jsi::Function read = callbackArg(rt, args, count, "withRead");
+
+                      return b->withRead([&](std::span<const uint8_t> bytes) {
+                        return read.call(rt, uint8ArrayOver(rt, std::make_shared<FreshBytes>(NativeBufferObject::copyOut(bytes))));
+                      });
+                    }));
+
+  proto.setProperty(rt, "withWrite",
+                    bufferMethod(rt, "withWrite", 1, [](jsi::Runtime& rt, Host&, const NativeBuffer& b, const jsi::Value* args, size_t count) {
+                      jsi::Function write = callbackArg(rt, args, count, "withWrite");
+
+                      return b->withWrite([&](std::span<uint8_t> bytes) {
+                        auto lent = std::make_shared<FreshBytes>(NativeBufferObject::copyOut(bytes));
+
+                        // What the callback wrote comes back, even if it then threw.
+                        struct CopyBack {
+                          std::span<uint8_t> to;
+                          const FreshBytes& from;
+                          ~CopyBack() { NativeBufferObject::copyIn(to, from.bytes()); }
+                        } back{bytes, *lent};
+
+                        return write.call(rt, uint8ArrayOver(rt, lent));
+                      });
+                    }));
+
+  proto.setProperty(rt, "transfer",
+                    bufferMethod(rt, "transfer", 0, [](jsi::Runtime& rt, Host& host, const NativeBuffer& b, const jsi::Value*, size_t) {
+                      return Convert<NativeBuffer>::toJs(rt, host, b->transfer());
+                    }));
+
+  jsi::Function close = bufferMethod(rt, "close", 0, [](jsi::Runtime&, Host&, const NativeBuffer& b, const jsi::Value*, size_t) {
+    b->close();
+    return jsi::Value::undefined();
+  });
+
+  // `using` in JavaScript, where the runtime has Symbol.dispose.
+  jsi::Value dispose = rt.global().getPropertyAsObject(rt, "Symbol").getProperty(rt, "dispose");
+  if (dispose.isSymbol()) {
+    jsi::Object descriptor(rt);
+    descriptor.setProperty(rt, "value", jsi::Value(rt, close));
+    descriptor.setProperty(rt, "configurable", true);
+    descriptor.setProperty(rt, "writable", true);
+    rt.global().getPropertyAsObject(rt, "Object").getPropertyAsFunction(rt, "defineProperty").call(rt, proto, dispose, descriptor);
+  }
+
+  proto.setProperty(rt, "close", std::move(close));
+}
+}  // namespace
+
+NativeBuffer Convert<NativeBuffer>::fromJs(jsi::Runtime& rt, const jsi::Value& v, const Path& p) {
+  if (auto b = std::dynamic_pointer_cast<NativeBufferObject>(instanceOf(rt, v))) return b;
+
+  throwBoundaryError(rt, p, "a NativeBuffer", v);
+}
+
+jsi::Value Convert<NativeBuffer>::toJs(jsi::Runtime& rt, Host& h, const NativeBuffer& b) {
+  return h.wrap(rt, b, kBufferPrototype, bufferPrototype);
+}
+
 Error Convert<Error>::fromJs(jsi::Runtime& rt, const jsi::Value& v, const Path&) {
   Error e = makeError(String::fromLatin1("Error"), String());
   if (v.isObject()) {

package/runtime/cpp/lucent/jsi/convert.h

@@ -11,10 +11,12 @@
 
 #include <jsi/jsi.h>
 
+#include <optional>
 #include <string>
 #include <vector>
 
 #include "../lucent.h"
+#include "../trace.h"
 #include "host.h"
 
 namespace lucent::js {
@@ -109,6 +111,15 @@ struct Convert<String> {
   static jsi::Value toJs(jsi::Runtime& rt, Host&, const String& v) { return jsi::Value(stringToJs(rt, v)); }
 };
 
+/// Bigints cross exactly: through jsi::BigInt's 64-bit forms when the value
+/// fits (no string, no allocation on the Lucent side), else through its
+/// digits, and the JS side's global BigInt for the value it gets.
+template <>
+struct Convert<BigInt> {
+  static BigInt fromJs(jsi::Runtime& rt, const jsi::Value& v, const Path& p);
+  static jsi::Value toJs(jsi::Runtime& rt, Host& h, const BigInt& v);
+};
+
 template <>
 struct Convert<Undefined> {
   static Undefined fromJs(jsi::Runtime& rt, const jsi::Value& v, const Path& p) {
@@ -287,6 +298,20 @@ struct Convert<Bytes> {
   static jsi::Value toJs(jsi::Runtime& rt, Host& h, const Bytes& b);
 };
 
+// --- native buffers ------------------------------------------------------------------------
+
+/// A NativeBuffer crosses as an opaque handle, the same JS object for the
+/// same buffer while JavaScript holds it. Its methods mirror lucent:core's:
+/// `byteLength`, `toUint8Array()`, `withRead(f)`, `withWrite(f)`,
+/// `transfer()`, `close()`. JavaScript never gets an ArrayBuffer over the
+/// storage: a borrow lends it a copy (a write borrow copies it back when
+/// the callback returns), counted in the buffer stats.
+template <>
+struct Convert<NativeBuffer> {
+  static NativeBuffer fromJs(jsi::Runtime& rt, const jsi::Value& v, const Path& p);
+  static jsi::Value toJs(jsi::Runtime& rt, Host& h, const NativeBuffer& b);
+};
+
 // --- errors ------------------------------------------------------------------------------
 
 template <>
@@ -338,6 +363,50 @@ struct Convert<AbortSignal> {
 
 // --- promises ------------------------------------------------------------------------------
 
+/// Settles `host`'s JS promise `id` like `p`, once `p` settles: on the JS
+/// thread, where its value converts. If the host is torn down first, the
+/// value is released on the legacy module context instead.
+/// Traced (`traceId`), the result's wait for the JS thread and its
+/// delivery are spans of that id, the delivery named after `site`.
+template <class T>
+void settleLater(Host& host, uint64_t id, const Promise<T>& p, uint64_t traceId = 0, const trace::Site* site = nullptr) {
+  std::weak_ptr<Host> weak = host.weak_from_this();
+
+  p.onSettled([p, weak, id, traceId, site] {
+    auto host = weak.lock();
+    if (!host) return;
+
+    trace::Mark wait = traceId ? trace::begin(trace::Category::Queue, "js.wait") : trace::Mark{};
+
+    host->postToJs([p, id, weak, traceId, site, wait](jsi::Runtime& rt) {
+      auto host = weak.lock();
+      if (!host) return;
+
+      trace::end(wait, trace::Category::Queue, "js.wait", {.id = traceId});
+      std::optional<trace::Scope> delivery;
+      if (traceId) delivery.emplace(trace::Category::Completion, site ? site->name : "completion", site, traceId);
+
+      LucentScope scope;
+      if (!p.fulfilled()) {
+        host->reject(rt, id, host->errorToJs(rt, p.error()));
+        return;
+      }
+
+      jsi::Value value = jsi::Value::undefined();
+      if constexpr (!std::is_void_v<T>) {
+        try {
+          value = Convert<T>::toJs(rt, *host, p.value());
+        } catch (const jsi::JSError& e) {
+          host->reject(rt, id, jsi::Value(rt, e.value()));
+          return;
+        }
+      }
+
+      host->resolve(rt, id, value);
+    });
+  });
+}
+
 /// Hands a Lucent promise to JavaScript: the JS promise settles on the JS
 /// thread when the Lucent one does.
 template <class T>
@@ -345,32 +414,7 @@ struct Convert<Promise<T>> {
   static jsi::Value toJs(jsi::Runtime& rt, Host& h, const Promise<T>& p) {
     uint64_t id = 0;
     jsi::Value jsPromise = h.createPromise(rt, id);
-    std::weak_ptr<Host> weak = h.weak_from_this();
-    p.onSettled([p, weak, id] {
-      auto host = weak.lock();
-      if (!host) return;
-      host->postToJs([p, id, weak](jsi::Runtime& rt) {
-        auto host = weak.lock();
-        if (!host) return;
-        LucentScope scope;
-        if (p.fulfilled()) {
-          jsi::Value value = jsi::Value::undefined();
-          try {
-            if constexpr (std::is_void_v<T>) {
-              value = jsi::Value::undefined();
-            } else {
-              value = Convert<T>::toJs(rt, *host, p.value());
-            }
-          } catch (const jsi::JSError& e) {
-            host->reject(rt, id, jsi::Value(rt, e.value()));
-            return;
-          }
-          host->resolve(rt, id, value);
-        } else {
-          host->reject(rt, id, host->errorToJs(rt, p.error()));
-        }
-      });
-    });
+    settleLater(h, id, p);
     return jsPromise;
   }
   /// A JS promise passed into Lucent (e.g. returned by a callback).
@@ -415,7 +459,7 @@ struct Convert<Fn<R(A...)>> {
     auto host = cb->host();
     if (!host || !host->alive()) {
       if constexpr (std::is_void_v<R>) return;
-      else throwError(String::fromLatin1("Error"), String::fromLatin1("The JavaScript runtime is gone"));
+      else throwError(Host::goneError());
     }
     if (host->onJsThread()) {
       jsi::Runtime& rt = host->runtime();
@@ -450,6 +494,8 @@ struct Convert<Fn<R(A...)>> {
       return;
     } else if constexpr (IsPromiseType<R>::value) {
       R out;
+      // If the task never runs (the runtime went), the promise rejects.
+      auto gone = [out] { out.reject(Host::goneError()); };
       host->postToJs([cb, out, where, args...](jsi::Runtime& rt) mutable {
         auto host = cb->host();
         jsi::Function* fn = host ? host->retained(cb->id()) : nullptr;
@@ -474,7 +520,7 @@ struct Convert<Fn<R(A...)>> {
         } catch (const Exception& e) {
           out.reject(e.error());
         }
-      });
+      }, gone);
       return out;
     } else {
       throwError(String::fromLatin1("Error"),
@@ -487,13 +533,14 @@ struct Convert<Fn<R(A...)>> {
     return jsi::Function::createFromHostFunction(
         rt, jsi::PropNameID::forAscii(rt, "lucentFunction"), sizeof...(A),
         [f, weak](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
-          auto host = weak.lock();
-          if (!host) throw jsi::JSError(rt, "Lucent host is gone");
+          // A torn-down host's function answers through the runtime's host.
+          auto kept = weak.lock();
+          Host& host = kept && kept->alive() ? *kept : Host::get(rt);
           LucentScope scope;
           try {
-            return call(rt, *host, f, args, count, std::index_sequence_for<A...>{});
+            return call(rt, host, f, args, count, std::index_sequence_for<A...>{});
           } catch (const Exception& e) {
-            throw jsi::JSError(rt, host->errorToJs(rt, e.error()));
+            throw jsi::JSError(rt, host.errorToJs(rt, e.error()));
           }
         });
   }
@@ -521,10 +568,22 @@ Promise<T> Convert<Promise<T>>::fromJs(jsi::Runtime& rt, const jsi::Value& v, co
     else out.resolve(Convert<T>::fromJs(rt, v, p));
     return out;
   }
+
+  // Rejected if the runtime's host is torn down before JavaScript settles
+  // it, so what awaits it goes on (and releases what it holds).
+  const std::shared_ptr<Scope>& scope = Host::get(rt).scope();
+  Scope::CleanupId pending = scope->onDispose([out] { out.reject(Host::goneError()); });
+  if (pending == 0) return out;
+
+  auto settled = [owner = std::weak_ptr<Scope>(scope), pending] {
+    if (auto s = owner.lock()) s->remove(pending);
+  };
+
   std::string where = std::string(p.fn) + " " + p.where();
   auto onFulfilled = jsi::Function::createFromHostFunction(
       rt, jsi::PropNameID::forAscii(rt, "onFulfilled"), 1,
-      [out, where](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+      [out, where, settled](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        settled();
         LucentScope scope;
         try {
           if constexpr (std::is_void_v<T>) out.resolve(undefined);
@@ -536,7 +595,8 @@ Promise<T> Convert<Promise<T>>::fromJs(jsi::Runtime& rt, const jsi::Value& v, co
       });
   auto onRejected = jsi::Function::createFromHostFunction(
       rt, jsi::PropNameID::forAscii(rt, "onRejected"), 1,
-      [out](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+      [out, settled](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) -> jsi::Value {
+        settled();
         LucentScope scope;
         out.reject(Convert<Error>::fromJs(rt, arg(args, count, 0), Path{"promise", "rejection"}));
         return jsi::Value::undefined();
@@ -551,6 +611,17 @@ Promise<T> Convert<Promise<T>>::fromJs(jsi::Runtime& rt, const jsi::Value& v, co
 
 /// Runs a synchronous Lucent call from JS, translating Lucent errors into
 /// JS exceptions.
+template <class F>
+jsi::Value callSync(jsi::Runtime& rt, Host& host, F&& body);
+
+/// A synchronous call from JS, traced as an entry at the export's site
+/// (the compiler passes it: LUCENT_TRACE_SITE_AT).
+template <class F>
+jsi::Value callSync(jsi::Runtime& rt, Host& host, const trace::Site* site, F&& body) {
+  trace::Scope entry(trace::Category::Entry, site->name, site);
+  return callSync(rt, host, std::forward<F>(body));
+}
+
 template <class F>
 jsi::Value callSync(jsi::Runtime& rt, Host& host, F&& body) {
   LucentScope scope;
@@ -569,43 +640,41 @@ jsi::Value callSync(jsi::Runtime& rt, Host& host, F&& body) {
 
 /// Starts an exported async function on the Lucent thread and returns a JS
 /// promise for its result. `start` runs on the Lucent thread and returns the
-/// Lucent promise.
+/// Lucent promise; it does not start if the host is torn down first.
 template <class T, class F>
 jsi::Value callAsync(jsi::Runtime& rt, Host& host, F&& start) {
+  return callAsync<T>(rt, host, nullptr, std::forward<F>(start));
+}
+
+/// As above, traced from the export's `site`: the call, the job it posts
+/// (its wait and its run), the result's wait for the JS thread and its
+/// delivery share one id.
+template <class T, class F>
+jsi::Value callAsync(jsi::Runtime& rt, Host& host, const trace::Site* site, F&& start) {
+  uint64_t traceId = site && trace::enabled() ? trace::newId() : 0;
+
+  std::optional<trace::Scope> entry;
+  std::optional<trace::Correlate> correlate;
+  if (traceId) [[unlikely]] {
+    entry.emplace(trace::Category::Entry, site->name, site, traceId);
+    correlate.emplace(traceId);
+  }
+
   uint64_t id = 0;
   jsi::Value jsPromise = host.createPromise(rt, id);
   std::weak_ptr<Host> weak = host.weak_from_this();
-  Scheduler::instance().post([weak, id, start = std::forward<F>(start)]() mutable {
+
+  host.postToModule([weak, id, traceId, site, start = std::forward<F>(start)]() mutable {
     Promise<T> p;
     try {
       p = start();
     } catch (...) {
       p = Promise<T>::rejected(currentError(std::current_exception()));
     }
-    p.onSettled([p, weak, id] {
-      auto host = weak.lock();
-      if (!host) return;
-      host->postToJs([p, id, weak](jsi::Runtime& rt) {
-        auto host = weak.lock();
-        if (!host) return;
-        LucentScope scope;
-        if (p.fulfilled()) {
-          jsi::Value value = jsi::Value::undefined();
-          if constexpr (!std::is_void_v<T>) {
-            try {
-              value = Convert<T>::toJs(rt, *host, p.value());
-            } catch (const jsi::JSError& e) {
-              host->reject(rt, id, jsi::Value(rt, e.value()));
-              return;
-            }
-          }
-          host->resolve(rt, id, value);
-        } else {
-          host->reject(rt, id, host->errorToJs(rt, p.error()));
-        }
-      });
-    });
+
+    if (auto host = weak.lock()) settleLater(*host, id, p, traceId, site);
   });
+
   return jsPromise;
 }