User Manual
Hamok / HamokEmitter / HamokMap / HamokQueue / HamokRecord / HamokRemoteMap
Table of Contents
Overview
HamokQueue is a class that implements a replicated queue with event-driven notifications.
It supports typical queue operations like push, pop, and peek.
Create a HamokQueue instance
You need a Hamok to create a HamokQueue instance. Here is how you can create a HamokQueue instance:
const queue = hamok.createQueue<string>({
queueId: "exampleQueue",
});
Configuration
You can pass the following configuration options at the time of creating a HamokQueue:
const queue = hamok.createQueue<string>({
/**
* The unique identifier for the queue.
*/
queueId: "queue1",
/**
* Optional. The timeout duration in milliseconds for requests.
*
* DEFAULT: 5000
*/
requestTimeoutInMs: 5000,
/**
* Optional. The maximum number of keys allowed in request or response messages.
*
* DEFAULT: 0 means infinity
*/
maxOutboundMessageKeys: 1000,
/**
* Optional. The maximum number of values allowed in request or response messages.
*
* DEFAULT: 0 means infinity
*/
maxOutboundMessageValues: 100,
/**
* Optional. A base map to be used as the initial state of the map.
*
* DEFAULT: a new and empty BaseMap instance
*/
baseMap: new BaseMap<K, V>(),
/**
* Optional. The length of byte array used for queue keys.
* This also affects the maximum number of items ever pushed into the queue.
* Can be 2, 4, or 8 bytes.
*
* Default is 4, which allows for 4.3 billion items in the queue during it's lifetime.
*/
lengthOfBytesQueueKeys: 4,
/**
* Optional. A codec for encoding and decoding items in the queue.
*
* DEFAULT: JSON codec
*/
codec: {
encode: (item: T) => Buffer.from(JSON.stringify(item)),
decode: (data: Uint8Array) => JSON.parse(Buffer.from(data).toString()),
},
});
API Reference
HamokQueue<T> Class
A class for managing a distributed queue with event-driven capabilities.
Properties
id:string- The unique identifier of the queue.empty:boolean- Indicates whether the queue is empty.size:number- Returns the number of elements in the queue.connection:HamokConnection<number, T>- The connection used by the queue.baseMap:BaseMap<number, T>- The base map used for storing the queue elements.closed:boolean- Indicates whether the queue is closed.ready:Promise<void>- A promise that resolves when the queue is initialized and ready to use.
Methods
- push(
...values: T[]):Promise<void>- Pushes values onto the queue. - pop():
Promise<T | undefined>- Removes and returns the value at the front of the queue. - peek():
T | undefined- Returns the value at the front of the queue without removing it. - clear():
Promise<void>- Clears the queue. - close():
void- Closes the queue and releases any held resources.
Events
empty: Emitted when the queue becomes empty.not-empty: Emitted when the queue transitions from empty to not empty.add: Emitted when an item is added to the queue.remove: Emitted when an item is removed from the queue.close: Emitted when the queue is closed.
Example Usage
const queue = new HamokQueue(connection, baseMap);
queue.on("add", (value) => {
console.log(`Added value: ${value}`);
});
queue.on("remove", (value) => {
console.log(`Removed value: ${value}`);
});
queue
.push("item1", "item2")
.then(() => {
return queue.pop();
})
.then((value) => {
console.log(`Popped value: ${value}`);
});
queue.clear().then(() => {
console.log("Queue cleared");
});
queue.close();
Examples
FAQ
What is the difference between the add event and the push method?
The push method is used to add one or more items to the end of the queue programmatically. When items are added to the queue using the push method, the add event is emitted. The add event acts as a notification to let listeners know that an item has been added to the queue.
// Listening to the add event means any instance anywhere added an item to the queue
queue.on("add", (item) => console.log(`Added to the queue: ${item}`));
// Using push method to add items to the queue
await queue.push("item1", "item2");
What is the difference between the remove event and the pop method?
The pop method is used to remove and return the item at the front of the queue programmatically. When an item is removed from the queue using the pop method, the remove event is emitted. The remove event acts as a notification to let listeners know that an item has been removed from the queue.
// Listening to the remove event so means that any instance anywhere removed an item from the queue
queue.on("remove", (item) => console.log(`Removed from the queue: ${item}`));
// Using pop method to remove an item from the queue
const item = await queue.pop();
console.log("Popped item:", item);
Can I use HamokQueue for real-time messaging?
HamokQueue is designed for replicated storage and is suitable for tasks like configuration sharing, leader election, and other significant signals and data sharing within a cluster. While it can be used for real-time messaging, it might not be as optimized as dedicated messaging systems like Redis or Kafka for high-throughput real-time message passing. So the answer is yes and no. you can use it for real-time messaging, but it might not be the best choice for high-throughput messaging, not mentioned about memory optimization.
How can I check if the queue is empty?
You can check if the queue is empty by using the empty property of the HamokQueue instance.
if (queue.empty) {
console.log("The queue is empty");
} else {
console.log("The queue is not empty");
}
Can I iterate over the items in the queue?
Yes, you can iterate over the items in the queue using the iterator provided by the [Symbol.iterator]() method.
for (const item of queue) {
console.log("Iterated item:", item);
}