Commit e18ffea5 authored by pbair's avatar pbair

Add documentation to WithLockRetries class

Document WithLockRetries with details about how the class can be used in
application code.
parent 32fe0463
...@@ -2,6 +2,11 @@ ...@@ -2,6 +2,11 @@
module Gitlab module Gitlab
module Database module Database
# This class provides a way to automatically execute code that relies on acquiring a database lock in a way
# designed to minimize impact on a busy production database.
#
# A default timing configuration is provided that makes repeated attempts to acquire the necessary lock, with
# varying lock_timeout settings, and also serves to limit the maximum number of attempts.
class WithLockRetries class WithLockRetries
AttemptsExhaustedError = Class.new(StandardError) AttemptsExhaustedError = Class.new(StandardError)
...@@ -65,6 +70,16 @@ module Gitlab ...@@ -65,6 +70,16 @@ module Gitlab
@log_params = { method: 'with_lock_retries', class: klass.to_s } @log_params = { method: 'with_lock_retries', class: klass.to_s }
end end
# Executes a block of code, retrying it whenever a database lock can't be acquired in time
#
# When a database lock can't be acquired, ActiveRecord throws ActiveRecord::LockWaitTimeout
# exception which we intercept to re-execute the block of code, until it finishes or we reach the
# max attempt limit. The default behavior when max attempts have been reached is to make a final attempt with the
# lock_timeout disabled, but this can be altered with the raise_on_exhaustion parameter.
#
# @see DEFAULT_TIMING_CONFIGURATION for the timings used when attempting a retry
# @param [Boolean] raise_on_exhaustion whether to raise `AttemptsExhaustedError` when exhausting max attempts
# @param [Proc] block of code that will be executed
def run(raise_on_exhaustion: false, &block) def run(raise_on_exhaustion: false, &block)
raise 'no block given' unless block_given? raise 'no block given' unless block_given?
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment