View Source Oban.Peer behaviour (Oban v2.17.1)
The Peer
module maintains leadership for a particular Oban instance within a cluster.
Leadership is used by plugins, primarily, to prevent duplicate work accross nodes. For example,
only the leader's Cron
plugin will try inserting new jobs. You can use peer leadership to
extend Oban with custom plugins, or even within your own application.
Note a few important details about how peer leadership operates:
Each peer checks for leadership at a 30 second interval. When the leader exits it broadcasts a message to all other peers to encourage another one to assume leadership.
Each Oban instance supervises a distinct
Oban.Peer
instance. That means that with multiple Oban instances on the same node one instance may be the leader, while the others aren't.Without leadership, global plugins (Cron, Lifeline, Stager, etc.), will not run on any node.
Available Peer Implementations
There are two built-in peering modules:
Oban.Peers.Postgres
— uses table-based leadership through theoban_peers
table and works in any environment, with or without clustering. Only one node (per instance name) will have a row in the peers table, that node is the leader. This is the default.Oban.Peers.Global
— coordinates global locks through distributed Erlang, requires distributed Erlang.
You can specify the peering module to use in your Oban configuration:
config :my_app, Oban,
peer: Oban.Peers.Postgres, # default value
...
If in doubt, you can call Oban.config()
to see which module is being used.
Examples
Check leadership for the default Oban instance:
Oban.Peer.leader?()
# => true
That is identical to using the name Oban
:
Oban.Peer.leader?(Oban)
# => true
Check leadership for a couple of instances:
Oban.Peer.leader?(Oban.A)
# => true
Oban.Peer.leader?(Oban.B)
# => false
Summary
Functions
Check whether the current instance leads the cluster.
Types
@type option() :: {:name, module()} | {:conf, Oban.Config.t()} | {:interval, timeout()}
Callbacks
@callback leader?(Oban.Config.t() | GenServer.server()) :: boolean()
Check whether the current peer instance leads the cluster.
@callback start_link([option()]) :: GenServer.on_start()
Starts a peer instance.