elixir_google_spreadsheets v0.1.16 GSS.Client.Limiter

Model of Limiter request subscribed to Client with partition :write or :read

This process is a ProducerConsumer for this GenStage pipeline.

Link to this section Summary

Functions

Check to reach limit

Gives events for the next stage to process when requested

Invoked on :producer_consumer and :consumer stages to handle events

Ask new events if needed

Invoked when a consumer subscribes to a producer

Invoked when the server is started

Starts an limiter manager linked to the current process

Link to this section Types

Link to this type

options()
options() :: [
  name: atom(),
  max_demand: pos_integer() | nil,
  max_interval: timeout() | nil,
  interval: timeout() | nil,
  clients: [{atom(), keyword()} | atom()]
]

Link to this type

state()
state() :: %GSS.Client.Limiter{
  interval: timeout(),
  max_demand: pos_integer(),
  max_interval: timeout(),
  producer: GenStage.from(),
  scheduled_at: pos_integer() | nil,
  taked_events: pos_integer()
}

Link to this section Functions

Link to this function

ask_and_schedule(state)

Check to reach limit.

If limit not reached ask again after :interval timeout, otherwise ask after :max_interval timeout.

Link to this function

handle_demand(demand, state)

Gives events for the next stage to process when requested

Link to this function

handle_events(events, from, state)

Invoked on :producer_consumer and :consumer stages to handle events.

Must always be explicitly implemented by such types.

Return values are the same as c:handle_cast/2.

Callback implementation for GenStage.handle_events/3.

Link to this function

handle_info(atom, state)

Ask new events if needed

Link to this function

handle_subscribe(atom, arg2, from, state)

Invoked when a consumer subscribes to a producer.

This callback is invoked in both producers and consumers. producer_or_consumer will be :producer when this callback is invoked on a consumer that subscribed to a producer, and :consumer if when this callback is invoked on producers a consumer subscribed to.

For consumers, successful subscriptions must return one of:

  • {:automatic, new_state} - means the stage implementation will take care of automatically sending demand to producers. This is the default.

  • {:manual, state} - means that demand must be sent to producers explicitly via ask/3. :manual subscriptions must be cancelled when c:handle_cancel/3 is called. :manual can be used when a special behaviour is desired (for example, ConsumerSupervisor uses :manual demand in its implementation).

For producers, successful subscriptions must always return {:automatic, new_state}. :manual mode is not supported.

If this callback is not implemented, the default implementation by use GenStage will return {:automatic, state}.

Examples

Let's see an example where we define this callback in a consumer that will use :manual mode. In this case, we'll store the subscription (from) in the state in order to be able to use it later on when asking demand via ask/3.

def handle_subscribe(:producer, _options, from, state) do
  new_state = %{state | subscription: from}
  {:manual, new_state}
end

Callback implementation for GenStage.handle_subscribe/4.

Invoked when the server is started.

start_link/3 (or start/3) will block until this callback returns. args is the argument term (second argument) passed to start_link/3 (or start/3).

In case of successful start, this callback must return a tuple where the first element is the stage type, which is one of:

  • :producer
  • :consumer
  • :producer_consumer (if the stage is acting as both)

For example:

def init(args) do
  {:producer, some_state}
end

The returned tuple may also contain 3 or 4 elements. The third element may be the :hibernate atom or a set of options defined below.

Returning :ignore will cause start_link/3 to return :ignore and the process will exit normally without entering the loop or calling terminate/2.

Returning {:stop, reason} will cause start_link/3 to return {:error, reason} and the process to exit with reason reason without entering the loop or calling terminate/2.

Options

This callback may return options. Some options are specific to the chosen stage type while others are shared across all types.

:producer options

  • :demand - when :forward, the demand is always forwarded to the c:handle_demand/2 callback. When :accumulate, demand is accumulated until its mode is set to :forward via demand/2. This is useful as a synchronization mechanism, where the demand is accumulated until all consumers are subscribed. Defaults to :forward.

:producer and :producer_consumer options

  • :buffer_size - the size of the buffer to store events without demand. Can be :infinity to signal no limit on the buffer size. Check the "Buffer events" section of the module documentation. Defaults to 10_000 for :producer, :infinity for :producer_consumer.

  • :buffer_keep - returns whether the :first or :last entries should be kept on the buffer in case the buffer size is exceeded. Defaults to :last.

  • :dispatcher - the dispatcher responsible for handling demands. Defaults to GenStage.DemandDispatch. May be either an atom representing a dispatcher module or a two-element tuple with the dispatcher module and the dispatcher options.

:consumer and :producer_consumer options

  • :subscribe_to - a list of producers to subscribe to. Each element represents either the producer module or a tuple with the producer module and the subscription options (as defined in sync_subscribe/2).

Callback implementation for GenStage.init/1.

Link to this function

start_link(options \\ [])
start_link(options()) :: GenServer.on_start()

Starts an limiter manager linked to the current process.

If the event manager is successfully created and initialized, the function returns {:ok, pid}, where pid is the PID of the server. If a process with the specified server name already exists, the function returns {:error, {:already_started, pid}} with the PID of that process.

Options

  • :name - used for name registration as described in the "Name registration" section of the module documentation
  • :interval - ask new events from producer after :interval milliseconds.
  • :max_demand - count of maximum requests per :maximum_interval
  • :max_interval - maximum time that allowed in :max_demand requests
  • :clients - list of clients with partition options. For example [{GSS.Client, partition: :read}}].