Representation of a user's bucket for API requests used for rate-limiting and prioritization.

A bucket can contain as many API requests as the BEAM VM and the memory can handle. However, each bucket will only process 10 API requests every 6 seconds.

The bucket provides the enqueue/1 and enqueue/2 operations providing the core functionality of this module:

• creating the bucket if necessary,
• handling telemetry,
• and request handling.

Bucket Creation

Creating buckets is not required, but you can create and store buckets in a different manner if you need to do so.

A buckets can be created with the following two methods:

• new/1 to create a bucket and store the PID of the GenServer manually
• enqueue/1 to create a bucket and let Tornex store the PID of the GenServer in a pre-initialized registry Tornex.Scheduler.BucketRegistry

Making API Requests

API requests are made with the enqueue/1 and the enqueue/2 operations with a Tornex.Query or Tornex.SpecQuery struct. The operations will then wait until the API call has been scheduled and the Torn API has responded instead of ending the invocation early and using a later await-like function.

However, for example, this can still be done with the built-in Task module (including to handle many API requests at once):

1..10
|> Enum.map(fn n ->
  Task.async(fn ->
    Tornex.Scheduler.Bucket.enqueue(pid, query)
  end)
end)
|> Task.await_many(timeout)

If the query is a Tornex.SpecQuery that can be combined with any other Tornex.SpecQuery, including those from other buckets, the set of queries will be merged into a Tornex.Scheduler.ExecutionUnit that will be executed as one API call. The response of this API call will be split into the necessary components for each Tornex.SpecQuery and these components will be returned as if the query was performed directly. For more information, see Tornex.Scheduler.QueryRegistry and Tornex.Scheduler.ExecutionUnit.

Bucket Timeouts

By default, the bucket will never time out when the bucket does not receive any requests. This can be configured in milliseconds globally using the :bucket_ttl configuration key or per-bucket using the :ttl option when starting the bucket. If the bucket does not receive any requests for the specified amount of time, the bucket will be stopped and removed from its supervisor. If a request is later enqueued for the removed bucket's user, a new bucket will be created.