gen_stage v0.2.0 Experimental.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 c:GenStage.init/1
Called every time the producer gets a new subscriber
Callbacks
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.
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.
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.
Specs
init(opts :: Keyword.t) :: {:ok, state} when state: any
Called on initialization with the options given on c:GenStage.init/1
.
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.