hare v0.2.2 Hare.Core.Queue

This module defines the Hare.Core.Queue struct that represents an queue and holds a channel to interact with it.

Summary

Functions

Acks a message given its meta

Binds the queue to a existing exchange

It cancels message consumption if the queue is consuming. Otherwise it does nothing

Delegates to consume/3 with caller’s pid and empty options

When the second argument is a pid it delegates to consume/3 with that pid and empty options

Consumes messages from the given queue through its associated channel

Declares a server-named queue on the AMQP server through the given channel, and builds a queue struct associated to that channel

Declares a queue on the AMQP server through the given channel, and builds a queue struct associated to that channel

Declares a queue with the given name and options through the given channel, and builds a queue struct associated to that channel

Deletes the given queue

Gets a message from the queue through the associated channel

When a pid consumes a queue, it receives status messages and actual queue messages as elixir messages. The format of those messages depends on the adapter

Nacks a message given its meta

Builds a queue with the given name associated to the given channel

Purges all messages on the given queue

Redeliver all unacknowledged messages from a specified queue

Rejects a message given its meta

Unbinds the queue from a existing exchange

Types

chan()
chan() :: Hare.Core.Chan.t
consumer_tag()
consumer_tag() :: Hare.Adapter.consumer_tag
consuming()
consuming() :: boolean
consuming_pid()
consuming_pid() :: pid
meta()
meta() :: Hare.Adapter.meta
name()
opts()
opts() :: Hare.Adapter.opts
payload()
payload() :: Hare.Adapter.payload
t()
t() :: %Hare.Core.Queue{chan: chan, consumer_tag: consumer_tag | nil, consuming: consuming, consuming_pid: consuming_pid | nil, name: name}

Functions

ack(queue, meta, opts \\ [])
ack(t, meta, opts) :: :ok

Acks a message given its meta.

bind(queue, exchange_or_name, opts \\ [])
bind(t, Hare.Core.Exchange.t | binary, opts) :: :ok

Binds the queue to a existing exchange.

The second argument can be an exchange (Hare.Core.Exchange struct) or a binary representing the name of the exchange to bind to.

The exchange is supposed to be already declared, therefore it is recommended to declare the exchange with Exchange.declare/4 and use the resulting exchange as bind/3 second argument.

cancel(queue, opts \\ [])
cancel(t, opts) :: {:ok, t}

It cancels message consumption if the queue is consuming. Otherwise it does nothing.

consume(queue)
consume(t) :: {:ok, t} | {:error, :already_consuming}

Delegates to consume/3 with caller’s pid and empty options.

consume(queue, pid)
consume(t, pid | opts) ::
  {:ok, t} |
  {:error, :already_consuming}

When the second argument is a pid it delegates to consume/3 with that pid and empty options.

Otherwise the second argument is interpreted as options. It delegates to consume/3 with the caller’s pid and the given options.

consume(queue, pid, opts)
consume(t, pid, opts) ::
  {:ok, t} |
  {:error, :already_consuming}

Consumes messages from the given queue through its associated channel.

When a queue is being consumed by a pid status messages and actual queue messages are sent to that pid as elixir messages.

The format of that messages depends on the adapter. Because of this reason the handle/2 function is provided. It asks the adapter whether the given message is a known AMQP message and returns it in a predictable format. See Hare.Conn.Queue.handle/2 for more information.

Each queue struct must be consumed by only one pid. For another pid to consume the same queue, another queue struct must be built.

declare(chan)
declare(chan) ::
  {:ok, info :: term, t} |
  {:error, reason :: term}

Declares a server-named queue on the AMQP server through the given channel, and builds a queue struct associated to that channel.

declare(chan, name)
declare(chan, name | opts) ::
  {:ok, info :: term, t} |
  {:error, reason :: term}

Declares a queue on the AMQP server through the given channel, and builds a queue struct associated to that channel.

When the second argument is a binary, it is interpreted as the name of the queue. A queue with that name and no options is declared.

Otherwise, the second argument is interpreted as the options to declare the exchange. A server-named queue with that options is declared.

# Declares a queue named: foo
{:ok, _info, queue} = Queue.declare(chan, "foo")
# => %Queue{name: "foo", chan: chan}

# Declares an exclusive, server-named queue
{:ok, _info, queue} = Queue.declare(chan, exclusive: true)
# => %Queue{name: "nas=eq3as.ndf?ea", chan: chan}
declare(chan, name, opts)
declare(chan, name, opts) ::
  {:ok, info :: term, t} |
  {:error, reason :: term}

Declares a queue with the given name and options through the given channel, and builds a queue struct associated to that channel.

delete(queue, opts \\ [])

Deletes the given queue.

get(queue, opts \\ [])
get(t, opts) ::
  {:empty, info :: term} |
  {:ok, payload, meta}

Gets a message from the queue through the associated channel.

handle(queue, message)
handle(t, message :: term) ::
  {:consume_ok, meta} |
  {:deliver, payload, meta} |
  {:cancel_ok, meta} |
  {:cancel, meta} |
  {:return, payload, meta} |
  :unknown

When a pid consumes a queue, it receives status messages and actual queue messages as elixir messages. The format of those messages depends on the adapter.

This function provides a way to tell whether the received message is a known AMQP message.

It can return 4 different values for a given message:

  • {:consume_ok, meta} - The process has been registered as a consumer and messages from the queue will be sent
  • {:deliver, payload, meta} - This is an actual queue message
  • {:cancel_ok, meta} - The process has been unregistered as a consumer
  • {:cancel, meta} - The process has been unexpectedly unregistered as a consumer by server
  • :unknown - The message is not a known AMQP message
nack(queue, meta, opts \\ [])
nack(t, meta, opts) :: :ok

Nacks a message given its meta.

new(chan, name)
new(chan, name) :: t

Builds a queue with the given name associated to the given channel.

The queue is supposed to already be declared on the server in order to use it to run functions like publish/4.

Is recommended to always use declare/3 instead of new/2 in order to ensure the queue is already declared as expected before using it.

purge(queue)
purge(t) :: {:ok, info :: term}

Purges all messages on the given queue

recover(queue, opts \\ [])

Redeliver all unacknowledged messages from a specified queue.

It delegates the given options to the underlying adapter. The format of these options depends on the adapter.

reject(queue, meta, opts \\ [])
reject(t, meta, opts) :: :ok

Rejects a message given its meta.

unbind(queue, exchange_or_name, opts \\ [])
unbind(t, Hare.Core.Exchange.t | binary, opts) :: :ok

Unbinds the queue from a existing exchange.

The second argument can be an exchange (Hare.Core.Exchange struct) or a binary representing the name of the exchange to bind to.

The exchange is supposed to be already declared, therefore it is recommended to declare the exchange with Exchange.declare/4 and use the resulting exchange as unbind/3 second argument.