docs: An example that implements broadcast communication (#656)

Co-authored-by: Carlos Fuentes <me@metcoder.dev>
(cherry picked from commit d57084a)

README.md

@@ -260,6 +260,56 @@ module.exports = ({ a, b }) => {
 };
 ```
 
+### Broadcast a message to all worker threads
+
+Piscina supports broadcast communication via BroadcastChannel(Node v18+). Here is an example, the main thread sends a message, and other threads the receive message.
+
+In `main.js`
+```js
+'use strict';
+
+const { BroadcastChannel } = require('worker_threads');
+const { resolve } = require('path');
+
+const Piscina = require('piscina');
+const piscina = new Piscina({
+  filename: resolve(__dirname, 'worker.js'),
+  useAtomics: false
+});
+
+async function main () {
+  const bc = new BroadcastChannel('my_channel');
+  // start worker
+  Promise.all([
+    piscina.run('thread 1'),
+    piscina.run('thread 2')
+  ]);
+  // post message in one second
+  setTimeout(() => {
+    bc.postMessage('Main thread message');
+  }, 1000);
+}
+
+main();
+
+```
+In `worker.js`
+```js
+'use strict';
+const { BroadcastChannel } = require('worker_threads');
+
+module.exports = async (thread) => {
+  const bc = new BroadcastChannel('my_channel');
+  bc.onmessage = (event) => {
+    console.log(thread + ' Received from:' + event.data);
+  };
+  await new Promise((resolve) => {
+    setTimeout(resolve, 2000);
+  });
+};
+
+```
+
 ### Additional Examples
 
 Additional examples can be found in the GitHub repo at

docs/docs/examples/broadcast.mdx

@@ -0,0 +1,61 @@
+---
+id: Simple
+sidebar_position: 23
+---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import { WorkerWrapperComponent } from '@site/src/components/WorkerWrapper.mdx'
+
+In this example, we create a Piscina instance that uses BroadcastChannel(Node v18+) to implement broadcast communication. The main thread sends a message, and other threads the receive message.
+
+<Tabs>
+<TabItem value="Javascript">
+
+```javascript title="index.js"
+'use strict';
+
+const { BroadcastChannel } = require('worker_threads');
+const { resolve } = require('path');
+
+const Piscina = require('piscina');
+const piscina = new Piscina({
+  filename: resolve(__dirname, 'worker.js'),
+  useAtomics: false
+});
+
+async function main () {
+  const bc = new BroadcastChannel('my_channel');
+  // start worker
+  Promise.all([
+    piscina.run('thread 1'),
+    piscina.run('thread 2')
+  ]);
+  // post message in one second
+  setTimeout(() => {
+    bc.postMessage('Main thread message');
+  }, 1000);
+}
+
+main();
+
+```
+
+```javascript title="worker.js"
+'use strict';
+const { BroadcastChannel } = require('worker_threads');
+
+module.exports = async (thread) => {
+  const bc = new BroadcastChannel('my_channel');
+  bc.onmessage = (event) => {
+    console.log(thread + ' Received from:' + event.data);
+  };
+  await new Promise((resolve) => {
+    setTimeout(resolve, 2000);
+  });
+};
+
+```
+</TabItem>
+</Tabs>
+
+You can also check out this example on [github](https://github.com/piscinajs/piscina/tree/current/examples/broadcast).

examples/broadcast/main.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { BroadcastChannel } = require('worker_threads');
+const { resolve } = require('path');
+
+const Piscina = require('piscina');
+const piscina = new Piscina({
+  filename: resolve(__dirname, 'worker.js'),
+  // Set useAtomics to false to avoid threads being blocked when idle
+  useAtomics: false
+});
+
+async function main () {
+  const bc = new BroadcastChannel('my_channel');
+  // start worker
+  Promise.all([
+    piscina.run('thread 1'),
+    piscina.run('thread 2')
+  ]);
+  // post message in one second
+  setTimeout(() => {
+    bc.postMessage('Main thread message');
+  }, 1000);
+}
+
+main();

examples/broadcast/worker.js

@@ -0,0 +1,12 @@
+'use strict';
+const { BroadcastChannel } = require('worker_threads');
+
+module.exports = async (thread) => {
+  const bc = new BroadcastChannel('my_channel');
+  bc.onmessage = (event) => {
+    console.log(thread + ' Received from:' + event.data);
+  };
+  await new Promise((resolve) => {
+    setTimeout(resolve, 2000);
+  });
+};