Tallies
Some numbers belong to the whole game: the gifts every player has given to a community goal, the
pumpkins harvested this season, the damage dealt to a world boss. Every server adds to them, and every
server shows them. KeepBlox.tally opens a store of such counts.
const gives = KeepBlox.tally("Gives")
-- when a player givesgives:add("harvest", 1)
-- on every server, to show the goalgives:watch("harvest", function(total) goalLabel.Text = `{total} / 1000`end)
-- or now, without yieldingprint(gives:total("harvest"))Why not one key
Section titled “Why not one key”The obvious way, one key and an UpdateAsync for each add, works with a few servers. Every server
then writes the same key at once: each write that loses the race is run again, the key’s writes queue,
and the game’s busiest moment is the one that fails. A sorted map in MemoryStore has the same key, and
a quota that grows only with the players in the game at once.
A tally spreads each count over several keys, its shards, and a server writes only every
interval seconds: everything its players added meanwhile goes as one batch, in one write. However
many adds a server has, a shard takes about one write an interval from each server in shards of
them.
Options
Section titled “Options”KeepBlox.tally(name, options?) takes the data store name and:
| Option | Meaning |
|---|---|
interval |
Seconds between a server’s batches, and between its reads of the keys it watches. Default 60. |
shards |
Keys each count is spread over, "<key>/1" to "<key>/<shards>". Default 8. Fixed for the tally’s name (see below). |
remember |
Seconds a shard keeps the entry of a server that stopped writing there, and so how long a batch is safe to try again. Default 86400 (a day). |
reserve |
Standard requests left in this server’s budget below which a turn waits, so saves keep theirs. Default 10. |
config |
Overrides for the defaults (see Config). A tally uses callTimeout, shutdownDeadline, backoffMin and backoffMax. |
mock |
Keep the counts in memory: true, or the name of a scratch set (see Studio and testing). |
services |
The engine services; tests pass fakes. |
A key with its shard’s number must fit the 50 characters a data store key may have: with 8 shards, a key of up to 48.
add, total, read, flush
Section titled “add, total, read, flush”gives:add(key, amount) -- counted here at once; never yieldsgives:total(key) -- every server's count as last read, with this server's adds since; never yieldsgives:read(key) -- reads every shard now: { ok = true, total = ... }; yieldsgives:flush() -- writes every key's batch now, one try each; true when nothing is left; yieldsamount is any finite number, negative ones too. A server’s own adds are in its total at once;
everyone else’s arrive when this server reads them, at most about two intervals later.
read answers { ok = false, reason = "failed" } when a shard could not be read, and
{ ok = false, reason = "foreign" } when a shard’s key holds something that is not a tally’s.
watch(key, handler) reads the key at once, calls handler(total) with what it found, and from then on
reads the key every interval seconds while it is watched, calling handler whenever the total changes,
by a read or by this server’s own add. It returns a connection; Disconnect() stops it, and a key no one
watches is not read.
How a batch lands once
Section titled “How a batch lands once”A write that seems to fail may still have gone through, and a call the library stopped waiting for keeps running in the engine. A batch tried again must not count twice. Each server numbers its batches on a key, and its shard keeps, for each server that wrote there lately, the number of its last batch that landed. A try that finds its number there already changes nothing. The server sends a key’s batches one at a time and keeps trying the same batch until one try is seen to land, by its own write or by a read of its shard.
A shard holds one entry a server, forgotten remember seconds after that server’s last write there, so
a shard stays small: a day’s servers divided among the shards.
Each interval, a server spends one UpdateAsync for each key added to since its last turn, and
shards reads for each key it watches. With the defaults that is 8 reads a minute a watched key, from
the server’s standard read budget, which grows with its players. A turn writes nothing while fewer than reserve standard writes are
left, and reads nothing while fewer than shards + reserve reads are; what waits goes at the next turn.
flush and read are the game’s own asks and do not wait for the budget.
What it does not promise
Section titled “What it does not promise”onError
Section titled “onError”onError fires (key, message, kind) as a store’s does: kind "tally" for a batch that could not be
written (once, until one lands), a watched key that could not be read, and a shard that holds something
that is not a tally’s; and "studio" once when Studio cannot reach live data and keeps the counts in
memory.
Use a data store of its own
Section titled “Use a data store of its own”A shard’s key that holds anything but a tally’s shard is never written and never counted. Keep tallies in their own data store, apart from profiles, shared documents and schedules.
