Merge remote-tracking branch 'upstream/dev' into dev

Author: JohnDog3112

docs/gettingstarted/events.md

@@ -47,15 +47,17 @@ int timer_main() {
 # Events
 In twr-wasm, certain APIs can trigger events.  For example a timer can trigger a "timer complete" event, or an audio api my trigger a "file has finished playing" event.  An event had an `id` and an associated callback.  The `id` is an integer that identifies the event (`int event_id`).   In order to receive an event call back:
 
-1. Write your callback in C/C++.  It must be C linkage, and you should be exported from your C code to JavaScript/TypeScript using the `export_name` clang `__attribute__` like this: `__attribute__((export_name("on_timer2")))`
-2. Register your callback.  This will also allocate the event ID paired to this callback.  For example: `int t2_eventid=twr_register_callback("on_timer2");` 
+1. Write your callback in C/C++.  It must be C linkage, and you should be exported from your C code to JavaScript/TypeScript using the `export_name` clang `__attribute__` like this: `__attribute__((export_name("on_timer2")))`. Replace `on_timer2` with your callback function name.
+2. Register your callback.  This will also allocate the event ID paired to this callback.  For example: `int t2_event_id=twr_register_callback("on_timer2");`
 3. Call an API that takes an event `id`.  For example: `twr_timer_repeat(500, t2_eventid);`.  This will call the `t2_event` callback every 500ms.
 
-You can use the same event/callback with multiple APIs if you wish.  When the event callback is called, the first argument will be the event `id` triggering the callback.  There may then optional parameters.  These are event specific.
+You can use the same event/callback with multiple APIs if you wish.  When the event callback is called, the first argument will be the event `id` triggering the callback.  There may then be optional parameters.  These are event specific.
+
+As in JavaScript, twr-wasm event callbacks only occur when your C/C++ code is not running. 
 
 # When using twrWasmModuleAsync
 
-With a `twrWasmModuleAsync` module, various blocking APIs are available. For example: `twr_sleep`.  When these functions are blocking (waiting), event callbacks are queued and not processed until wait unblocks. 
+With a `twrWasmModuleAsync` module, various blocking APIs are available. For example: `twr_sleep`.  When these functions are blocking (waiting), event callbacks are queued and not processed until your C functions return back to JavaScript.
 
 With a `twrWasmModuleAsync` module, events are sent from the JavaScript main thread to the worker thread that is running the C/C++ code.
 

examples/tests-timer/tests-timer.c

@@ -10,11 +10,6 @@ __attribute__((export_name("on_timer1")))
 void on_timer1(int event_id) {
    t1_count++;
    printf("timer callback 1 entered (event id=%d, count=%d)\n", event_id, t1_count);
-
-   if (t2_count!=5) 
-      printf("twr_timer_repeat FAIL!!\n");
-   else
-      printf("test run complete\n");
 }
 
 // timer2 event callback (called multiple times)
@@ -25,34 +20,30 @@ void on_timer2(int event_id) {
 
    if (t2_count==5) {
       twr_timer_cancel(t2_id);
-      if (t1_count!=0) 
+      if (t1_count!=1) 
          printf("twr_timer_single_shot FAIL!!\n");
+      printf("timer test complete\n");
    }
 }
 
 int tests_timer(int is_async) {
 
    printf("starting timer tests.\n");
 
+   int t1_eventid=twr_register_callback("on_timer1");
+   twr_timer_single_shot(2000, t1_eventid);
+
    int t2_eventid=twr_register_callback("on_timer2");
    t2_id=twr_timer_repeat(500, t2_eventid);
-   
-   int t1_eventid=twr_register_callback("on_timer1");
 
    if (is_async) {
       printf("going to sleep...\n");
       twr_sleep(1000);
       printf("awake from sleep!\n");
-
-      if (t2_count!=2) {
-         printf("FAIL!!  t2_count is %d\n", t2_count);
       }
 
-      twr_timer_single_shot(2000, t1_eventid);
-   }
-
-   else {
-      twr_timer_single_shot(4000, t1_eventid);
+   if (t2_count!=0 && t1_count!=0) {
+      printf("FAIL!!  t1_count is %d, t2 %d\n", t1_count, t2_count);
    }
 
    return 0;

source/twr-ts/twreventqueue.ts

@@ -107,7 +107,9 @@ export class twrEventQueueReceive {
          const [eventID, args, index]=this.findEvent(filterEvent);
          // execute callbacks up to this filterEvent (so as to call them in order)
          // if filterEvent not found, index is undefined, which causes doCallbacks to execute all pendingEventIDs
-         //this.doCallbacks(index); causes all kinds of problems. See notes in twrlibrary.ts
+         // this call commented out so that the C events act like JavaScript events/callbacks (only called when main function finishes)
+         // to consider: allow callbacks in sync blocking functions like sleep (that use await in their implementations)
+         //this.doCallbacks(index); 
          if (eventID && args) {
          return [eventID, args];
          }

source/twr-ts/twrlibrary.ts

@@ -7,15 +7,8 @@ import {twrEventQueueReceive} from "./twreventqueue.js"
 /////////////////////////////////////////////////////////////////////
 
 // TODO List
-// Working on: Allow callbacks while blocking call is waiting.
-// see commented out doCallbacks in WaitEvents
-// what if printf in callback and char waits for ret val?
-// that is what drawseq does
-// is animateframe being called before drawseq retval?
-// ie, recursive  waitEvent
-// update doc, can't block in a callback?
-// finish test_timer
-
+// Should we:  Allow callbacks while blocking call is waiting? Not on "return value" waits, but on functions like sleep.
+// add a function to allow twrWasmModuleAsync c code (like main) to process events without returning to JavaScript
 // fix example/lib/out and .gitignore so correct build artifacts are checked in  
 // resolve fact that libraries with interfaces are passed in the "io" option.  Eg Allow "libs" or other synonym.
 // current implementation has no libs: (akin to io:).