From 2565bc0d82d9cb012f7a2f9cdbc299cca8b856ae Mon Sep 17 00:00:00 2001 From: Tim Sekiguchi Date: Wed, 4 Dec 2024 13:55:47 -0800 Subject: [PATCH 1/4] chore: add electron specific documentation to the examples section in the docs --- docs/docs/examples/electron.mdx | 46 +++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/docs/examples/electron.mdx diff --git a/docs/docs/examples/electron.mdx b/docs/docs/examples/electron.mdx new file mode 100644 index 00000000..9a0f2618 --- /dev/null +++ b/docs/docs/examples/electron.mdx @@ -0,0 +1,46 @@ +--- +id: Worker Options +sidebar_position: 4 +--- + +import { WorkerWrapperComponent } from "@site/src/components/WorkerWrapper.mdx"; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +Using workers and pooling within your application can greatly enhance performance and stability. The renderer is processed on the main thread, so any processor intensive tasks are going to cause hangups for users, either delivering a poor UX or in many cases, causing the dreaded `pthread_kill` and crashing the app. + +Implementing workers is relatively straight-forward in development, but you might run into some issues when packaging your build. + +## electron-vite +NB: While Electron / electron-vite officially support ESM, with the way that rollup packages the worker, electron ends up not being able read the worker. You must be using CJS in electron to read the worker modules. Besides, the bytecode plugin for obfuscating your code only works with CJS too. + +In your main file, import the path to your worker (not the wrapper - no wrapper is needed because of rollup) by appending `\*?modulePath` to the end of the path. + +```typescript +import workerPath from './worker?modulePath'; +``` + +During compilation, rollup will now automatically create a separate file for the worker in your main folder output at the given path. The path above resolves, and we can now use this in Piscina at run time. + +Create a pool with Piscina, and use the imported path instead. + +For those using TypeScript, the filename export referenced in the guide is not needed. + +```typescript title="index.ts" +const pool = new Piscina({ + filename: workerPath, + workerData: { + userPath: path.join(app.getPath("userData")), + }, +}); +``` + +Electron-specific modules are NOT accessible inside workers. + +If you need access to information that electron provides, (e.g. `app.getPath("userData")`), you'll need to pass in that data as workerData. + +That's it! You can now use pool like normal in the Piscina docs. + +For further help, reference the worker section of the docs from electron-vite. + +https://electron-vite.org/guide/dev#worker-threads From 5176769191425dd5938168502676794e9a927413 Mon Sep 17 00:00:00 2001 From: Tim Sekiguchi Date: Mon, 6 Jan 2025 11:55:14 -0800 Subject: [PATCH 2/4] fix: updated title of electron page, updated all page positions in examples to be alphabetical, move typescript to installation folder --- docs/docs/examples/broadcast.mdx | 2 +- docs/docs/examples/electron.mdx | 2 +- docs/docs/examples/es-module.mdx | 2 +- docs/docs/examples/message-port.mdx | 2 +- docs/docs/examples/messages.mdx | 2 +- docs/docs/examples/move.mdx | 2 +- .../examples/multiple-workers-one-file.mdx | 2 +- docs/docs/examples/multiple-workers.mdx | 2 +- docs/docs/examples/n-api.mdx | 2 +- docs/docs/examples/named.mdx | 2 +- docs/docs/examples/progress.mdx | 2 +- docs/docs/examples/react-ssr.mdx | 2 +- docs/docs/examples/resource-limit.mdx | 2 +- docs/docs/examples/scrypt.mdx | 2 +- docs/docs/examples/server.mdx | 2 +- docs/docs/examples/simple.mdx | 2 +- docs/docs/examples/simple_async.mdx | 2 +- docs/docs/examples/stream-in.mdx | 2 +- docs/docs/examples/stream.mdx | 2 +- docs/docs/examples/task-queue.mdx | 2 +- docs/docs/examples/typescript.md | 81 ------------------- docs/docs/examples/webstreams-transform.mdx | 2 +- docs/docs/examples/webstreams.mdx | 2 +- docs/docs/examples/worker-options.mdx | 2 +- .../managing-worker-threads.mdx | 2 +- .../typescript.mdx | 2 +- 26 files changed, 25 insertions(+), 106 deletions(-) delete mode 100644 docs/docs/examples/typescript.md rename docs/docs/{examples => getting-started}/typescript.mdx (99%) diff --git a/docs/docs/examples/broadcast.mdx b/docs/docs/examples/broadcast.mdx index f69aab51..e3d0ff6b 100644 --- a/docs/docs/examples/broadcast.mdx +++ b/docs/docs/examples/broadcast.mdx @@ -1,6 +1,6 @@ --- id: Simple -sidebar_position: 23 +sidebar_position: 3 --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/docs/examples/electron.mdx b/docs/docs/examples/electron.mdx index 9a0f2618..72f9fba5 100644 --- a/docs/docs/examples/electron.mdx +++ b/docs/docs/examples/electron.mdx @@ -1,5 +1,5 @@ --- -id: Worker Options +id: Electron sidebar_position: 4 --- diff --git a/docs/docs/examples/es-module.mdx b/docs/docs/examples/es-module.mdx index 3072ffce..c988dd90 100644 --- a/docs/docs/examples/es-module.mdx +++ b/docs/docs/examples/es-module.mdx @@ -1,6 +1,6 @@ --- id: ES Module -sidebar_position: 3 +sidebar_position: 5 --- import { WorkerWrapperComponent } from "@site/src/components/WorkerWrapper.mdx"; diff --git a/docs/docs/examples/message-port.mdx b/docs/docs/examples/message-port.mdx index ed6c7d30..27b4bb34 100644 --- a/docs/docs/examples/message-port.mdx +++ b/docs/docs/examples/message-port.mdx @@ -1,6 +1,6 @@ --- id: Message Port -sidebar_position: 4 +sidebar_position: 6 --- import { WorkerWrapperComponent } from "@site/src/components/WorkerWrapper.mdx"; diff --git a/docs/docs/examples/messages.mdx b/docs/docs/examples/messages.mdx index f86efd13..b774ef48 100644 --- a/docs/docs/examples/messages.mdx +++ b/docs/docs/examples/messages.mdx @@ -1,6 +1,6 @@ --- id: Messages -sidebar_position: 5 +sidebar_position: 7 --- import { WorkerWrapperComponent } from "@site/src/components/WorkerWrapper.mdx"; diff --git a/docs/docs/examples/move.mdx b/docs/docs/examples/move.mdx index feb91f53..c3adb569 100644 --- a/docs/docs/examples/move.mdx +++ b/docs/docs/examples/move.mdx @@ -1,6 +1,6 @@ --- id: Move -sidebar_position: 6 +sidebar_position: 8 --- import { WorkerWrapperComponent } from "@site/src/components/WorkerWrapper.mdx"; diff --git a/docs/docs/examples/multiple-workers-one-file.mdx b/docs/docs/examples/multiple-workers-one-file.mdx index 80c447e4..278e615d 100644 --- a/docs/docs/examples/multiple-workers-one-file.mdx +++ b/docs/docs/examples/multiple-workers-one-file.mdx @@ -1,6 +1,6 @@ --- id: Multiple Workers in One File -sidebar_position: 8 +sidebar_position: 9 --- import { WorkerWrapperComponent } from "@site/src/components/WorkerWrapper.mdx"; diff --git a/docs/docs/examples/multiple-workers.mdx b/docs/docs/examples/multiple-workers.mdx index c6782349..f1ec25ff 100644 --- a/docs/docs/examples/multiple-workers.mdx +++ b/docs/docs/examples/multiple-workers.mdx @@ -1,6 +1,6 @@ --- id: Multiple Workers -sidebar_position: 7 +sidebar_position: 10 --- import { WorkerWrapperComponent } from "@site/src/components/WorkerWrapper.mdx"; diff --git a/docs/docs/examples/n-api.mdx b/docs/docs/examples/n-api.mdx index 6be34d3b..5e52dc51 100644 --- a/docs/docs/examples/n-api.mdx +++ b/docs/docs/examples/n-api.mdx @@ -1,6 +1,6 @@ --- id: N-API Native Addon -sidebar_position: 9 +sidebar_position: 11 --- For CPU-intensive tasks or when implementing workers in languages such as C++ or Rust, you can leverage Piscina's support for native addons as worker implementations. diff --git a/docs/docs/examples/named.mdx b/docs/docs/examples/named.mdx index 4e1a2e74..7c14fbc4 100644 --- a/docs/docs/examples/named.mdx +++ b/docs/docs/examples/named.mdx @@ -1,6 +1,6 @@ --- id: Named Tasks -sidebar_position: 10 +sidebar_position: 12 --- import { WorkerWrapperComponent } from "@site/src/components/WorkerWrapper.mdx"; diff --git a/docs/docs/examples/progress.mdx b/docs/docs/examples/progress.mdx index 1e611bb2..2837ed57 100644 --- a/docs/docs/examples/progress.mdx +++ b/docs/docs/examples/progress.mdx @@ -1,6 +1,6 @@ --- id: Progress -sidebar_position: 11 +sidebar_position: 13 --- import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx'; diff --git a/docs/docs/examples/react-ssr.mdx b/docs/docs/examples/react-ssr.mdx index a00f195d..f7661619 100644 --- a/docs/docs/examples/react-ssr.mdx +++ b/docs/docs/examples/react-ssr.mdx @@ -1,6 +1,6 @@ --- id: React Server Side Rendering -sidebar_position: 12 +sidebar_position: 14 --- import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; diff --git a/docs/docs/examples/resource-limit.mdx b/docs/docs/examples/resource-limit.mdx index 42b967ca..f425ed77 100644 --- a/docs/docs/examples/resource-limit.mdx +++ b/docs/docs/examples/resource-limit.mdx @@ -1,6 +1,6 @@ --- id: Resource Limits -sidebar_position: 12 +sidebar_position: 15 --- import Tabs from '@theme/Tabs'; diff --git a/docs/docs/examples/scrypt.mdx b/docs/docs/examples/scrypt.mdx index 86f52efb..4a52c06e 100644 --- a/docs/docs/examples/scrypt.mdx +++ b/docs/docs/examples/scrypt.mdx @@ -1,6 +1,6 @@ --- id: Scrypt -sidebar_position: 13 +sidebar_position: 16 --- import Tabs from '@theme/Tabs'; diff --git a/docs/docs/examples/server.mdx b/docs/docs/examples/server.mdx index 38529001..aeb96b80 100644 --- a/docs/docs/examples/server.mdx +++ b/docs/docs/examples/server.mdx @@ -1,6 +1,6 @@ --- id: Server -sidebar_position: 14 +sidebar_position: 17 --- The benefit of offloading work to a worker pool will vary significantly diff --git a/docs/docs/examples/simple.mdx b/docs/docs/examples/simple.mdx index 13e7436a..abd9ff7a 100644 --- a/docs/docs/examples/simple.mdx +++ b/docs/docs/examples/simple.mdx @@ -1,6 +1,6 @@ --- id: Simple -sidebar_position: 15 +sidebar_position: 19 --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/docs/examples/simple_async.mdx b/docs/docs/examples/simple_async.mdx index c9574b45..ebb19d82 100644 --- a/docs/docs/examples/simple_async.mdx +++ b/docs/docs/examples/simple_async.mdx @@ -1,6 +1,6 @@ --- id: Simple Async -sidebar_position: 16 +sidebar_position: 18 --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/docs/examples/stream-in.mdx b/docs/docs/examples/stream-in.mdx index 793364e2..3643c0a3 100644 --- a/docs/docs/examples/stream-in.mdx +++ b/docs/docs/examples/stream-in.mdx @@ -1,6 +1,6 @@ --- id: Stream-In -sidebar_position: 17 +sidebar_position: 20 --- import Tabs from '@theme/Tabs'; diff --git a/docs/docs/examples/stream.mdx b/docs/docs/examples/stream.mdx index 5dce9c31..878b618d 100644 --- a/docs/docs/examples/stream.mdx +++ b/docs/docs/examples/stream.mdx @@ -1,6 +1,6 @@ --- id: Stream -sidebar_position: 16 +sidebar_position: 21 --- import Tabs from '@theme/Tabs'; diff --git a/docs/docs/examples/task-queue.mdx b/docs/docs/examples/task-queue.mdx index c746abf0..d3875c3c 100644 --- a/docs/docs/examples/task-queue.mdx +++ b/docs/docs/examples/task-queue.mdx @@ -1,6 +1,6 @@ --- id: Task Queue -sidebar_position: 18 +sidebar_position: 22 --- import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx'; diff --git a/docs/docs/examples/typescript.md b/docs/docs/examples/typescript.md deleted file mode 100644 index 34f874fc..00000000 --- a/docs/docs/examples/typescript.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -id: Using Typescript with Piscina -sidebar_position: 2 ---- -import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx'; - -Although Piscina itself is written in TypeScript and supports TypeScript out of the box, complication arises when trying to use `.ts` files directly as worker files because Node.js does not support TypeScript natively. - -To work around this, you would typically need to compile your TypeScript worker files to JavaScript first, and then point Piscina’s `filename` option to the compiled JavaScript files. Consider the following methods: - -## Method 1: Using a Worker Wrapper File and `ts_node` - -The worker wrapper checks if the provided file path ends with `.ts` and registers the `ts-node` compiler to handle TypeScript files. - - - -In your `worker.ts`: - -```typescript title='worker.ts' - -import { resolve } from 'path'; - -export const filename = resolve(__filename); - -interface Inputs { - a: number; - b: number; -} - -export function addNumbers({ a, b }: Inputs): number { - return a + b; -} -``` - -Inside the main application: - -```typescript title='main.ts' - -import Piscina from 'piscina'; -import { resolve } from 'path'; -import { filename } from './worker'; - -const piscina = new Piscina({ - filename: resolve(__dirname, './workerWrapper.js'), - workerData: { fullpath: filename }, -}); - -(async () => { - const result = await piscina.run({ a: 2, b: 3 }, { name: 'addNumbers' }); - console.log('Result:', result); -})(); -``` - -## Method 2: Inline Worker Code - -Alternatively, you can include the worker code in the same file as your main code and use the `isMainThread` flag from `worker_threads` to determine whether the code is running in the main thread or the worker thread. - -```typescript title="main.ts" - -import Piscina from 'piscina'; -import { isMainThread } from 'worker_threads'; - -interface Inputs { - a: number; - b: number; -} - -if (isMainThread) { - const piscina = new Piscina({ filename: __filename }); - - (async () => { - const task: Inputs = { a: 1, b: 2 }; - console.log(await piscina.run(task)); - })(); -} else { - export default ({ a, b }: Inputs): number => { - return a + b; - }; -} -``` -You can also check out this example on [github](https://github.com/piscinajs/piscina/tree/current/examples/typescript). \ No newline at end of file diff --git a/docs/docs/examples/webstreams-transform.mdx b/docs/docs/examples/webstreams-transform.mdx index 04c0bfbf..cbbc6b34 100644 --- a/docs/docs/examples/webstreams-transform.mdx +++ b/docs/docs/examples/webstreams-transform.mdx @@ -1,6 +1,6 @@ --- id: Web Streams Transfer -sidebar_position: 21 +sidebar_position: 24 --- import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx'; diff --git a/docs/docs/examples/webstreams.mdx b/docs/docs/examples/webstreams.mdx index cb6fc5fc..e2072436 100644 --- a/docs/docs/examples/webstreams.mdx +++ b/docs/docs/examples/webstreams.mdx @@ -1,6 +1,6 @@ --- id: Web Streams -sidebar_position: 20 +sidebar_position: 25 --- import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx'; diff --git a/docs/docs/examples/worker-options.mdx b/docs/docs/examples/worker-options.mdx index 0d2bc50d..4044e99d 100644 --- a/docs/docs/examples/worker-options.mdx +++ b/docs/docs/examples/worker-options.mdx @@ -1,6 +1,6 @@ --- id: Worker Options -sidebar_position: 22 +sidebar_position: 26 --- import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx'; diff --git a/docs/docs/getting-started/managing-worker-threads.mdx b/docs/docs/getting-started/managing-worker-threads.mdx index 796e7252..883bbc88 100644 --- a/docs/docs/getting-started/managing-worker-threads.mdx +++ b/docs/docs/getting-started/managing-worker-threads.mdx @@ -1,6 +1,6 @@ --- id: Managing Worker Threads -sidebar_position: 2 +sidebar_position: 3 --- import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx'; import Tabs from "@theme/Tabs"; diff --git a/docs/docs/examples/typescript.mdx b/docs/docs/getting-started/typescript.mdx similarity index 99% rename from docs/docs/examples/typescript.mdx rename to docs/docs/getting-started/typescript.mdx index 24a82d8c..962fa415 100644 --- a/docs/docs/examples/typescript.mdx +++ b/docs/docs/getting-started/typescript.mdx @@ -1,6 +1,6 @@ --- id: Typescript -sidebar_position: 19 +sidebar_position: 4 --- import {WorkerWrapperComponent} from '@site/src/components/WorkerWrapper.mdx'; From 7cbd843bd58be7d8bd03c5fc69aad15e431092fa Mon Sep 17 00:00:00 2001 From: Tim Sekiguchi Date: Wed, 8 Jan 2025 08:14:20 -0800 Subject: [PATCH 3/4] fix: side bar position --- docs/docs/examples/broadcast.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/examples/broadcast.mdx b/docs/docs/examples/broadcast.mdx index d70e1bd4..ed5b0ac3 100644 --- a/docs/docs/examples/broadcast.mdx +++ b/docs/docs/examples/broadcast.mdx @@ -4,7 +4,7 @@ id: Simple sidebar_position: 3 ======= id: Broadcast -sidebar_position: 23 +sidebar_position: 3 >>>>>>> upstream/current --- import Tabs from '@theme/Tabs'; From 1b58587416d8ae63834e95ee3f81ed6ce7ee4074 Mon Sep 17 00:00:00 2001 From: Tim Sekiguchi Date: Wed, 8 Jan 2025 08:16:34 -0800 Subject: [PATCH 4/4] fix: side bar position --- docs/docs/examples/broadcast.mdx | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/docs/examples/broadcast.mdx b/docs/docs/examples/broadcast.mdx index d70e1bd4..26da7d6d 100644 --- a/docs/docs/examples/broadcast.mdx +++ b/docs/docs/examples/broadcast.mdx @@ -1,11 +1,6 @@ --- -<<<<<<< HEAD -id: Simple -sidebar_position: 3 -======= id: Broadcast -sidebar_position: 23 ->>>>>>> upstream/current +sidebar_position: 3 --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';