https://github.com/dozyio/js-buffered-channel
https://github.com/dozyio/js-buffered-channel
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/dozyio/js-buffered-channel
- Owner: dozyio
- Created: 2024-10-21T00:47:11.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2024-10-24T00:13:56.000Z (12 months ago)
- Last Synced: 2024-10-24T14:14:35.544Z (12 months ago)
- Language: TypeScript
- Size: 436 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# BufferedChannel
BufferedChannel is a robust TypeScript library designed to facilitate reliable and efficient message passing between the main thread and worker threads in both **Node.js** and **browser** environments. Leveraging **semaphores** for concurrency control, BufferedChannel ensures backpressure management, acknowledgment handling, and error management, making it ideal for high-throughput applications.
## Architecture
BufferedChannel operates by establishing a communication channel between the main thread and worker threads using `MessagePort`. It leverages semaphores to manage the number of concurrent messages being sent, ensuring that the system can handle backpressure gracefully.
## Installation
Install BufferedChannel via npm:
```bash
npm install buffered-channel
```
Or using Yarn:
```bash
yarn add buffered-channel
```
## Usage
BufferedChannel can be used in both **Node.js** and **browser** environments. See the [example](example) folder for a browser example.
## API Reference
### BufferedChannel
A class that manages the sending and receiving of messages between the main thread and worker threads with concurrency control and acknowledgment handling.
#### Constructor
```typescript
constructor(
port: MessagePortLike,
bufferSize: number = 1,
opts: BufferedChannelOpts = {}
)
```
- **port**: The `MessagePort` to use for communication.
- **bufferSize**: The maximum number of concurrent send operations.
- **opts**: Optional configuration options.
- **debug**: Enable debug logging.
- **name**: Name of the channel for logging purposes.
- **throwOnError**: Whether to throw errors or log them.
#### Methods
- **sendData**
Sends a data message through the channel with backpressure control.
```typescript
async sendData(
message: DataMessage,
transfer: Transferable[] = [],
timeout?: number | null
): Promise
```
- **message**: The data message to send.
- **transfer**: Transferable objects (e.g., `ArrayBuffer`) to transfer ownership.
- **timeout**: Optional timeout in milliseconds for the send operation.
- **sendAck**
Sends an acknowledgment message through the channel.
```typescript
async sendAck(
ack: AckMessage,
transfer: Transferable[] = []
): Promise
```
- **ack**: The acknowledgment message to send.
- **transfer**: Transferable objects to transfer ownership.
- **receive**
An asynchronous generator that yields incoming data messages.
```typescript
get receive(): AsyncIterableIterator>
```
- **logPerformanceMetrics**
Logs performance metrics related to message sending and acknowledgment handling.
```typescript
logPerformanceMetrics(): void
```
#### Properties (Public Getters)
- **sentMessagesCountPublic**: `number`
Number of messages sent.
- **receivedAcksCountPublic**: `number`
Number of acknowledgments received.
- **totalLatencyPublic**: `number`
Total latency accumulated from message sending to acknowledgment receipt.
- **errorCountPublic**: `number`
Number of errors encountered during message processing.
## License
This project is licensed under the [MIT License](LICENSE).