Module: Cybertrain::Cache
- Defined in:
- cybertrain/cache.rb
Overview
Cybertrain::Cache – a cache store in the application’s own SQLite database: “keep this answer for a while, so the next request does not ask the slow API again”.
require “cybertrain/cache” # bin/
text = Cybertrain::Cache.fetch(“defillama/tvl”, expires_in: 21_600, race_condition_ttl: 30) do client.get(“https://api.llama.fi/tvl”).body end data = Cybertrain::Cache.fetch_hash(“prices/eth”, expires_in: 60) { { “usd” => price } } Cybertrain::Cache.write(“import-lock”, “1”, expires_in: 300, unless_exist: true) # true when written
Values are Strings (Cache.fetch_hash, Cache.fetch_array and
Cache.fetch_int store JSON or Integer text and parse it back). Times
are epoch seconds from Cache.now. expires_in: 0, the default,
never expires; a row with expires_at E is live up to and including
second E and expired from E + 1 on.
The rows live in cybertrain_cache, which the framework creates itself
(CREATE TABLE IF NOT EXISTS, on first use) and leaves out of
db/schema.rb, like cybertrain_jobs. Every write takes the
application’s SQLite writer lock, which requests writing their own
rows wait for: cache what the jobs produce rather than in request
paths that write often. Nothing is kept in memory: every read is a
SELECT, which SQLite answers from its page cache. The expired rows are
deleted every Cybertrain::Config#cache_prune_interval seconds (Cache.prune):
with require "cybertrain/jobs", by the scheduled task
"cybertrain cache prune" (requiring both registers it); without
jobs, by the writes (Cache.write, Cache.increment): the first of
the process and the first once that interval has passed, at most
1000 rows per write (Cache.prune_if_due).
Class Method Summary collapse
-
.clear ⇒ nil
Removes every row.
-
.delete(key) ⇒ Boolean
Removes the row of
key, live or expired. -
.exist?(key) ⇒ Boolean
Whether a live row is stored under
key. -
.fetch(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ String
The value stored under
key, or the block’s value, which is then stored. -
.fetch_array(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ Array<Object>
Cache.fetch for an Array, stored as JSON and parsed back with Cybertrain::Cast.array: a corrupt cell (not a JSON array) reads as
[]until it expires and the block runs again. -
.fetch_hash(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ Hash{String => Object}
Cache.fetch for a Hash, stored as JSON and parsed back with Cybertrain::Cast.json_hash: a corrupt cell (not a JSON object) reads as
{}until it expires and the block runs again. -
.fetch_int(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ Integer
Cache.fetch for an Integer, stored as its decimal text: a corrupt cell (not an integer, or one too long to be one) reads as 0 until it expires and the block runs again.
-
.increment(key, by: 1, expires_in: 0) ⇒ Integer
Adds
byto the Integer stored underkeyin one statement, and answers the sum. -
.install! ⇒ nil
Creates the table if it is missing.
-
.now ⇒ Integer
The current time as the cache sees it: Cybertrain::Clock.now in epoch seconds, so a test moves it with
travel_to/travelinstead of sleeping. -
.prune(now) ⇒ Integer
Deletes the rows expired at
now(anexpires_atbefore it), at most 1000 per statement so the writer lock is released between batches. -
.read(key) ⇒ String?
The live value stored under
key; nil when there is none or it has expired. -
.register_prune_task ⇒ nil
Registers the scheduled task
"cybertrain cache prune", every Cache.prune_interval seconds, when cybertrain/jobs is loaded and no task of that name is registered already (Features.schedule_all_periodic: JobsFeature takes on CacheFeature’s periodic hook). -
.write(key, value, expires_in: 0, unless_exist: false) ⇒ Boolean
Stores
valueunderkey, replacing any row.
Class Method Details
.clear ⇒ nil
Removes every row.
360 361 362 363 364 |
# File 'cybertrain/cache.rb', line 360 def self.clear ensure_installed DB.with { |c| c.execute("DELETE FROM cybertrain_cache") } nil end |
.delete(key) ⇒ Boolean
Removes the row of key, live or expired.
310 311 312 313 314 315 316 317 318 |
# File 'cybertrain/cache.rb', line 310 def self.delete(key) ensure_installed changed = 0 DB.with do |c| c.execute("DELETE FROM cybertrain_cache WHERE key = ?", [key]) changed = c.changes end changed > 0 end |
.exist?(key) ⇒ Boolean
Whether a live row is stored under key.
325 326 327 |
# File 'cybertrain/cache.rb', line 325 def self.exist?(key) !live_value(key, Cache.now).nil? end |
.fetch(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ String
The value stored under key, or the block’s value, which is then
stored. A live row is answered without running the block. On a miss
(no row, or an expired one) the block runs and its value, a String
(anything else is stored as its to_s), is written with
expires_in.
With race_condition_ttl: n, a caller that finds the row expired
first extends it by n seconds; only the caller whose extension
changed the row runs the block, and the others answer the stale
value meanwhile (Rails’ semantics). When that block raises, nothing
is written and the exception propagates: the stale value is served
until the extension runs out. Without it, every caller of an expired
key runs the block. A missing row is always computed.
155 156 157 158 159 160 161 162 163 164 165 166 |
# File 'cybertrain/cache.rb', line 155 def self.fetch(key, expires_in: 0, race_condition_ttl: 0) hit = fetch_hit(key, race_condition_ttl) return hit.to_s unless hit.nil? # The block's value in a local first: an argument expression may be # evaluated once per branch of the inlined cast, running the block # twice. computed = yield value = Cast.str(computed) write(key, value, expires_in: expires_in) value end |
.fetch_array(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ Array<Object>
fetch for an Array, stored as JSON and parsed back with
Cybertrain::Cast.array: a corrupt cell (not a JSON array) reads as [] until
it expires and the block runs again.
200 201 202 203 204 205 206 207 208 |
# File 'cybertrain/cache.rb', line 200 def self.fetch_array(key, expires_in: 0, race_condition_ttl: 0) hit = fetch_hit(key, race_condition_ttl) return Cast.array(Cast.parse_json(hit.to_s)) unless hit.nil? computed = yield text = JSON.generate(computed) write(key, text, expires_in: expires_in) Cast.array(Cast.parse_json(text)) end |
.fetch_hash(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ Hash{String => Object}
fetch for a Hash, stored as JSON and parsed back with
Cybertrain::Cast.json_hash: a corrupt cell (not a JSON object) reads as {}
until it expires and the block runs again.
179 180 181 182 183 184 185 186 187 |
# File 'cybertrain/cache.rb', line 179 def self.fetch_hash(key, expires_in: 0, race_condition_ttl: 0) hit = fetch_hit(key, race_condition_ttl) return Cast.json_hash(hit.to_s) unless hit.nil? computed = yield text = JSON.generate(computed) write(key, text, expires_in: expires_in) Cast.json_hash(text) end |
.fetch_int(key, expires_in: 0, race_condition_ttl: 0) { ... } ⇒ Integer
fetch for an Integer, stored as its decimal text: a corrupt cell (not an integer, or one too long to be one) reads as 0 until it expires and the block runs again.
221 222 223 224 225 226 227 228 229 |
# File 'cybertrain/cache.rb', line 221 def self.fetch_int(key, expires_in: 0, race_condition_ttl: 0) hit = fetch_hit(key, race_condition_ttl) return Params.parse_int(hit.to_s, 0) unless hit.nil? computed = yield value = Cast.int(computed) write(key, value.to_s, expires_in: expires_in) value end |
.increment(key, by: 1, expires_in: 0) ⇒ Integer
Adds by to the Integer stored under key in one statement, and
answers the sum. A missing or expired row starts at by; a value
that is not a number counts as 0. expires_in sets the expiry of a
new or expired row, and of a live row that has none; a live row that
has one keeps it, so the counter’s window is fixed from its first
increment (as Rails’ stores do) and does not slide with every call.
345 346 347 348 349 350 351 352 353 354 |
# File 'cybertrain/cache.rb', line 345 def self.increment(key, by: 1, expires_in: 0) ensure_installed now = Cache.now prune_if_due(now) expires_at = expires_in > 0 ? now + expires_in : 0 rows = DB.with { |c| c.execute(INCREMENT_SQL, Cast.binds(key, by, expires_at, now)) } return 0 if rows.empty? Cast.int(rows[0]["n"]) end |
.install! ⇒ nil
Creates the table if it is missing. Every other method calls it once per connected database; call it yourself only to create the table ahead of time.
109 110 111 112 113 114 115 116 |
# File 'cybertrain/cache.rb', line 109 def self.install! DB.with { |c| c.exec_script(TABLE_SQL) } # A CREATE inside a transaction that rolls back is undone, so only one # outside a transaction is remembered (as Job.install! does). pool = DB.pool @installed_generation = DB.generation if !pool.nil? && pool.held_index < 0 nil end |
.now ⇒ Integer
The current time as the cache sees it: Cybertrain::Clock.now in epoch seconds,
so a test moves it with travel_to / travel instead of sleeping.
128 129 130 |
# File 'cybertrain/cache.rb', line 128 def self.now Clock.now.to_i end |
.prune(now) ⇒ Integer
Deletes the rows expired at now (an expires_at before it), at
most 1000 per statement so the writer lock is released between
batches. The scheduled task "cybertrain cache prune" calls it with
now.
374 375 376 377 378 379 380 381 382 383 |
# File 'cybertrain/cache.rb', line 374 def self.prune(now) ensure_installed total = 0 batch = PRUNE_BATCH while batch == PRUNE_BATCH batch = prune_batch(now) total += batch end total end |
.read(key) ⇒ String?
The live value stored under key; nil when there is none or it has
expired.
272 273 274 |
# File 'cybertrain/cache.rb', line 272 def self.read(key) live_value(key, Cache.now) end |
.register_prune_task ⇒ nil
Registers the scheduled task "cybertrain cache prune", every
prune_interval seconds, when cybertrain/jobs is loaded and no
task of that name is registered already
(Features.schedule_all_periodic: JobsFeature takes on CacheFeature’s
periodic hook). Requiring this file and cybertrain/jobs, in either order,
registers it; calling it again adds nothing.
465 466 467 468 |
# File 'cybertrain/cache.rb', line 465 def self.register_prune_task Features.schedule_all_periodic nil end |
.write(key, value, expires_in: 0, unless_exist: false) ⇒ Boolean
Stores value under key, replacing any row. With unless_exist:
true a live row is left alone and the answer is false (an expired
one is replaced): a lock for expires_in seconds that one process
gets.
289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 |
# File 'cybertrain/cache.rb', line 289 def self.write(key, value, expires_in: 0, unless_exist: false) ensure_installed now = Cache.now prune_if_due(now) expires_at = expires_in > 0 ? now + expires_in : 0 sql = unless_exist ? ADD_SQL : WRITE_SQL binds = Cast.binds(key, value, expires_at, now) binds << now if unless_exist changed = 0 DB.with do |c| c.execute(sql, binds) changed = c.changes end changed > 0 end |