View Source emmap_queue (emmap v2.1.1)

Persistent FIFO queue The FIFO queue can be used as a persistent container of messages with constant time push and pop operations. Additionally, this module provides a gen_server API, which wraps the queue for use in multi-process applications. The queue is stored in a memory-mapped file, and it automatically grows if the messages are not dequeued from the queue. Messages stored in the queue can be compressed using variable compression level controlled by the argument to the push/3 function. See test cases at the end of this module for sample use cases.

Link to this section Summary

Functions

Close a previously open queue.

Dequeue a message from the queue

Enqueue a message to the queue

Erase the content of the queue. All messages in the queue are discarded!

Asynchronously flush the modified memory used by the queue to disk. See notes of emmap:sync/1. This call is optional.

Return queue info as a map

Peek a message from the queue without dequeuing it

Returns true if the queue is empty.

Get queue length. This function has a linear-time complexity.

Get queue metadata

Open a memory mapped queue.

Inspect all messages in the queue iteratively by passing them to a custom lambda function. The Fun takes a message and state and returns a {cont, State} to continue or {halt, State} to abort.

Peek the last written term at the back of the FIFO queue without removing it. This function has a constant-time complexity.

Peek the next awaiting term from the head of the FIFO queue without popping it. This function has a constant-time complexity.

Pop a term from the queue. This function has a constant-time complexity.

Pop messages from the queue by passing them to a custom lambda function. The Fun takes a message and state and returns a {cont, State} to continue or {halt, State} to abort.

Pop a term from the queue and reclaim queue's memory if the queue is empty. This function has a constant-time complexity.

Purge queue. It is a constant time operation.

Push a term to the queue. This function has a constant-time complexity.

Push a term to the queue. This function has a constant-time complexity. Compression is the compression level from 0 to 9, where 0 is no compression.

Inspect all messages in the queue iteratively in the reverse order by passing them to a custom lambda function. The Fun takes a message and state and returns a {cont, State} to continue or {halt, State} to abort.

Start a queue process. Name - name of the registered process. Filename - name of the memory mapped file. SegmSize - size of the memory mapped segment (can be 0 for an existing file). Opts - see emmap:open_options().

Dequeue a message from the queue. The function returns Res where Res is the result of evaluating the Fun with the poped element from the queue. If the Fun throws an exception, the exception if propagated to the caller.

Evaluate the Fun function on the next term in the queue. If the function doesn't raise an exception, pop the term from the queue, otherwise leave the queue unmodified. This function has a constant-time complexity. It returns the result of evaluating Fun.

Evaluate the Fun function on the next term in the queue. If the function doesn't raise an exception, pop the term from the queue, otherwise leave the queue unmodified. This function has a constant-time complexity. It returns the result of evaluating Fun.

Link to this section Types

Link to this section Functions

-spec close(queue()) -> ok.

Close a previously open queue.

Dequeue a message from the queue

Enqueue a message to the queue

Erase the content of the queue. All messages in the queue are discarded!

-spec flush(queue()) -> ok.

Asynchronously flush the modified memory used by the queue to disk. See notes of emmap:sync/1. This call is optional.

Link to this function

handle_call(_, From, State)

View Source
-spec info(atom()) -> map().

Return queue info as a map

Peek a message from the queue without dequeuing it

Returns true if the queue is empty.

Get queue length. This function has a linear-time complexity.

-spec metadata(queue()) ->
            #{head => integer(), tail => integer(), next_tail => integer(), size => integer()}.

Get queue metadata

Link to this function

open(Filename, Size, Opts)

View Source
-spec open(binary() | list(), integer(), list()) -> {ok, queue()} | {error, term()}.

Open a memory mapped queue.

Inspect all messages in the queue iteratively by passing them to a custom lambda function. The Fun takes a message and state and returns a {cont, State} to continue or {halt, State} to abort.

Peek the last written term at the back of the FIFO queue without removing it. This function has a constant-time complexity.

Peek the next awaiting term from the head of the FIFO queue without popping it. This function has a constant-time complexity.

Pop a term from the queue. This function has a constant-time complexity.

Pop messages from the queue by passing them to a custom lambda function. The Fun takes a message and state and returns a {cont, State} to continue or {halt, State} to abort.

Pop a term from the queue and reclaim queue's memory if the queue is empty. This function has a constant-time complexity.

-spec purge(queue()) -> boolean().

Purge queue. It is a constant time operation.

Push a term to the queue. This function has a constant-time complexity.

Link to this function

push(Mem, Term, Compression)

View Source

Push a term to the queue. This function has a constant-time complexity. Compression is the compression level from 0 to 9, where 0 is no compression.

Inspect all messages in the queue iteratively in the reverse order by passing them to a custom lambda function. The Fun takes a message and state and returns a {cont, State} to continue or {halt, State} to abort.

Link to this function

start_link(Name, Filename, SegmSize, Opts)

View Source

Start a queue process. Name - name of the registered process. Filename - name of the memory mapped file. SegmSize - size of the memory mapped segment (can be 0 for an existing file). Opts - see emmap:open_options().

Link to this function

terminate(Reason, State)

View Source

Dequeue a message from the queue. The function returns Res where Res is the result of evaluating the Fun with the poped element from the queue. If the Fun throws an exception, the exception if propagated to the caller.

Evaluate the Fun function on the next term in the queue. If the function doesn't raise an exception, pop the term from the queue, otherwise leave the queue unmodified. This function has a constant-time complexity. It returns the result of evaluating Fun.

Link to this function

try_pop_and_purge(Mem, Fun)

View Source

Evaluate the Fun function on the next term in the queue. If the function doesn't raise an exception, pop the term from the queue, otherwise leave the queue unmodified. This function has a constant-time complexity. It returns the result of evaluating Fun.