Throttler 1.0.0 API documentation

throttler.core documentation

Returns a function that will take an input channel and return an
output channel with the desired rate. Optionally acceps a bucket size
for bursty channels.

If the throttling function returned here is used on more than one
channel, they will all share the same token-bucket. This means their
overall output rate combined will be equal to the provided rate. In
other words, they will all share the alloted bandwith using
statistical multiplexing.

See fn-throttler for an example that can trivially be extrapolated to
chan-throttler.

Creates a function that will globally throttle multiple functions at
the provided rate.  The returned function accepts a function and
produces an equivalent one that complies with the desired rate. If
applied to many functions, the sum af all their invocations in a time
interval will sum up to the goal average rate.

Example:
    ; create the function throttler
    (def slow-to-1-per-minute (fn-throttler 1 :minute)

    ; create slow versions of f1, f2 and f3
    (def f1-slow (slow-to-1-per-minute f1)
    (def f2-slow (slow-to-1-per-minute f2)
    (def f3-slow (slow-to-1-per-minute f3)

    ; use them to do work. Their aggregate rate will be equal to 1
    ; call/minute
    (f1-slow arg1 arg2) ; => result, t = 0
    (f2-slow)           ; => result, t = 1 minute
    (f3-slow arg)       ; => result, t = 2 minutes

The combined rate of f1-slow, f2-slow and f3-slow will be equal to
'rate'. This does not mean that the rate of each is 1/3rd of
'rate'; if only f1-slow is being called then its throughput will be
close to rate. Or, if one of the functions is being called from
multiple threads then it'll get a greater share of the total
bandwith.

In other words, the functions will use statistical multiplexing to
cap the allotted bandwidth.

Takes a write channel, a goal rate and a unit and returns a read
channel. Messages written to the input channel can be read from
the throttled output channel at a rate that will be at most the
provided goal rate.

Optionally takes a bucket size, which will correspond to the
maximum number of burst messages.

As an example, the channel produced by calling:

(throttle-chan (chan) 1 :second 9)

Will transmit 1 message/second on average but can transmit up to
10 messages on a single second (9 burst messages + 1
message/second).

Note that after the burst messages have been consumed they have to
be refilled in a quiescent period at the provided rate, so the
overall goal rate is not affected in the long term.

The throttled channel will be closed when the input channel
closes.

Takes a function, a goal rate and a time unit and returns a
function that is equivalent to the original but that will have a maximum
throughput of 'rate'.

Optionally accepts a burst rate, in which case the resulting function
will behave like a bursty channel. See throttle-chan for details.