Token Bucket Single Event Update

Apply one deterministic token-bucket event with bounded refill and all-or-nothing consumption; no real-time state, burst guarantee or distributed synchronization.

Description

Apply one deterministic token-bucket event with bounded refill and all-or-nothing consumption; no real-time state, burst guarantee or distributed synchronization.

A single token-bucket event first refills up to capacity and then optionally spends the requested cost.

When to use this tool

Apply one deterministic token-bucket event with bounded refill and all-or-nothing consumption; no real-time state, burst guarantee or distributed synchronization.

Prepare the supplied capacity, tokens, rate, elapsed, cost fields for this operation.
Compare the complete example with the representation used by your own input before carrying the result into another step.

How to use the tool and how it works

Enter capacity, tokens, rate, elapsed, cost. Use the exact text syntax, units and index conventions explained below.
Run the tool. If input validation fails, correct the supplied fields before interpreting any result.
Read result.available, result.admitted, result.tokens. Interpret false, null and empty lists using the distinctions below; they can be valid outputs.

Validate nonnegative inputs and tokens within capacity. available is min(capacity, tokens plus rate*elapsed). If available covers cost, admitted is true and returned tokens subtract cost; otherwise the full available balance remains.^[1]

Input field	Meaning and representation	Accepted input
capacity	capacity.	Finite number
tokens	tokens.	Finite number
rate	rate.	Finite number
elapsed	elapsed.	Finite number
cost	cost.	Finite number

Output field	Interpretation
result	Object containing the named outputs below.
result.available	The available value under the stated formula or text convention.
result.admitted	Flag for admitted under the exact condition described above.
result.tokens	The tokens value under the stated formula or text convention.

json

{
  "input": {
    "capacity": 10,
    "tokens": 2,
    "rate": 2,
    "elapsed": 3,
    "cost": 5
  },
  "output": {
    "result": {
      "available": 8,
      "admitted": true,
      "tokens": 3
    }
  }
}

Limitations and assumptions

No state is stored between calls and no concurrency or clock behavior is implemented. Pass the returned tokens into any subsequent event explicitly.
All declared input fields are required and unexpected top-level fields are rejected. Numbers must be finite; lists are limited to 128 entries and ordinary text fields to 8,192 UTF-16 code units, with tighter limits where stated.
JSON text inputs must parse within bounded nesting and size limits. Numeric outputs outside the safe finite range are rejected; large exact integer results use decimal strings. Indexes and half-open spans are zero-based unless a rank is explicitly described as one-based.

Alternative or Complementary methods

Check the arithmetic against the actual scheduling or storage policy. Add variable costs, arrivals, concurrent state and overhead in a model that explicitly represents them when they affect the decision.

References

Tool behavior and example: Token Bucket Single Event Update — tool.io

Similar or alternative tools

Token Bucket Next Admission Delay
Compute deterministic next token-bucket admission delay with null for impossible requests; assumes constant refill and no intervening consumption.
Buffer Equal Record Slot Count
Budget fixed-byte records after an explicit buffer header reservation, retaining unused tail bytes.