gen_stage v0.1.0 GenStage.Dispatcher behaviour

This module defines the behaviour used by :producer and :producer_consumer to dispatch events.

Elixir ships with two dispatcher implementations:

  • GenStage.DemandDispatcher - dispatches the given batch of events to the consumer with the biggest demand in a FIFO ordering. This is the default dispatcher.

  • GenStage.BroadcastDispatcher - dispatches all events to all consumers. The demand is only sent upstream once all consumers ask for data.

Summary

Callbacks

Called every time a consumer sends demand

Called every time a subscription is cancelled or the consumer goes down

Called every time a producer wants to dispatch an event

Called on initialization with the options given on GenStage.init/1

Called every time the producer gets a new subscriber

Callbacks

ask(demand, from, state)

Specs

ask(demand :: pos_integer, from :: {pid, reference}, state :: term) :: {:ok, actual_demand :: non_neg_integer, new_state} when new_state: term

Called every time a consumer sends demand.

The demand will always be a positive integer (more than 0). This callback must return the actual_demand as part of its return tuple. The returned demand is then sent to producers.

It is guaranteed the reference given in from points to a reference previously given in subscribe.

cancel(from, state)

Specs

cancel(from :: {pid, reference}, state :: term) :: {:ok, demand :: non_neg_integer, new_state} when new_state: term

Called every time a subscription is cancelled or the consumer goes down.

It is guaranteed the reference given in from points to a reference previously given in subscribe.

dispatch(events, state)

Specs

dispatch(events :: [term, ...], state :: term) :: {:ok, leftover_events :: [term], new_state} when new_state: term

Called every time a producer wants to dispatch an event.

The events will always be a non empty list. This callback must return events it could not effectively deliver as part of its return tuple. Any leftover_events will be stored by producers in their overflown buffer.

It is important to emphasize that leftover_events can happen in any dispatcher implementation. After all, a consumer can subscribe, ask for events and crash. Eventually the events the consumer asked will be delivered while the consumer no longer exists, meaning they must be returned as left_over events until another consumer subscribes.

It is guaranteed the reference given in from points to a reference previously given in subscribe.

init(opts)

Specs

init(opts :: Keyword.t) :: {:ok, state} when state: any

Called on initialization with the options given on GenStage.init/1.

subscribe(opts, from, state)

Specs

subscribe(opts :: Keyword.t, from :: {pid, reference}, state :: term) :: {:ok, demand :: non_neg_integer, new_state} when new_state: term

Called every time the producer gets a new subscriber.