Module: Cybertrain::Lease

Defined in:
cybertrain/lease.rb

Overview

Cybertrain::Lease – a named lock with an expiry, kept in the application’s database, so that of several processes sharing one SQLite file exactly one does a thing at a time (the Scheduler’s recurring tasks).

if Cybertrain::Lease.acquire(“scheduler”, holder, Time.current.to_i, ttl: 30) # this process holds “scheduler” for the next 30 s; acquire again # before then to keep it end

The rows live in cybertrain_leases, which the framework creates itself (CREATE TABLE IF NOT EXISTS, on first use) and leaves out of db/schema.rb, like cybertrain_jobs.

Class Method Summary collapse

Class Method Details

.acquire(name, holder, now, ttl:) ⇒ Boolean

Takes or renews the lease name for holder until now + ttl: true when the lease was free, already holder’s, or expired (its expires_at before now); false while another holder has it.

Parameters:

  • name (String)
  • holder (String) —

    who asks, unique per process

  • now (Integer) —

    epoch seconds

  • ttl (Integer) —

    seconds the lease lasts unless renewed

Returns:

  • (Boolean)

Raises:

  • (Cybertrain::DB::Error) —

    when the database is not reachable



65
66
67
68
69
70
71
72
73
74
# File 'cybertrain/lease.rb', line 65

def self.acquire(name, holder, now, ttl:)
  ensure_installed
  binds = Cast.binds(name, holder, now + ttl, now)
  won = false
  DB.with do |c|
    c.execute(ACQUIRE_SQL, binds)
    won = c.changes == 1
  end
  won
end

.install! ⇒ nil

Creates the table if it is missing. acquire and release call it once per connected database.

Returns:

  • (nil)


40
41
42
43
44
45
46
47
# File 'cybertrain/lease.rb', line 40

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

.lease_expires_at(name) ⇒ Integer

When name’s lease runs out, epoch seconds; 0 when no row exists.

Parameters:

  • name (String)

Returns:



106
107
108
109
110
111
112
# File 'cybertrain/lease.rb', line 106

def self.lease_expires_at(name)
  ensure_installed
  rows = DB.with { |c| c.execute("SELECT expires_at FROM cybertrain_leases WHERE name = ?", [name]) }
  return 0 if rows.empty?

  Cast.int(rows[0]["expires_at"])
end

.lease_holder(name) ⇒ String

Who holds name, “” when no row exists (the lease may have expired: compare lease_expires_at with the time). For a status page.

Parameters:

  • name (String)

Returns:

  • (String)


94
95
96
97
98
99
100
# File 'cybertrain/lease.rb', line 94

def self.lease_holder(name)
  ensure_installed
  rows = DB.with { |c| c.execute("SELECT holder FROM cybertrain_leases WHERE name = ?", [name]) }
  return "" if rows.empty?

  Cast.str(rows[0]["holder"])
end

.release(name, holder) ⇒ nil

Gives the lease up if holder has it (another holder’s is left), so another process can take it at once instead of after the ttl.

Parameters:

  • name (String)
  • holder (String)

Returns:

  • (nil)


82
83
84
85
86
87
# File 'cybertrain/lease.rb', line 82

def self.release(name, holder)
  ensure_installed
  binds = Cast.binds(name, holder)
  DB.with { |c| c.execute("DELETE FROM cybertrain_leases WHERE name = ? AND holder = ?", binds) }
  nil
end