@xylabs/threads
v5.0.80
Published
Web workers & worker threads as simple as a function call
Readme
@xylabs/threads
Web workers & worker threads as simple as a function call
Reference
@xylabs/threads
Modules
index-browser
functions
### <a id="Transfer"></a>TransferCall Signature
function Transfer(transferable): TransferDescriptor;Mark a transferable object as such, so it will no be serialized and deserialized on messaging with the main thread, but to transfer ownership of it to the receiving thread.
Only works with array buffers, message ports and few more special types of objects, but it's much faster than serializing and deserializing them.
Note: The transferable object cannot be accessed by this thread again unless the receiving thread transfers it back again!
Parameters
transferable
Transferable
Array buffer, message port or similar.
Returns
See
https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast
Call Signature
function Transfer<T>(payload, transferables): TransferDescriptor;Mark transferable objects within an arbitrary object or array as being a transferable object. They will then not be serialized and deserialized on messaging with the main thread, but ownership of them will be tranferred to the receiving thread.
Only array buffers, message ports and few more special types of objects can be transferred, but it's much faster than serializing and deserializing them.
Note: The transferable object cannot be accessed by this thread again unless the receiving thread transfers it back again!
Type Parameters
T
T
Parameters
payload
T
transferables
Transferable[]
Returns
See
https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast
### <a id="isWorkerRuntime"></a>isWorkerRuntimefunction isWorkerRuntime(): boolean;Returns
boolean
### <a id="registerSerializer"></a>registerSerializerfunction registerSerializer(serializer): void;Parameters
serializer
SerializerImplementation<JsonSerializable>
Returns
void
### <a id="spawn"></a>spawnfunction spawn<Exposed>(worker, options?): Promise<ExposedAs<Exposed>>;Spawn a new thread. Takes a fresh worker instance, wraps it in a thin abstraction layer to provide the transparent API and verifies that the worker has initialized successfully.
Type Parameters
Exposed
Exposed extends WorkerFunction | WorkerModule<any> = ArbitraryWorkerInterface
Parameters
worker
Worker
Instance of Worker. Either a web worker, worker_threads worker or tiny-worker worker.
options?
timeout?
number
Init message timeout. Default: 10000 or set by environment variable.
Returns
Promise<ExposedAs<Exposed>>
interfaces
### <a id="Pool"></a>PoolThread pool managing a set of worker threads. Use it to queue tasks that are run on those threads with limited concurrency.
Type Parameters
ThreadType
ThreadType extends Thread
Methods
completed()
completed(allowResolvingImmediately?): Promise<any>;Returns a promise that resolves once the task queue is emptied. Promise will be rejected if any task fails.
Parameters
allowResolvingImmediately?
boolean
Set to true to resolve immediately if task queue is currently empty.
Returns
Promise<any>
settled()
settled(allowResolvingImmediately?): Promise<Error[]>;Returns a promise that resolves once the task queue is emptied. Failing tasks will not cause the promise to be rejected.
Parameters
allowResolvingImmediately?
boolean
Set to true to resolve immediately if task queue is currently empty.
Returns
Promise<Error[]>
events()
events(): Observable<PoolEvent<ThreadType>>;Returns an observable that yields pool events.
Returns
Observable<PoolEvent<ThreadType>>
queue()
queue<Return>(task): QueuedTask<ThreadType, Return>;Queue a task and return a promise that resolves once the task has been dequeued, started and finished.
Type Parameters
Return
Return
Parameters
task
TaskRunFunction<ThreadType, Return>
An async function that takes a thread instance and invokes it.
Returns
QueuedTask<ThreadType, Return>
terminate()
terminate(force?): Promise<void>;Terminate all pool threads.
Parameters
force?
boolean
Set to true to kill the thread even if it cannot be stopped gracefully.
Returns
Promise<void>
### <a id="QueuedTask"></a>QueuedTaskTask that has been pool.queued()-ed.
Type Parameters
ThreadType
ThreadType extends Thread
Return
Return
Properties
then()
then: <TResult1, TResult2>(onfulfilled?, onrejected?) => Promise<TResult1 | TResult2>;QueuedTask is thenable, so you can await it.
Resolves when the task has successfully been executed. Rejects if the task fails.
Attaches callbacks for the resolution and/or rejection of the Promise.
Type Parameters
TResult1
TResult1 = Return
TResult2
TResult2 = never
Parameters
onfulfilled?
The callback to execute when the Promise is resolved.
null | (value) => TResult1 | PromiseLike<TResult1>
onrejected?
The callback to execute when the Promise is rejected.
null | (reason) => TResult2 | PromiseLike<TResult2>
Returns
Promise<TResult1 | TResult2>
A Promise for the completion of which ever callback is executed.
Methods
cancel()
cancel(): void;Queued tasks can be cancelled until the pool starts running them on a worker thread.
Returns
void
### <a id="Serializer"></a>SerializerType Parameters
Msg
Msg = JsonSerializable
Input
Input = any
Methods
deserialize()
deserialize(message): Input;Parameters
message
Msg
Returns
Input
serialize()
serialize(input): Msg;Parameters
input
Input
Returns
Msg
### <a id="SerializerImplementation"></a>SerializerImplementationType Parameters
Msg
Msg = JsonSerializable
Input
Input = any
Methods
deserialize()
deserialize(message, defaultDeserialize): Input;Parameters
message
Msg
defaultDeserialize
(msg) => Input
Returns
Input
serialize()
serialize(input, defaultSerialize): Msg;Parameters
input
Input
defaultSerialize
(inp) => Msg
Returns
Msg
### <a id="TransferDescriptor"></a>TransferDescriptorType Parameters
T
T = any
Properties
[$transferable]
[$transferable]: true;send
send: T;transferables
transferables: Transferable[];namespaces
### Pool
### type-aliases
### <a id="Event"></a>Eventtype Event<ThreadType> = PoolEvent<ThreadType>;Type Parameters
ThreadType
ThreadType extends Thread = any
### <a id="EventType"></a>EventTypetype EventType = PoolEventType;type-aliases
### <a id="BlobWorker"></a>BlobWorkertype BlobWorker = typeof BlobWorkerClass;### <a id="ExposedAs"></a>ExposedAstype ExposedAs<Exposed> = Exposed extends ArbitraryWorkerInterface ? ArbitraryThreadType : Exposed extends WorkerFunction ? FunctionThread<Parameters<Exposed>, StripAsync<ReturnType<Exposed>>> : Exposed extends WorkerModule<any> ? ModuleThread<Exposed> : never;Type Parameters
Exposed
Exposed extends WorkerFunction | WorkerModule<any>
### <a id="FunctionThread"></a>FunctionThreadtype FunctionThread<Args, ReturnType> = ProxyableFunction<Args, ReturnType> & PrivateThreadProps;Type Parameters
Args
Args extends any[] = any[]
ReturnType
ReturnType = any
### <a id="JsonSerializable"></a>JsonSerializabletype JsonSerializable =
| JsonSerializablePrimitive
| JsonSerializablePrimitive[]
| JsonSerializableObject
| JsonSerializableObject[];### <a id="ModuleThread"></a>ModuleThreadtype ModuleThread<Methods> = ModuleProxy<Methods> & PrivateThreadProps;Type Parameters
Methods
Methods extends ModuleMethods = any
### <a id="Thread"></a>Threadtype Thread = ThreadType;### <a id="Worker"></a>Workertype Worker = WorkerType;variables
### <a id="BlobWorker"></a>BlobWorkerBlobWorker: typeof BlobWorker;Separate class to spawn workers from source code blobs or strings.
### <a id="DefaultSerializer"></a>DefaultSerializerconst DefaultSerializer: Serializer<JsonSerializable>;### <a id="Pool"></a>PoolPool: <ThreadType>(spawnWorker, optionsOrSize?) => WorkerPool<ThreadType> & object;Thread pool constructor. Creates a new pool and spawns its worker threads.
Type declaration
EventType
EventType: typeof PoolEventType;### <a id="Thread"></a>ThreadThread: object;Thread utility functions. Use them to manage or inspect a spawn()-ed thread.
Type declaration
errors()
errors<ThreadT>(thread): Observable<Error>;Return an observable that can be used to subscribe to all errors happening in the thread.
Type Parameters
ThreadT
ThreadT extends Thread
Parameters
thread
ThreadT
Returns
Observable<Error>
events()
events<ThreadT>(thread): Observable<WorkerEvent>;Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging.
Type Parameters
ThreadT
ThreadT extends Thread
Parameters
thread
ThreadT
Returns
Observable<WorkerEvent>
terminate()
terminate<ThreadT>(thread): Promise<void>;Terminate a thread. Remember to terminate every thread when you are done using it.
Type Parameters
ThreadT
ThreadT extends Thread
Parameters
thread
ThreadT
Returns
Promise<void>
### <a id="Worker"></a>WorkerWorker: typeof WorkerImplementation;Worker implementation. Either web worker or a node.js Worker class.
index-node
functions
### <a id="isWorkerRuntime"></a>isWorkerRuntimefunction isWorkerRuntime(): boolean;Returns
boolean
type-aliases
### <a id="BlobWorker"></a>BlobWorkertype BlobWorker = typeof BlobWorkerClass;### <a id="Worker"></a>Workertype Worker = WorkerType;variables
### <a id="BlobWorker"></a>BlobWorkerBlobWorker: typeof BlobWorker;Separate class to spawn workers from source code blobs or strings.
### <a id="Worker"></a>WorkerWorker: typeof WorkerImplementation;Worker implementation. Either web worker or a node.js Worker class.
Part of sdk-js
Maintainers
License
See the LICENSE file for license details