diff options
Diffstat (limited to 'docs/runtime/workers.md')
-rw-r--r-- | docs/runtime/workers.md | 251 |
1 files changed, 0 insertions, 251 deletions
diff --git a/docs/runtime/workers.md b/docs/runtime/workers.md deleted file mode 100644 index d39a8b130..000000000 --- a/docs/runtime/workers.md +++ /dev/null @@ -1,251 +0,0 @@ -## Workers - -Deno supports -[`Web Worker API`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker). - -Workers can be used to run code on multiple threads. Each instance of `Worker` -is run on a separate thread, dedicated only to that worker. - -Currently Deno supports only `module` type workers; thus it's essential to pass -the `type: "module"` option when creating a new worker. - -Use of relative module specifiers in the main worker are only supported with -`--location <href>` passed on the CLI. This is not recommended for portability. -You can instead use the `URL` constructor and `import.meta.url` to easily create -a specifier for some nearby script. Dedicated workers, however, have a location -and this capability by default. - -```ts -// Good -new Worker(new URL("./worker.js", import.meta.url).href, { type: "module" }); - -// Bad -new Worker(new URL("./worker.js", import.meta.url).href); -new Worker(new URL("./worker.js", import.meta.url).href, { type: "classic" }); -new Worker("./worker.js", { type: "module" }); -``` - -### Instantiation permissions - -Creating a new `Worker` instance is similar to a dynamic import; therefore Deno -requires appropriate permission for this action. - -For workers using local modules; `--allow-read` permission is required: - -**main.ts** - -```ts -new Worker(new URL("./worker.ts", import.meta.url).href, { type: "module" }); -``` - -**worker.ts** - -```ts -console.log("hello world"); -self.close(); -``` - -```shell -$ deno run main.ts -error: Uncaught PermissionDenied: read access to "./worker.ts", run again with the --allow-read flag - -$ deno run --allow-read main.ts -hello world -``` - -For workers using remote modules; `--allow-net` permission is required: - -**main.ts** - -```ts -new Worker("https://example.com/worker.ts", { type: "module" }); -``` - -**worker.ts** (at https[]()://example.com/worker.ts) - -```ts -console.log("hello world"); -self.close(); -``` - -```shell -$ deno run main.ts -error: Uncaught PermissionDenied: net access to "https://example.com/worker.ts", run again with the --allow-net flag - -$ deno run --allow-net main.ts -hello world -``` - -### Using Deno in worker - -> This is an unstable Deno feature. Learn more about -> [unstable features](./stability.md). - -By default the `Deno` namespace is not available in worker scope. - -To enable the `Deno` namespace pass `deno.namespace = true` option when creating -new worker: - -**main.js** - -```ts -const worker = new Worker(new URL("./worker.js", import.meta.url).href, { - type: "module", - deno: { - namespace: true, - }, -}); -worker.postMessage({ filename: "./log.txt" }); -``` - -**worker.js** - -```ts -self.onmessage = async (e) => { - const { filename } = e.data; - const text = await Deno.readTextFile(filename); - console.log(text); - self.close(); -}; -``` - -**log.txt** - -``` -hello world -``` - -```shell -$ deno run --allow-read --unstable main.js -hello world -``` - -### Specifying worker permissions - -> This is an unstable Deno feature. Learn more about -> [unstable features](./stability.md). - -The permissions available for the worker are analogous to the CLI permission -flags, meaning every permission enabled there can be disabled at the level of -the Worker API. You can find a more detailed description of each of the -permission options [here](../getting_started/permissions.md). - -By default a worker will inherit permissions from the thread it was created in, -however in order to allow users to limit the access of this worker we provide -the `deno.permissions` option in the worker API. - -- For permissions that support granular access you can pass in a list of the - desired resources the worker will have access to, and for those who only have - the on/off option you can pass true/false respectively. - - ```ts - const worker = new Worker(new URL("./worker.js", import.meta.url).href, { - type: "module", - deno: { - namespace: true, - permissions: { - net: [ - "https://deno.land/", - ], - read: [ - new URL("./file_1.txt", import.meta.url), - new URL("./file_2.txt", import.meta.url), - ], - write: false, - }, - }, - }); - ``` - -- Granular access permissions receive both absolute and relative routes as - arguments, however take into account that relative routes will be resolved - relative to the file the worker is instantiated in, not the path the worker - file is currently in - - ```ts - const worker = new Worker( - new URL("./worker/worker.js", import.meta.url).href, - { - type: "module", - deno: { - namespace: true, - permissions: { - read: [ - "/home/user/Documents/deno/worker/file_1.txt", - "./worker/file_2.txt", - ], - }, - }, - }, - ); - ``` - -- Both `deno.permissions` and its children support the option `"inherit"`, which - implies it will borrow its parent permissions. - - ```ts - // This worker will inherit its parent permissions - const worker = new Worker(new URL("./worker.js", import.meta.url).href, { - type: "module", - deno: { - namespace: true, - permissions: "inherit", - }, - }); - ``` - - ```ts - // This worker will inherit only the net permissions of its parent - const worker = new Worker(new URL("./worker.js", import.meta.url).href, { - type: "module", - deno: { - namespace: true, - permissions: { - env: false, - hrtime: false, - net: "inherit", - plugin: false, - read: false, - run: false, - write: false, - }, - }, - }); - ``` - -- Not specifying the `deno.permissions` option or one of its children will cause - the worker to inherit by default. - - ```ts - // This worker will inherit its parent permissions - const worker = new Worker(new URL("./worker.js", import.meta.url).href, { - type: "module", - }); - ``` - - ```ts - // This worker will inherit all the permissions of its parent BUT net - const worker = new Worker(new URL("./worker.js", import.meta.url).href, { - type: "module", - deno: { - namespace: true, - permissions: { - net: false, - }, - }, - }); - ``` - -- You can disable the permissions of the worker all together by passing `"none"` - to the `deno.permissions` option. - - ```ts - // This worker will not have any permissions enabled - const worker = new Worker(new URL("./worker.js", import.meta.url).href, { - type: "module", - deno: { - namespace: true, - permissions: "none", - }, - }); - ``` |