BF-40: Py buffers (bytearray/memoryview/etc.) to JS TypedArray, JS TypedArray/ArrayBuffer to Py memoryview coercion

include/BufferType.hh

@@ -0,0 +1,71 @@
+/**
+ * @file BufferType.hh
+ * @author Tom Tang (xmader@distributive.network)
+ * @brief Struct for representing ArrayBuffers
+ * @version 0.1
+ * @date 2023-04-27
+ *
+ * @copyright Copyright (c) 2023 Distributive Corp.
+ *
+ */
+
+#ifndef PythonMonkey_BufferType_
+#define PythonMonkey_BufferType_
+
+#include "PyType.hh"
+#include "TypeEnum.hh"
+
+#include <jsapi.h>
+#include <js/ScalarType.h>
+
+#include <Python.h>
+
+struct BufferType : public PyType {
+public:
+  BufferType(PyObject *object);
+
+  /**
+   * @brief Construct a new BufferType object from a JS TypedArray or ArrayBuffer, as a Python [memoryview](https://docs.python.org/3.9/c-api/memoryview.html) object
+   *
+   * @param cx - javascript context pointer
+   * @param bufObj - JS object to be coerced
+   */
+  BufferType(JSContext *cx, JS::HandleObject bufObj);
+
+  const TYPE returnType = TYPE::BUFFER;
+
+  /**
+   * @brief Convert a Python object that [provides the buffer interface](https://docs.python.org/3.9/c-api/typeobj.html#buffer-object-structures) to JS TypedArray.
+   * The subtype (Uint8Array, Float64Array, ...) is automatically determined by the Python buffer's [format](https://docs.python.org/3.9/c-api/buffer.html#c.Py_buffer.format)
+   *
+   * @param cx - javascript context pointer
+   */
+  JSObject *toJsTypedArray(JSContext *cx);
+
+  /**
+   * @returns Is the given JS object either a TypedArray or an ArrayBuffer?
+   */
+  static bool isSupportedJsTypes(JSObject *obj);
+
+protected:
+  virtual void print(std::ostream &os) const override;
+
+  static PyObject *fromJsTypedArray(JSContext *cx, JS::HandleObject typedArray);
+  static PyObject *fromJsArrayBuffer(JSContext *cx, JS::HandleObject arrayBuffer);
+
+private:
+  static void _releasePyBuffer(Py_buffer *bufView);
+  static void _releasePyBuffer(void *, void *bufView); // JS::BufferContentsFreeFunc callback for JS::NewExternalArrayBuffer
+
+  static JS::Scalar::Type _getPyBufferType(Py_buffer *bufView);
+  static const char *_toPyBufferFormatCode(JS::Scalar::Type subtype);
+
+  /**
+   * @brief Create a new typed array using up the given ArrayBuffer or SharedArrayBuffer for storage.
+   * @see https://hg.mozilla.org/releases/mozilla-esr102/file/a03fde6/js/public/experimental/TypedData.h#l80
+   * There's no SpiderMonkey API to assign the subtype at execution time
+   */
+  static JSObject *_newTypedArrayWithBuffer(JSContext *cx, JS::Scalar::Type subtype, JS::HandleObject arrayBuffer);
+};
+
+#endif

include/ExceptionType.hh

@@ -0,0 +1,49 @@
+/**
+ * @file ExceptionType.hh
+ * @author Tom Tang (xmader@distributive.network)
+ * @brief Struct for representing Python Exception objects from a corresponding JS Error object
+ * @version 0.1
+ * @date 2023-04-11
+ *
+ * @copyright Copyright (c) 2023
+ *
+ */
+
+#ifndef PythonMonkey_ExceptionType_
+#define PythonMonkey_ExceptionType_
+
+#include "PyType.hh"
+#include "TypeEnum.hh"
+
+#include <jsapi.h>
+
+#include <Python.h>
+
+/**
+ * @brief This struct represents a Python Exception object from the corresponding JS Error object
+ */
+struct ExceptionType : public PyType {
+public:
+  ExceptionType(PyObject *object);
+
+  /**
+   * @brief Construct a new SpiderMonkeyError from the JS Error object.
+   *
+   * @param cx - javascript context pointer
+   * @param error - JS Error object to be converted
+   */
+  ExceptionType(JSContext *cx, JS::HandleObject error);
+
+  const TYPE returnType = TYPE::EXCEPTION;
+
+  /**
+   * @brief Convert a python [*Exception object](https://docs.python.org/3/c-api/exceptions.html#standard-exceptions) to JS Error object
+   *
+   * @param cx - javascript context pointer
+   */
+  JSObject *toJsError(JSContext *cx);
+protected:
+  virtual void print(std::ostream &os) const override;
+};
+
+#endif

include/IntType.hh

@@ -33,7 +33,7 @@ public:
    * @brief Construct a new IntType object from a JS::BigInt.
    *
    * @param cx - javascript context pointer
-   * @param str - JS::BigInt pointer
+   * @param bigint - JS::BigInt pointer
    */
   IntType(JSContext *cx, JS::BigInt *bigint);
 

include/JobQueue.hh

@@ -0,0 +1,67 @@
+/**
+ * @file JobQueue.hh
+ * @author Tom Tang (xmader@distributive.network)
+ * @brief
+ * @version 0.1
+ * @date 2023-04-03
+ *
+ * @copyright Copyright (c) 2023
+ *
+ */
+
+#ifndef PythonMonkey_JobQueue_
+#define PythonMonkey_JobQueue_
+
+#include <jsapi.h>
+#include <js/Promise.h>
+
+#include <Python.h>
+
+class JobQueue : public JS::JobQueue {
+//
+// JS::JobQueue methods.
+//    see also: js::InternalJobQueue https://hg.mozilla.org/releases/mozilla-esr102/file/tip/js/src/vm/JSContext.h#l88
+//
+public:
+~JobQueue() = default;
+
+JSObject *getIncumbentGlobal(JSContext *cx) override;
+
+bool enqueuePromiseJob(JSContext *cx, JS::HandleObject promise,
+  JS::HandleObject job, JS::HandleObject allocationSite,
+  JS::HandleObject incumbentGlobal) override;
+
+void runJobs(JSContext *cx) override;
+
+/**
+ * @return true if the job queue is empty, false otherwise.
+ */
+bool empty() const override;
+
+private:
+js::UniquePtr<JS::JobQueue::SavedJobQueue> saveJobQueue(JSContext *) override;
+
+//
+// Custom methods
+//
+public:
+/**
+ * @brief Initialize PythonMonkey's event-loop job queue
+ * @param cx - javascript context pointer
+ * @return success
+ */
+bool init(JSContext *cx);
+
+private:
+/**
+ * @brief The callback for dispatching an off-thread promise to the event loop
+ *          see https://hg.mozilla.org/releases/mozilla-esr102/file/tip/js/public/Promise.h#l580
+ *              https://hg.mozilla.org/releases/mozilla-esr102/file/tip/js/src/vm/OffThreadPromiseRuntimeState.cpp#l160
+ * @param closure - closure, currently the javascript context
+ * @param dispatchable - Pointer to the Dispatchable to be called
+ * @return not shutting down
+ */
+static bool dispatchToEventLoop(void *closure, JS::Dispatchable *dispatchable);
+};
+
+#endif

include/PromiseType.hh

@@ -0,0 +1,56 @@
+/**
+ * @file PromiseType.hh
+ * @author Tom Tang (xmader@distributive.network)
+ * @brief Struct for representing Promises
+ * @version 0.1
+ * @date 2023-03-29
+ *
+ * @copyright Copyright (c) 2023
+ *
+ */
+
+#ifndef PythonMonkey_PromiseType_
+#define PythonMonkey_PromiseType_
+
+#include "PyType.hh"
+#include "TypeEnum.hh"
+
+#include <jsapi.h>
+#include <js/Promise.h>
+
+#include <Python.h>
+
+/**
+ * @brief This struct represents the JS Promise type in Python using our custom pythonmonkey.promise type. It inherits from the PyType struct
+ */
+struct PromiseType : public PyType {
+public:
+  PromiseType(PyObject *object);
+
+  /**
+   * @brief Construct a new PromiseType object from a JS::PromiseObject.
+   *
+   * @param cx - javascript context pointer
+   * @param promise - JS::PromiseObject to be coerced
+   */
+  PromiseType(JSContext *cx, JS::HandleObject promise);
+
+  const TYPE returnType = TYPE::PYTHONMONKEY_PROMISE;
+
+  /**
+   * @brief Convert a Python [awaitable](https://docs.python.org/3/library/asyncio-task.html#awaitables) object to JS Promise
+   *
+   * @param cx - javascript context pointer
+   */
+  JSObject *toJsPromise(JSContext *cx);
+protected:
+  virtual void print(std::ostream &os) const override;
+};
+
+/**
+ * @brief Check if the object can be used in Python await expression.
+ * `PyAwaitable_Check` hasn't been and has no plan to be added to the Python C API as of CPython 3.9
+ */
+bool PythonAwaitable_Check(PyObject *obj);
+
+#endif