@rosepetal/node-red-contrib-async-function 1.0.1 → 1.0.3

package/README.md

@@ -20,7 +20,7 @@ Run heavy computations in Node-RED without slowing down your flows. This node wo
 
 ## How It Works
 
-Drop an **async function** node into your flow. Write your code just like you would in a regular function node. The difference? Your code runs in a separate worker thread, so heavy operations won't freeze Node-RED.
+Drop an **async function** node into your flow. Write your code just like you would in a regular function node. The difference? Your code runs in a separate worker thread by default (or a child process if configured), so heavy operations won't freeze Node-RED.
 
 ## When to Use This
 
@@ -31,7 +31,7 @@ Drop an **async function** node into your flow. Write your code just like you wo
 
 **Skip It For:**
 - Simple math or quick transformations (the regular function node is faster).
-- When you need `context`, `flow`, or `global` storage (coming in v2.0).
+- Flows that require live context reads/writes during execution (context is snapshot-based).
 
 ## Node Options
 
@@ -40,9 +40,10 @@ Drop an **async function** node into your flow. Write your code just like you wo
 - **Function** – Your JavaScript code. Works with `async/await`, `return`, and `require()`.
 - **Outputs** – How many output wires (0-10). Return an array for multiple outputs.
 - **Timeout** – Maximum seconds to wait before killing the worker. Default: 30 seconds.
+- **Runtime** – Worker Threads (default, fastest) or Child Process (for native modules like `gl`).
 
 ### Worker Pool
-- **Workers** – Fixed number of worker threads (1-16). Each node maintains exactly this many workers. Default: 3.
+- **Workers** – Fixed number of workers (1-16). Each node maintains exactly this many workers. Default: 3.
 - **Queue Size** – Messages to queue when all workers are occupied. Default: 100.
 
 ### Modules
@@ -61,7 +62,7 @@ return msg;
 ```
 
 ### Buffer Handling
-- **Buffers** – Any `Buffer` in `msg` is transferred through shared memory (`/dev/shm` on Linux, otherwise `os.tmpdir()`), with base64 fallback if needed.
+- **Buffers** – Worker Threads use zero-copy transfer when possible. Child Process mode and non-transferable buffers fall back to shared memory (`/dev/shm` on Linux, otherwise `os.tmpdir()`), with base64 fallback if needed.
 
 ## Typical Flow
 
@@ -85,9 +86,11 @@ return msg;
 - `console` – Logging functions
 - `setTimeout`, `setInterval` – Timers
 
-**Not Available (Yet):**
-- `context`, `flow`, `global` – Coming in v2.0
-- `node` – Node instance methods
+**Notes:**
+- `context`, `flow`, `global` are snapshot-based: reads are from the snapshot, writes are applied after the function completes
+- Snapshot includes only literal keys found in `flow.get("key")` / `global.get("key")` / `context.get("key")`
+- Context store selection is not supported (default store only)
+- `node.warn/error/log` are collected and forwarded to the main thread
 - Non-serializable objects (functions, symbols, etc.)
 
 ## Code Examples
@@ -165,11 +168,11 @@ The node shows you what's happening in real time:
 
 ## Performance Notes
 
-- Worker threads add about 5-10ms overhead per message.
+- Worker threads add about 5-10ms overhead per message (child process mode is higher).
 - Best for operations taking more than 10ms to run.
 - Each node maintains a fixed pool of workers—no startup delay or dynamic scaling overhead.
 - Workers are dedicated per-node, ensuring predictable performance.
-- **Binary Fast Path**: Buffers use shared memory transfer (base64 fallback), keeping messages responsive even with large payloads.
+- **Binary Fast Path**: Worker threads use zero-copy transfer when possible; shared memory is the fallback.
 - Event loop never blocks, even when processing multi-MB binary data (images, files, etc.).
 
 ## Error Handling

package/nodes/async-function.html

@@ -7,10 +7,11 @@
         defaults: {
             name: { value: '' },
             func: {
-                value: '// Write your async code here\n// The code runs in a worker thread\n// Available: msg, return, async/await, require()\n// Not available: context, flow, global, node\n\nreturn msg;'
+                value: '// Write your async code here\n// The code runs in a worker thread or child process\n// Available: msg, return, async/await, require(), node.warn/error/log,\n//           flow/global/context (snapshot-based)\n\nreturn msg;'
             },
             outputs: { value: 1, validate: RED.validators.number() },
             timeout: { value: 30000, validate: RED.validators.number() },
+            executionMode: { value: 'worker_threads' },
             numWorkers: { value: 3, validate: RED.validators.number() },
             maxQueueSize: { value: 100, validate: RED.validators.number() },
             libs: { value: [] },
@@ -239,6 +240,32 @@
             // Ensure configured module vars are registered in the editor on load
             updateEditorModules();
 
+            // Restart Workers button click handler
+            $('#node-restart-workers').on('click', function() {
+                var btn = $(this);
+                var status = $('#node-restart-status');
+                var nodeId = node.id;
+
+                btn.prop('disabled', true);
+                status.text('Restarting...').css('color', '#666');
+
+                $.ajax({
+                    url: 'async-function/' + nodeId + '/restart',
+                    type: 'POST',
+                    success: function(data) {
+                        status.text('✓ Workers restarted').css('color', 'green');
+                        setTimeout(function() { status.text(''); }, 3000);
+                    },
+                    error: function(xhr) {
+                        var msg = xhr.responseJSON ? xhr.responseJSON.error : 'Restart failed';
+                        status.text('✗ ' + msg).css('color', 'red');
+                    },
+                    complete: function() {
+                        btn.prop('disabled', false);
+                    }
+                });
+            });
+
             // Resize editor on dialog resize
             $('#dialog-form').on('dialogresize', function() {
                 const rows = $('#dialog-form>div:not(#async-func-tabs-content)');
@@ -412,6 +439,13 @@
                     <input id="node-input-timeout" style="width:120px;" value="30000">
                     <span style="margin-left:5px;">ms</span>
                 </div>
+                <div class="form-row">
+                    <label for="node-input-executionMode"><i class="fa fa-bolt"></i> Runtime</label>
+                    <select id="node-input-executionMode" style="width: 260px;">
+                        <option value="worker_threads">Worker Threads (fastest)</option>
+                        <option value="child_process">Child Process (native modules)</option>
+                    </select>
+                </div>
             </div>
 
             <!-- Worker Pool Section -->
@@ -440,6 +474,22 @@
                     <ol id="node-input-libs-container"></ol>
                 </div>
             </div>
+
+            <!-- Actions Section -->
+            <div class="async-func-section">
+                <div class="async-func-section-header">
+                    <i class="fa fa-refresh"></i> Actions
+                </div>
+                <div class="form-row" style="margin-bottom: 0;">
+                    <button type="button" class="red-ui-button" id="node-restart-workers">
+                        <i class="fa fa-refresh"></i> Restart Workers
+                    </button>
+                    <span id="node-restart-status" style="margin-left: 10px;"></span>
+                    <div style="margin-top: 8px; color: #999; font-size: 12px;">
+                        Restarts all worker processes/threads to reload modules and reset state.
+                    </div>
+                </div>
+            </div>
         </div>
 
         <!-- Function Tab -->
@@ -456,12 +506,13 @@
             <div class="form-tips">
                 <b>Tips:</b>
                 <ul style="margin-top:5px; margin-bottom:0;">
-                    <li>Code runs in a worker thread to prevent blocking</li>
-                    <li>Available: <code>msg</code>, <code>return</code>, <code>async/await</code>, <code>require()</code></li>
-                    <li>Not available: <code>context</code>, <code>flow</code>, <code>global</code>, <code>node</code></li>
-                    <li>Return <code>msg</code> for single output, or <code>[msg1, msg2]</code> for multiple outputs</li>
-                    <li>Return <code>null</code> to stop the flow</li>
-                </ul>
+                <li>Code runs in a worker thread or child process to prevent blocking</li>
+                <li>Available: <code>msg</code>, <code>return</code>, <code>async/await</code>, <code>require()</code>, <code>node</code>, <code>flow</code>, <code>global</code>, <code>context</code></li>
+                <li>Context access is snapshot-based (writes apply after execution)</li>
+                <li>Use "Child Process" runtime for native modules that require main thread (e.g., <code>gl</code>)</li>
+                <li>Return <code>msg</code> for single output, or <code>[msg1, msg2]</code> for multiple outputs</li>
+                <li>Return <code>null</code> to stop the flow</li>
+            </ul>
             </div>
         </div>
 
@@ -469,7 +520,7 @@
 </script>
 
 <script type="text/html" data-help-name="async-function">
-    <p>Execute custom JavaScript code in a worker thread to prevent event loop blocking.</p>
+    <p>Execute custom JavaScript code in a worker thread or child process to prevent event loop blocking.</p>
 
     <h3>Inputs</h3>
     <dl class="message-properties">
@@ -486,8 +537,8 @@
     </dl>
 
     <h3>Details</h3>
-    <p>This node executes JavaScript code in a worker thread, preventing CPU-intensive operations
-    from blocking the Node-RED event loop.</p>
+    <p>This node executes JavaScript code in a worker thread or child process, preventing CPU-intensive
+    operations from blocking the Node-RED event loop.</p>
 
     <h4>Available in Code</h4>
     <ul>
@@ -495,14 +546,14 @@
         <li><code>return</code> - Return modified message or array of messages</li>
         <li><code>async/await</code> - Use async operations</li>
         <li><code>require()</code> - Import Node.js modules</li>
+        <li><code>node</code> - Node helpers (<code>warn</code>, <code>error</code>, <code>log</code>)</li>
+        <li><code>flow</code>, <code>global</code>, <code>context</code> - Snapshot-based context access (writes apply after execution)</li>
         <li><code>console</code> - Logging functions</li>
         <li><code>setTimeout</code>, <code>setInterval</code> - Timers</li>
     </ul>
 
     <h4>Not Available</h4>
     <ul>
-        <li><code>context</code>, <code>flow</code>, <code>global</code> - Context storage (v2.0 feature)</li>
-        <li><code>node</code> - Node instance methods</li>
         <li>Non-serializable objects in <code>msg</code></li>
     </ul>
 
@@ -554,12 +605,14 @@ return msg;</pre>
         <dd>Number of output ports (0-10). Use array return for multiple outputs.</dd>
         <dt>Timeout</dt>
         <dd>Maximum execution time in milliseconds (1000-300000). Worker is terminated if exceeded. Default: 30000 (30s).</dd>
+        <dt>Runtime</dt>
+        <dd>Worker Threads (default, fastest) or Child Process (useful for native modules like <code>gl</code>).</dd>
         <dt>Workers</dt>
-        <dd>Fixed number of worker threads (1-16). Each node maintains exactly this many workers. Default: 3.</dd>
+        <dd>Fixed number of workers (1-16). Each node maintains exactly this many workers. Default: 3.</dd>
         <dt>Queue Size</dt>
         <dd>Maximum number of messages queued when all workers are busy (10-1000). Default: 100.</dd>
         <dt>Buffers</dt>
-        <dd>All Buffers are transferred via shared memory when possible (falls back to base64 if needed).</dd>
+        <dd>Worker threads use zero-copy transfer when possible; shared memory is used as a fallback.</dd>
     </dl>
 
     <h3>Status Display</h3>
@@ -582,13 +635,15 @@ return msg;</pre>
 
     <h3>Performance Notes</h3>
     <ul>
-        <li>Worker threads add ~5-10ms overhead per message</li>
+        <li>Worker threads add ~5-10ms overhead per message (child process mode is higher)</li>
         <li>Best for CPU-intensive operations (>10ms execution time)</li>
         <li>For simple operations, use the standard function node</li>
         <li>Workers are pooled and reused for efficiency</li>
-        <li><b>Buffer Transfer:</b> Buffers are streamed through shared memory (base64 fallback)</li>
+        <li><b>Buffer Transfer:</b> Worker threads use zero-copy transfer when possible; shared memory is the fallback</li>
         <li>Event loop never blocks, even when processing multi-MB binary data (images, files, etc.)</li>
         <li>Message transfer is optimized by copying only referenced <code>msg.*</code> keys when possible</li>
+        <li>Context snapshots include only literal keys found in <code>flow.get("key")</code> etc.</li>
+        <li>Context snapshots use the default context store only</li>
         <li>Timing is recorded on <code>msg.performance</code> under the node label</li>
     </ul>