@lzptec/job-system v0.5.0-0
@lzptec/job-system
A library to implement a Job System in nodejs using worker_threads.
Installation
npm
npm i @lzptec/job-systempnpm
pnpm i @lzptec/job-systemUsage
The following examples uses typescript
⚠ Version 1.0.0 will be the first Stable Release and the Usage will change drastically.
Basic
import { ThreadPool } from '@lzptec/job-system';
const threadPool = new ThreadPool();
const job = ({ a, b }) => a * b;
// When we schedule a Job the return will be a JobHandle<T>.
const jobHandle = await threadPool.schedule(job, { a: 2, b: 5 });
// OR
const jobHandle = await threadPool.schedule(({ a, b }) => a * b, { a: 2, b: 5 });
// If we want to get the result, we need to call complete()
const result = await jobHandle.complete();
console.log(result); // 10Advanced
import { ThreadPool } from '@lzptec/job-system';
const threadPool = new ThreadPool();
// When we schedule a Job the return will be a JobHandle<T>.
const jobHandle = threadPool.schedule(({ a, b }) => a * b, { a: 2, b: 5 });
// If we want to get the result, we need to call complete()
const result = await jobHandle.complete();
console.log(result); // 10
// We can use the JobHandle<T> as Dependency to another job, this will ensure that a job run only after the dependency job.
const job1Handle = threadPool.schedule((data) => console.log(`Hello from Job n${data}`), 1);
const job2Handle = threadPool.schedule((data) => console.log(`Hello from Job n${data}`), 2, [job1Handle]);
await job2Handle.complete();
// Console
// -> Hello from Job n1
// -> Hello from Job n2API
ThreadPool(settings?)
Returns a new ThreadPool.
settings.maxWorkers
Optional
Type: number
Default: 0
Defines the maximum number of workers the Job System can instantiate.
If it is 0 the number of workers will be automatically defined using the following logic:
const cpuSize = os.cpus().length;
const maxWorkers = Math.max(1, cpuSize >= 6 ? (cpuSize / 2) : cpuSize - 1);Important: If a number smaller than
0is set, an error will occur!
settings.minWorkers
Optional
Type: number
Default: 0
Defines the minimum number of workers the Job System will instantiate on startup.
Important: If the value is bigger than
maxWorkersit will usemaxWorkersinstead.
settings.idleTimeout
Optional
Type: number
Default: 0
Defines the maximum idle time of a worker inside the pool, after this time the worker will be terminated. The timer resets if a new work is schedule to that worker.
Important: If the value is set to
0the Worker stays alive until theshutdown()method is called.
settings.useMainThread
Optional
Type: boolean
Default: false
Use the main thread if no worker is available.
setSettings(settings)
Set new settings on this pool.
settings
Required
Type: ThreadPoolSettings
New settings.
getSettings()
Return: ThreadPoolSettings
Return the current settings of this pool.
schedule(job, data?, dependencies?, transferList?)
Returns: JobHandle
Add a job to the execution queue
job
Required
Type: Function
The function that must be executed in one of the threads.
data
Optional
Type: SerializableValue | undefined
Default: undefined
The data that will be sent to the Job.
dependencies
Optional
Type: JobHandle[] | undefined
Default: undefined
A list of depedencies, use it to ensure that a job executes after all the dependencies has completed execution.
transferList
Optional
Type: Transferable[] | undefined
Default: undefined
A list of transferable objects like ArrayBuffers to be transferred to the receiving worker thread.
shutdown()
Shutdown the Thread Pool, it will wait for all jobs to complete.
Important: If the
schedulemethod is called aftershutdown, an error will occur!
JobHandle extends EventEmitter
JobHandle.
JobHandle.complete()
Returns a Promise that resolves when the job completes.
JobHandle.state
Returns the current job state.
Events
success | error | complete
Notes
Documentation will be updated over time.