gen_queue v0.1.3 GenQueue behaviour View Source
A behaviour module for implementing queues.
GenQueue relies on adapters to handle the specifics of how the queues are run. At its most simple, this can mean simple FIFO queues. At its most advanced, this can mean full async job queues with retries and backoffs. By providing a standard interface for such tools - ease in switching between different implementations is assured.
Example
The GenQueue behaviour abstracts the common queue interactions. Developers are only required to implement the callbacks and functionality they are interested in via adapters.
Let’s start with a simple FIFO queue:
defmodule Queue do
use GenQueue
end
# Start the queue
Queue.start_link()
# Push items into the :foo queue
Queue.push(:hello)
#=> {:ok, :hello}
Queue.push(:world)
#=> {:ok, :world}
# Pop items from the :foo queue
Queue.pop()
#=> {:ok, :hello}
Queue.pop()
#=> {:ok, :world}
We start our enqueuer by calling start_link/1
. This call is then
forwarded to our adapter. In this case, we dont specify an adapter
anywhere, so it defaults to the simple FIFO queue implemented with
the included GenQueue.SimpleAdapter
.
We can then add items into our simple FIFO queues with push/2
, as
well as remove them with pop/1
.
use GenQueue and adapters
As we can see from above - implementing a simple queue is easy. But we can further extend our queues by creating our own adapters or by using external libraries. Simply specify the adapter name in your config.
config :my_app, MyApp.Enqueuer, [
adapter: GenQueue.MyAdapter
]
defmodule MyApp.Enqueuer do
use GenQueue, otp_app: :my_app
end
We can then create our own adapter by creating an adapter module that handles
the callbacks specified by GenQueue.Adapter
.
defmodule MyApp.MyAdapter do
use GenQueue.Adapter
def handle_push(gen_queue, item) do
IO.inspect(item)
{:ok, item}
end
end
Job queues
One of the benefits of using GenQueue
is that it can abstract common tasks
- like job enqueueing. We can then provide a common API for the various forms of job enqueing we would like to implement, as well as easily swap implementations.
Link to this section Summary
Functions
Get the adapter for a GenQueue module based on the options provided. If
no adapter if specified, the default GenQueue.SimpleAdapter
is returned
Remove all items from a queue
Get the number of items in a queue
Pop an item from a queue
Push an item to a queue
Link to this section Types
Link to this section Functions
config_adapter(GenQueue.t(), list()) :: GenQueue.Adapter.t()
Get the adapter for a GenQueue module based on the options provided. If
no adapter if specified, the default GenQueue.SimpleAdapter
is returned.
Parameters:
gen_queue
- GenQueue module to use
flush(GenQueue.t(), list()) :: {:ok, integer()} | {:error, any()}
Remove all items from a queue
Parameters:
gen_queue
- GenQueue module to useopts
- Any options that may be valid to an adapter
Returns:
{:ok, number_of_items_removed}
if the operation was successful{:error, reason}
if there was an error
length(GenQueue.t(), list()) :: {:ok, integer()} | {:error, any()}
Get the number of items in a queue
Parameters:
gen_queue
- GenQueue module to useopts
- Any options that may be valid to an adapter
Returns:
{:ok, number_of_items}
if the operation was successful{:error, reason}
if there was an error
pop(GenQueue.t(), list()) :: {:ok, any()} | {:error, any()}
Pop an item from a queue
Parameters:
gen_queue
- GenQueue module to useopts
- Any options that may be valid to an adapter
Returns:
{:ok, item}
if the operation was successful{:error, reason}
if there was an error
push(GenQueue.t(), any(), list()) :: {:ok, any()} | {:error, any()}
Push an item to a queue
Parameters:
gen_queue
- GenQueue module to useitem
- Any valid termopts
- Any options that may be valid to an adapter
Returns:
{:ok, item}
if the operation was successful{:error, reason}
if there was an error