TermUI.MessageQueue (TermUI v0.2.0)

Message queue for batching multiple messages before rendering.

Multiple messages may arrive between renders. We batch messages, applying all updates before rendering once. This prevents redundant renders when multiple events arrive quickly. The batch preserves message order for deterministic updates.

Usage

# Create a queue
queue = MessageQueue.new()

# Enqueue messages
queue = MessageQueue.enqueue(queue, :increment)
queue = MessageQueue.enqueue(queue, {:set_value, 42})

# Process all messages
{messages, queue} = MessageQueue.flush(queue)

# Apply messages to state
state = Enum.reduce(messages, state, fn msg, state ->
  {new_state, _commands} = Component.update(msg, state)
  new_state
end)

Summary

Types

message()

t()

Functions

clear(queue)

Clears the queue and resets overflow count.

dequeue(queue)

Removes and returns the front message.

empty?(arg1)

Returns true if the queue is empty.

enqueue(queue, message)

Enqueues a message for processing.

enqueue_all(queue, messages)

Enqueues multiple messages at once.

flush(queue)

Removes and returns all messages from the queue.

new(opts \\ [])

Creates a new message queue.

overflow_count(message_queue)

Returns the number of dropped messages due to overflow.

peek(message_queue)

Peeks at the front message without removing it.

process(queue, initial_acc, fun)

Processes all queued messages with a function.

size(message_queue)

Returns the number of messages in the queue.

Types

message()

@type message() :: term()

t()

@type t() :: %TermUI.MessageQueue{
  max_size: pos_integer(),
  messages: :queue.queue(message()),
  overflow_count: non_neg_integer(),
  size: non_neg_integer()
}

Functions

clear(queue)

@spec clear(t()) :: t()

Clears the queue and resets overflow count.

dequeue(queue)

@spec dequeue(t()) :: {{:value, message()}, t()} | {:empty, t()}

Removes and returns the front message.

empty?(arg1)

@spec empty?(t()) :: boolean()

Returns true if the queue is empty.

enqueue(queue, message)

@spec enqueue(t(), message()) :: t()

Enqueues a message for processing.

Messages are added to the back of the queue, preserving order. If the queue is at max capacity, the message is dropped and overflow count is incremented.

enqueue_all(queue, messages)

@spec enqueue_all(t(), [message()]) :: t()

Enqueues multiple messages at once.

flush(queue)

@spec flush(t()) :: {[message()], t()}

Removes and returns all messages from the queue.

Returns {messages, empty_queue} where messages is a list in the order they were enqueued.

new(opts \\ [])

@spec new(keyword()) :: t()

Creates a new message queue.

Options

:max_size - Maximum number of messages before dropping (default: 1000)

overflow_count(message_queue)

@spec overflow_count(t()) :: non_neg_integer()

Returns the number of dropped messages due to overflow.

peek(message_queue)

@spec peek(t()) :: {:value, message()} | :empty

Peeks at the front message without removing it.

process(queue, initial_acc, fun)

@spec process(t(), acc, (message(), acc -> acc)) :: {acc, t()} when acc: term()

Processes all queued messages with a function.

Applies fun to each message and the accumulator, returning the final accumulator and empty queue.

Example

{final_state, commands, queue} = MessageQueue.process(queue, {state, []}, fn msg, {state, cmds} ->
  {new_state, new_cmds} = Component.update(msg, state)
  {new_state, cmds ++ new_cmds}
end)

size(message_queue)

@spec size(t()) :: non_neg_integer()

Returns the number of messages in the queue.