with_advisory_lock Documentation

To use advisory locking in your ActiveRecord application, add the gem to your Gemfile and run bundle.

Requirements:

• ActiveRecord 7.2+
• Ruby 3.3+
• JRuby or TruffleRuby
• MySQL 8+ or PostgreSQL (MySQL 5.7 and SQLite are not supported)

gem 'with_advisory_lock'

$ bundle

The with_advisory_lock gem integrates with ActiveRecord via ActiveSupport hooks. When required in a standard Ruby environment (MRI or TruffleRuby), it automatically includes WithAdvisoryLock::Concern into ActiveRecord::Base and prepends the appropriate database-specific advisory lock modules to your connection adapters.

Supported adapter integrations include:

• PostgreSQL: Uses WithAdvisoryLock::CoreAdvisory and WithAdvisoryLock::PostgreSQLAdvisory.
• MySQL (mysql2): Uses WithAdvisoryLock::CoreAdvisory and WithAdvisoryLock::MySQLAdvisory.
• Trilogy: Uses WithAdvisoryLock::CoreAdvisory and WithAdvisoryLock::MySQLAdvisory.

For JRuby, the gem uses a specialized JRubyAdapter which is installed via WithAdvisoryLock::JRubyAdapter.install! to ensure compatibility.

Use advisory_lock_exists? to check if a specific lock name is currently active in the current connection's lock stack.

Note: For PostgreSQL, the implementation attempts a non-blocking query first to avoid race conditions before falling back to a zero-timeout acquisition attempt.

if MyModel.advisory_lock_exists?('my_lock_name')
  puts 'Lock is currently held'
end

The with_advisory_lock method allows you to wrap a block of code in an advisory lock. If the lock is successfully acquired, the block is executed and its return value is returned. If the lock cannot be acquired (e.g., due to a timeout), the method returns false instead of raising an error.

Arguments:

• lock_name: The identifier for the lock.
• options: A hash of options (e.g., timeout_seconds).
• &block: The code to execute while holding the lock.

# Returns the result of the block if lock acquired, otherwise returns false
MyModel.with_advisory_lock('my_lock_name') do
  # critical section
end

The with_advisory_lock! method is similar to with_advisory_lock, but it enforces acquisition. If the lock cannot be acquired, it raises a WithAdvisoryLock::FailedToAcquireLock error.

Arguments:

• lock_name: The identifier for the lock.
• options: A hash of options.
• &block: The code to execute while holding the lock.

# Raises WithAdvisoryLock::FailedToAcquireLock if lock cannot be acquired
MyModel.with_advisory_lock!('my_lock_name') do
  # critical section
end

You can inspect the locks currently held by the active connection using current_advisory_lock or current_advisory_locks.

• current_advisory_lock: Returns the name of the most recent (top of stack) lock.
• current_advisory_locks: Returns an array of names of all locks currently held in the stack.

# Returns the name of the top-most lock
lock = MyModel.current_advisory_lock

# Returns an array of all held lock names
all_locks = MyModel.current_advisory_locks

When using methods that return a WithAdvisoryLock::Result object (typically when a lock is not immediately acquired), you can inspect the outcome using the following attributes:

• lock_was_acquired?: A predicate method that returns true if the lock was successfully acquired, and false otherwise.
• result: Contains the return value of the block executed within the lock, if the lock was acquired.

# Example of how a Result object might be used
result_obj = WithAdvisoryLock::Result.new(lock_was_acquired: true, result: "success")

if result_obj.lock_was_acquired?
  puts "Lock was held! Block result: #{result_obj.result}"
else
  puts "Failed to acquire lock."
end