Class: Familia::Lock

Inherits:
StringKey show all
Defined in:
lib/familia/data_type/types/lock.rb

Instance Attribute Summary collapse

Attributes included from Settings

#current_key_version, #default_expiration, #delim, #encryption_hkdf_salt, #encryption_hkdf_salt_history, #encryption_keys, #encryption_personalization, #encryption_personalization_history, #logical_database, #prefix, #raise_on_unsaved_parent_write, #schema_path, #schema_validator, #schemas, #strict_write_order, #suffix, #transaction_mode

Instance Method Summary collapse

Methods included from DataType::ScalarBase

#scalar_type?

Methods included from Features::Autoloader

autoload_files, included, normalize_to_config_name

Methods included from DataType::Serialization

#deserialize_value, #deserialize_values, #deserialize_values_with_nil, #serialize_value, #strip_legacy_json_encoding

Methods included from DataType::DatabaseCommands

#current_expiration, #delete!, #echo, #exists?, #expire, #expireat, #move, #persist, #rename, #renamenx, #type

Methods included from DataType::Connection

#dbclient, #dbkey, #uri

Methods included from Connection::Behavior

#connect, #create_dbclient, #multi, #normalize_uri, #pipeline, #pipelined, #transaction, #uri=, #url, #url=, #with_connection_scope

Methods included from Settings

#configure, #default_suffix, #dirty_write_warnings, #dirty_write_warnings=, #pipelined_mode, #pipelined_mode=

Methods included from Base

add_feature, #as_json, #expired?, #expires?, find_feature, #generate_id, #to_json, #to_s, #ttl, #update_expiration, #uuid

Constructor Details

#initialize(*args) ⇒ Lock

Returns a new instance of Lock.



7
8
9
10
# File 'lib/familia/data_type/types/lock.rb', line 7

def initialize(*args)
  super
  @opts[:default] = nil
end

Instance Attribute Details

#features_enabled ⇒ Object (readonly) Originally defined in module Features

Returns the value of attribute features_enabled.

#logical_database(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

#parent ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute parent.

#prefix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute prefix.

#suffix ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute suffix.

#uri(val = nil) ⇒ Object Originally defined in module DataType::ClassMethods

Returns the value of attribute uri.

Instance Method Details

#acquire(token = nil, ttl: 10) ⇒ String, false

Acquire a lock with optional TTL

With a positive ttl this is a single atomic SET NX EX command, so the value and its expiry land together -- a crash can never strand a permanent TTL-less lock (previously SETNX followed by EXPIRE).

Parameters:

  • token (String) (defaults to: nil) —

    Unique token to identify lock holder (auto-generated if nil)

  • ttl (Integer, nil) (defaults to: 10) —

    Time-to-live in seconds. nil = no expiration, <=0 rejected

Returns:

  • (String, false) —

    Returns token if acquired successfully, false otherwise

Raises:

  • (Familia::OperationModeError) —

    inside a transaction or pipeline, where the SET is only queued and returns a Redis::Future -- ownership cannot be decided before EXEC, so a truthy Future would report a lock as acquired while another holder still owns it



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
# File 'lib/familia/data_type/types/lock.rb', line 25

def acquire(token = nil, ttl: 10)
  if Familia.transaction_or_pipeline?
    raise Familia::OperationModeError,
          'Lock#acquire cannot run inside a transaction or pipeline: ' \
          'the NX verdict resolves at EXEC, after the caller has already ' \
          'proceeded. Acquire the lock outside the block.'
  end

  # An explicitly passed nil would serialize to "" -- honor the documented
  # auto-generation contract instead.
  token ||= SecureRandom.uuid

  # Reject invalid TTLs before touching the server
  return false if ttl&.<=(0)

  if ttl
    # redis-rb returns true/false for SET with NX (BoolifySet). Token goes
    # through serialize_value so held_by?/release comparisons stay
    # consistent (identity for plain strings).
    return dbclient.set(dbkey, serialize_value(token), nx: true, ex: ttl) ? token : false
  end

  # nil TTL: setnx applies the :expiration feature's default TTL via
  # update_expiration when present; otherwise the key stays TTL-less.
  success = setnx(token)
  # Handle both integer (1/0) and boolean (true/false) return values
  [1, true].include?(success) ? token : false
end

#empty? ⇒ Boolean

The inverse of #locked?, inherited from StringKey and refused inside a block for the same reason.

Returns:

  • (Boolean) —

    whether no token holds the lock

Raises:

  • (Familia::OperationModeError) —

    inside a transaction or pipeline, where StringKey#empty? would return the GET Future. The Future is truthy, so a caller testing it would treat a held lock as free.



114
115
116
117
118
# File 'lib/familia/data_type/types/lock.rb', line 114

def empty?
  Familia.assert_replies_available!('Lock#empty?')

  super
end

#force_unlock! ⇒ Object



120
121
122
# File 'lib/familia/data_type/types/lock.rb', line 120

def force_unlock!
  del
end

#held_by?(token) ⇒ Boolean

Returns whether +token+ holds the lock.

Parameters:

  • token (String) —

    the token returned by #acquire

Returns:

  • (Boolean) —

    whether +token+ holds the lock

Raises:

  • (Familia::OperationModeError) —

    inside a transaction or pipeline, where the GET returns a Redis::Future. The Future is truthy, so a caller testing it would proceed as the owner whatever token it holds.



101
102
103
104
105
# File 'lib/familia/data_type/types/lock.rb', line 101

def held_by?(token)
  Familia.assert_replies_available!('Lock#held_by?')

  value == token
end

#locked? ⇒ Boolean

Returns whether any token holds the lock.

Returns:

  • (Boolean) —

    whether any token holds the lock

Raises:

  • (Familia::OperationModeError) —

    inside a transaction or pipeline, where the GET returns a Redis::Future. The Future is truthy, so a caller testing it would act as though the lock were held.



90
91
92
93
94
# File 'lib/familia/data_type/types/lock.rb', line 90

def locked?
  Familia.assert_replies_available!('Lock#locked?')

  !value.nil?
end

#release(token) ⇒ Boolean, Redis::Future

Deletes the lock only if +token+ still holds it.

Unlike the other Lock methods, release can be queued inside a transaction or pipeline. The ownership check and the delete run in one server-side script, so the queued release deletes the lock only if +token+ holds it when the script runs at EXEC. The outcome is known only after the block: the returned Future is truthy whether or not the lock was released, so read its value after the block instead of testing it inside.

A queued release does not make the other commands in the block depend on the lock. Its false reply does not stop them, so when the lock expired or passed to another holder before EXEC, they still run, and the release's value reports the loss only afterwards. A held_by? check before the block does not close that gap. When the writes must not run without the lock, WATCH the lock key and check the token on the connection that runs the MULTI, or check the token and write in one server-side script. See docs/migrating/transaction-replies.md.

Parameters:

  • token (String) —

    the token returned by #acquire

Returns:

  • (Boolean, Redis::Future) —

    true when the lock was released. Inside a transaction or pipeline, the EVAL Future, which resolves to true when released and false otherwise.



77
78
79
80
81
82
83
84
# File 'lib/familia/data_type/types/lock.rb', line 77

def release(token)
  # Lua script to atomically check token and delete
  script = "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end"
  # The block is redis-rb's reply coercion. It runs on the reply outside
  # a block, and inside one it runs when the Future is resolved, so the
  # Future's value and the block's MultiResult carry the same Boolean.
  dbclient.call(:eval, script, 1, dbkey, token) { |reply| reply == 1 }
end