docs: js_event_loop

Author: portasynthinca3

applications/system/js_app/examples/apps/Scripts/event_loop.js

@@ -2,15 +2,26 @@
 /// <reference types="../../../types/event_loop" />
 let event_loop = require("event_loop");
 
+// print a string after 1337 milliseconds
+event_loop.subscribe(event_loop.timer("oneshot", 1337), function (_subscription) {
+    print("Hi after 1337 ms");
+});
+
+// count up to 5 with a delay of 100ms between increments
+event_loop.subscribe(event_loop.timer("periodic", 100), function (subscription, counter) {
+    print("Counter two:", counter);
+    if (counter === 5)
+        subscription.cancel();
+    return [counter + 1];
+}, 0);
+
+// count up to 15 with a delay of 100ms between increments
+// and stop the program when the count reaches 15
 event_loop.subscribe(event_loop.timer("periodic", 100), function (_subscription, event_loop, counter) {
-    print("Counter:", counter);
+    print("Counter one:", counter);
     if (counter === 15)
         event_loop.stop();
     return [event_loop, counter + 1];
 }, event_loop, 0);
 
-event_loop.subscribe(event_loop.timer("oneshot", 1337), function (_subscription) {
-    print("Hi after 1337 ms");
-});
-
 event_loop.run();

applications/system/js_app/modules/js_event_loop.c

@@ -3,17 +3,26 @@
 #include <expansion/expansion.h>
 #include <furi/core/event_loop_i.h>
 
+/**
+ * @brief Per-module instance control structure
+ */
 typedef struct {
     FuriEventLoop* loop;
 } JsEventLoop;
 
+/**
+ * @brief Context passed to the generic event callback
+ */
 typedef struct {
     struct mjs* mjs;
     mjs_val_t callback;
     size_t arity;
     mjs_val_t* arguments;
 } JsEventLoopCallbackContext;
 
+/**
+ * @brief Generic event callback, handles all events
+ */
 static void js_event_loop_callback(void* param) {
     JsEventLoopCallbackContext* context = (JsEventLoopCallbackContext*)param;
     mjs_val_t result;
@@ -25,7 +34,7 @@ static void js_event_loop_callback(void* param) {
         context->arity,
         context->arguments);
 
-    // save returned value until next call
+    // save returned value as args for next call
     if(mjs_array_length(context->mjs, result) != context->arity - 1) return;
     for(size_t i = 0; i < context->arity - 1; i++) {
         mjs_disown(context->mjs, &context->arguments[i + 1]);
@@ -34,6 +43,9 @@ static void js_event_loop_callback(void* param) {
     }
 }
 
+/**
+ * @brief Subscribes a JavaScript function to an event
+ */
 static void js_event_loop_subscribe(struct mjs* mjs) {
     // get arguments
     if(mjs_nargs(mjs) < 2)
@@ -73,16 +85,26 @@ static void js_event_loop_subscribe(struct mjs* mjs) {
     }
 }
 
+/**
+ * @brief Runs the event loop until it is stopped
+ */
 static void js_event_loop_run(struct mjs* mjs) {
     JsEventLoop* module = mjs_get_ptr(mjs, mjs_get(mjs, mjs_get_this(mjs), INST_PROP_NAME, ~0));
     furi_event_loop_run(module->loop);
 }
 
+/**
+ * @brief Stops a running event loop
+ */
 static void js_event_loop_stop(struct mjs* mjs) {
     JsEventLoop* module = mjs_get_ptr(mjs, mjs_get(mjs, mjs_get_this(mjs), INST_PROP_NAME, ~0));
     furi_event_loop_stop(module->loop);
 }
 
+/**
+ * @brief Creates a timer event that can be subscribed to just like and other
+ * event
+ */
 static void js_event_loop_timer(struct mjs* mjs) {
     // get arguments
     if(mjs_nargs(mjs) != 2) JS_ERROR_AND_RETURN(mjs, MJS_BAD_ARGS_ERROR, "requires 2 arguments");
@@ -111,6 +133,8 @@ static void js_event_loop_timer(struct mjs* mjs) {
     mjs_return(mjs, mjs_mk_foreign(mjs, contract));
 }
 
+// TODO: memory freeing, subscription cancellation
+
 static void* js_event_loop_create(struct mjs* mjs, mjs_val_t* object) {
     mjs_val_t event_loop_obj = mjs_mk_object(mjs);
     JsEventLoop* module = malloc(sizeof(JsEventLoop));

applications/system/js_app/modules/js_event_loop.h

@@ -10,14 +10,26 @@ typedef enum {
     JsEventLoopObjectTypeStream,
 } JsEventLoopObjectType;
 
+/**
+ * @brief Adapter for other JS modules that wish to integrate with the event
+ * loop
+ * 
+ * If another module wishes to integrate with `js_event_loop`, it needs to
+ * implement a function that returns an mJS foreign pointer to an instance of
+ * this structure. This value is then read by `event_loop`'s `subscribe`
+ * function.
+ */
 typedef struct {
     JsEventLoopObjectType object_type;
     FuriEventLoopObject* object;
     union {
-        FuriEventLoopEvent event;
+        FuriEventLoopEvent
+            event; //<! Event bitfield. Valid for all `object_type`s except `JsEventLoopObjectTypeTimer`
         struct {
-            FuriEventLoopTimerType timer_type;
-            uint32_t interval_ticks;
+            FuriEventLoopTimerType
+                timer_type; //<! Timer type (periodic or oneshot). Only valid for `JsEventLoopObjectTypeTimer`
+            uint32_t
+                interval_ticks; //<! Timer interval in ticks. Only valid for `JsEventLoopObjectTypeTimer`
         };
     };
 } JsEventLoopContract;

applications/system/js_app/types/event_loop/index.d.ts

@@ -1,15 +1,47 @@
 type Lit = undefined | null | {};
 
+/**
+ * Subscription control interface
+ */
 export interface Subscription {
+    /**
+     * Cancels the subscription, preventing any future events managed by the
+     * subscription from firing
+     */
     cancel(): void;
 }
 
+/**
+ * Opaque event source identifier
+ */
 export type Contract = symbol;
 
-export type Callback<Args extends Lit[]> = (subscription: Subscription, ...args: Args) => Args | void;
+/**
+ * A callback can be assigned to an event loop to listen to an event. It may
+ * return an array with values that will be passed to it as arguments the next
+ * time that it is called.
+ */
+export type Callback<Args extends Lit[]> = (subscription: Subscription, ...args: Args) => Args | undefined | void;
 
+/**
+ * Subscribes a callback to an event
+ * @param contract Event identifier
+ * @param callback Function to call when the event is triggered
+ * @param args Initial arguments passed to the callback
+ */
 export function subscribe<Args extends Lit[]>(contract: Contract, callback: Callback<Args>, ...args: Args): Subscription;
-export function run(): void;
+/**
+ * Runs the event loop until it is stopped (potentially never)
+ */
+export function run(): void | never;
+/**
+ * Stops the event loop
+ */
 export function stop(): void;
 
+/**
+ * Creates a timer event that can be subscribed to just like any other event
+ * @param mode Either `"oneshot"` or `"periodic"`
+ * @param interval Timer interval in milliseconds
+ */
 export function timer(mode: "oneshot" | "periodic", interval: number): Contract;