3 | 4 |
5 | 
7 | 8 |
3 |
5 |
7 | 
30 | -no data-129 |
Start the engine.
77 |Internally, configures the job processing functions, starts the load balancer and launches a first Web Worker.
78 | 79 |A Promise for the current engine instance. Can be used for chaining multiple instance method calls.
80 |The function which will process all jobs sent to this engine instance.
87 |Optional initFunction: WorkerInitFunction<unknown>A function for setting up a Web Worker environment before it starts processing jobs. May be sync or async.
91 |Optional initArgs: WorkerFunctionTransferArgsDynamic data to send to the initFunction to set up the environment of new Web Worker instances.
95 |Schedule, execute and get the results of a job.
105 | 106 |A Promise that will be fulfilled with T or an empty resolve when the job has been processed.
107 |If the job threw an error when processing, the Promise will reject with an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#Instance_properties) object containing the job's error message.
108 | The return type of a successful job - meaning what the WorkerFunction will return, with Transferable objects inlined.
Rest ...args: WorkerFunctionTransferArgsStart as much WebWorkers as currently recommended by the browser, or allowed by afterburner.
144 |You should use this only if you know you will have to process many jobs and want to ensure that the engine is fully revved up. 145 | In most cases the automatic "temperature" adjustement will provide a good balance between performance and memory footprint.
146 |You should immediatly follow this call with your actual runJob calls, otherwise the engine might start to cool itself down automatically.
147 | 148 |A Promise for the current engine instance. Can be used for chaining multiple instance method calls.
149 |WARNING: Possibly unstable.
171 |Overrides the maximum number of WebWorkers Rinzler will attempt to spawn.
172 |Normally this is retrieved from navigator.hardwareConcurrency, which is a browser-provided indicator of how many Workers a browsing context should use, with respect to the browser's own limitations and the number of available CPU cores on the host hardware.
By going beyond that number you may crash the browser tab, get unexpected errors, or a considerable boost in parallelized performance. 174 | Aim for the moon, right?
175 | 176 |A Promise for the current engine instance. Can be used for chaining multiple instance method calls.
177 |The new maximum number of WebWorkers this instance will manage. If set to lower than the current max, extra Workers will be gracefully shut down to respect the new limit.
184 |Generated using TypeDoc
17 |
19 |
21 | Rinzler is a turboramjet parallel processing engine for the browser.
It speeds up your web application by allowing recurring functions to execute in parallel taking full advantage of the host system's available processing power.
26 |Check out the full docs, try the interactive demo or read on for a high-level overview and a quick start guide.
27 | 28 | 29 |Most devices have a processor unit (CPU) with multiple cores, meaning that they are capable of working on multiple tasks at the same time. 32 | Modern operating systems with multi-tasking functionality (e.g the ability to run & manage multiple programs/windows) have a special component called a thread scheduler.
33 |Each program you run can have multiple threads, and the scheduler's job is to distribute threads to the CPU's cores.
34 |A web page's JavaScript normally executes on a single thread, meaning it will never use more than one CPU core. In most cases this is fine, and also helps ensures other tabs in the user's browser, or other programs, can also keep running smoothly.
35 |However, some web applications might need to process a lot of data, or do a lot of expensive computing, and therefore can benefit from spreading work across all the available cores of the host machine.
36 |Rinzler is a tool to do just that, in the simplest way possible - just define functions to run in parallel, and use native ES6 Promises to run & manage parallelized jobs.
37 |
39 | Internally, it leverages Web Workers, which is a standard Web API for executing code in separate threads. It also includes a custom scheduler that handles spawning new Workers when necessary, sharing work between them, and shutting them down when they're not used.
42 | 43 | 44 |npm i rinzler-engine
47 | Both ES & UMD modules are bundled, as well as TypeScript types, so you should be all set.
49 |Rinzler targets browsers with WebWorkers and Promises support (check the browserslistrc). Most modern evergreen browsers, including Edge, should be compatible.
50 | 51 | 52 |In the following example, we will set up a Rinzler-accelerated app that decodes ArrayBuffers of text.
In most real-life use cases, the job processing you will offload to Rinzler will depend on some dynamic variable in the context of your app: in this example, the original encoding of the text we want to decode.
60 |The processing functions you will pass to Rinzler cannot contain references to external variables, because their source code will be extracted and printed in the Worker instances' source.
61 |To work around this limitation, Rinzler allows you to setup an "initialization" function and pass it a payload. This function & payload will be run on each new Web Worker instance before it starts processing your jobs.
62 |const initOptions = [{
encoding: 'utf-8' // We're just going to print this here, but in real life you would probably get this option from user input.
}]
function init(options) {
// This will run once in new Web Worker contexts. We can use the `self` global to store data for later.
self.params = {
encoding: options.encoding
}
}
63 | We need to setup a function that will actually do the job we need to parallelize, in this case, decoding text buffers.
69 |function processJob(message) {
// We expect to receive an object with an `encodedText` prop that is an ArrayBuffer.
const buffer = message.encodedText
// Get the encoding parameter we stored earlier, or default to ASCII.
const encoding = self.params?.encoding || 'ascii'
const text = new TextDecoder(encoding).decode(buffer)
return [text]
}
70 | Next we will import Rinzler and start the engine by passing the function(s) we defined above.
76 |The following code is written for asynchronous contexts, but you can translate it to synchronous by using .then() with a callback instead of await.
import RinzlerEngine from 'rinzler-engine'
const engine = await new RinzlerEngine().configureAndStart(processJob, init, initOptions)
78 | Now we can actually run jobs! We'll use the runJob() method, which returns a Promise that will resolve when the job is completed.
Since we need to pass an ArrayBuffer, we'll use the second argument as a Transferable[] - much like in the native worker.postMessage() API.
// Encode some text to try our decoder with
const encodedText = new TextEncoder('utf-8').encode('hello Rinzler!')
// Pass the encoded text to our decoding engine
const decodedResult = await engine.runJob({ encodedText }, [encodedText])
console.log(decodedResult) // "hello Rinzler!"
86 | You can start as many jobs as you want, and take full advantage of ES6's asynchronous syntax (for example, Promise.all()).
If you use TypeScript, you can pass return types with the runJob<T>(): Promise<T> signature.
Under the hood, Rinzler will take care of launching Web Workers, balancing their load, and gracefully shutting them down when needed to reduce your app's memory footprint.
90 | 91 | 92 |Web Worker instances will be destroyed by the browser when the page exits, but you can schedule a graceful shutdown yourself using engine.shutdown(), which returns a Promise that will resolve once all currently active jobs have completed and all workers have been stopped.
Rinzler is licensed under the MIT License. You may integrate it in commercial applications.
100 |Generated using TypeDoc
Generated using TypeDoc
Anything passed in runJob, with Transferable objects inlined.
The function which will process all jobs sent to this engine instance. May be sync or async. 34 | Worker functions cannot use variables defined outside of their block, because the function code itself is inlined 35 | and written to the Web Worker source code.
36 |You can safely throw errors in this function as they will be catched and bubbled up from the engine.
37 |Optional message: TGenerated using TypeDoc
Interface for passing messages and Transferable data to Web Worker instances.
See DedicatedWorkerGlobalScope.postMessage() for more details.
Generated using TypeDoc
Anything passed as initArgs in configureAndStart, with Transferable objects inlined.
A function for setting up a Web Worker environment before it starts processing jobs. May be sync or async. 34 | Worker functions cannot use variables defined outside of their block, because the function code itself is inlined 35 | and written to the Web Worker source code.
36 |You should pass any dynamic data that won't change between jobs using initArgs in configureAndStart,
37 | and parse/use them in the init function.
If you need to store some global state to be used later when processing jobs, you can write a property to self, which will be a DedicatedWorkerGlobalScope.
39 | But be careful not to overwrite any browser-initialized properties in there!
Optional message: TGenerated using TypeDoc
Welcome to Rinzler's full documentation.
22 | 23 |If you're just getting started, check out the Quick Start guide.
24 |This page describes the interface of an instanted RinzlerEngine class, which you can access like so:
25 | 27 |