active_record_mutex 2.5.1 → 3.1.0

data/lib/active_record/database_mutex/implementation.rb

@@ -1,129 +1,212 @@
-require 'base64'
-require 'tins/xt/string_version'
+require 'digest/md5'
 
 module ActiveRecord
   module DatabaseMutex
     class Implementation
 
       class << self
+        # The db method returns an instance of ActiveRecord::Base.connection
         def db
           ActiveRecord::Base.connection
         end
-
-        def check_size?
-          if defined? @check_size
-            @check_size
-          else
-            version = db.execute("SHOW VARIABLES LIKE 'version'").first.last.
-              delete('^0-9.').version
-            @check_size = version >= '5.7'.version
-          end
-        end
       end
 
-      # Creates a mutex with the name given with the option :name.
+      # The initialize method initializes an instance of the DatabaseMutex
+      # class by setting its name and internal_name attributes.
+      #
+      # @param opts [ Hash ] options hash containing the **name** key
+      #
+      # @option opts name [ String ] name for the mutex, required.
+      #
+      # @raise [ ArgumentError ] if no **name** option is provided in the options hash.
       def initialize(opts = {})
         @name = opts[:name] or raise ArgumentError, "mutex requires a :name argument"
-        counter or raise ArgumentError, 'argument :name is too long'
+        internal_name # create/check internal_name
       end
 
-      # Returns the name of this mutex as given as a constructor argument.
+      # Returns the name of this mutex as given via the constructor argument.
       attr_reader :name
 
-      # Locks the mutex if it isn't already locked via another database
-      # connection and yields to the given block. After executing the block's
-      # content the mutex is unlocked (only if it was locked by this
-      # synchronize method before).
+      # The internal_name method generates an encoded name for this mutex
+      # instance based on its class and {name} attributes and memoizes it.
       #
-      # If the mutex was already locked by another database connection the
-      # method blocks until it could aquire the lock and only then the block's
-      # content is executed. If the mutex was already locked by the current database
-      # connection then the block's content is run and the the mutex isn't
-      # unlocked afterwards.
-      #
-      # If a value in seconds is passed to the :timeout option the blocking
-      # ends after that many seconds and the method returns immediately if the
-      # lock couldn't be aquired during that time.
+      # @return [ String ] the encoded name of length <= 64 characters
+      def internal_name
+        @internal_name and return @internal_name
+        encoded_name = ?$ + Digest::MD5.base64digest([ self.class.name, name ] * ?#).
+          delete('^A-Za-z0-9+/').gsub(/[+\/]/, ?+ => ?_, ?/ => ?.)
+        if encoded_name.size <= 64
+          @internal_name = encoded_name
+        else
+          # This should never happen:
+          raise MutexInvalidState, "internal_name #{encoded_name} too long: >64 characters"
+        end
+      end
+
+			# The synchronize method attempts to acquire a mutex lock for the given name
+			# and executes the block passed to it. If the lock is already held by another
+			# database connection, this method will return nil instead of raising an
+			# exception and not execute the block. #
+			#
+			# This method provides a convenient way to ensure that critical sections of code
+			# are executed while holding the mutex lock. It attempts to acquire the lock using
+			# the underlying locking mechanisms (such as {lock} and {unlock}) and executes
+			# the block passed to it.
+			#
+			# The **block** and **timeout** options are passed to the {lock} method
+			# and configure the way the lock is acquired.
+			#
+			# The **force** option is passed to the {unlock} method, which will force the
+			# lock to open if true.
+			#
+			# @example
+			#   foo.mutex.synchronize { do_something_with foo } # wait forever and never give up
+			#
+			# @example
+			#   foo.mutex.synchronize(timeout: 5) { do_something_with foo } # wait 5s and give up
+			#
+			# @example
+			#   unless foo.mutex.synchronize(block: false) { do_something_with foo }
+			#     # try again later
+			#   end
+			#
+			# @param opts [ Hash ] Options hash containing the **block**, **timeout**, or **force** keys
+			#
+			# @yield [ Result ] The block to be executed while holding the mutex lock
+			#
+			# @return [ Nil or result of yielded block ] depending on whether the lock was acquired
       def synchronize(opts = {})
-        locked = lock(opts) or return
+        locked = lock(opts.slice(:block, :timeout)) or return
         yield
       rescue ActiveRecord::DatabaseMutex::MutexLocked
         return nil
       ensure
-        locked and unlock
+        locked and unlock opts.slice(:force)
       end
 
-      # Locks the mutex and returns true if successful. If the mutex is
-      # already locked and the timeout in seconds is given as the :timeout
-      # option, this method raises a MutexLocked exception after that many
-      # seconds. If the :timeout option wasn't given, this method blocks until
-      # the lock could be aquired.
+      # The lock method attempts to acquire the mutex lock for the configured
+      # name and returns true if successful, that means #{locked?} and
+      # #{owned?} will be true. Note that you can lock the mutex n-times, but
+      # it has to be unlocked n-times to be released as well.
+      #
+      # If the **block** option was given as false, it returns false instead of
+      # raising MutexLocked exception when unable to acquire lock without blocking.
+      #
+      # If a **timeout** option with the (nonnegative) timeout in seconds was
+      # given, a MutexLocked exception is raised after this time, otherwise the
+      # method blocks forever.
+      #
+      # If the **raise** option is given as false, no MutexLocked exception is raised,
+      # but false is returned.
+      #
+      # @param opts [ Hash ] the options hash
+      #
+      # @option opts [ true, false ] block, defaults to true
+      # @option opts [ true, false ] raise, defaults to true
+      # @option opts [ Integer, nil ] timeout, defaults to nil, which means wait forever
+      #
+      # @return [ true, false ] depending on whether lock was acquired
       def lock(opts = {})
-        if opts[:nonblock] # XXX document
-          begin
-            lock_with_timeout :timeout => 0
-          rescue MutexLocked
-          end
-        elsif opts[:timeout]
-          lock_with_timeout opts
+        opts = { block: true, raise: true }.merge(opts)
+        if opts[:block]
+          timeout = opts[:timeout] || -1
+          lock_with_timeout timeout:
         else
-          spin_timeout = opts[:spin_timeout] || 1 # XXX document
           begin
-            lock_with_timeout :timeout => spin_timeout
+            lock_with_timeout timeout: 0
           rescue MutexLocked
-            retry
+            false # If non-blocking and unable to acquire lock, return false.
           end
         end
+      rescue MutexLocked
+        if opts[:raise]
+          raise
+        else
+          return false
+        end
       end
 
-      # Unlocks the mutex and returns true if successful. Otherwise this method
-      # raises a MutexLocked exception.
-      def unlock(*)
-        if aquired_lock?
-          decrease_counter
+      # The unlock method releases the mutex lock for the given name and
+      # returns true if successful. If the lock doesn't belong to this
+      # connection raises a MutexUnlockFailed exception.
+      #
+      # @param opts [ Hash ] the options hash
+      #
+      # @option opts [ true, false ] raise if false won't raise MutexUnlockFailed, defaults to true
+      # @option opts [ true, false ] force if true will force the lock to open, defaults to false
+      #
+      # @raise [ MutexUnlockFailed ] if unlocking failed and raise was true
+      #
+      # @return [ true, false ] true if unlocking was successful, false otherwise
+      def unlock(opts = {})
+        opts = { raise: true, force: false }.merge(opts)
+        if owned?
+          if opts[:force]
+            reset_counter
+          else
+            decrement_counter
+          end
           if counter_zero?
-            case query("SELECT RELEASE_LOCK(#{quote(name)})")
+            case query("SELECT RELEASE_LOCK(#{quote(internal_name)})")
             when 1
               true
             when 0, nil
               raise MutexUnlockFailed, "unlocking of mutex '#{name}' failed"
             end
+          else
+            false
           end
         else
           raise MutexUnlockFailed, "unlocking of mutex '#{name}' failed"
         end
+      rescue MutexUnlockFailed
+        if opts[:raise]
+          raise
+        else
+          return false
+        end
       end
 
-      # Unlock this mutex and return self if successful, otherwise (the mutex
-      # was not locked) nil is returned.
-      def unlock?(*a)
-        unlock(*a)
-        self
-      rescue MutexUnlockFailed
-        nil
+      # The unlock? method returns self if the mutex could successfully
+      # unlocked, otherwise it returns nil.
+      #
+      # @return [self, nil] self if the mutex was unlocked, nil otherwise
+      def unlock?(opts = {})
+        opts = { raise: false }.merge(opts)
+        self if unlock(opts)
       end
 
-      # Returns true if this mutex is unlocked at the moment.
+      # The unlocked? method checks whether the mutex is currently free and not
+      # locked by any database connection.
+      #
+      # @return [ true, false ] true if the mutex is unlocked, false otherwise
       def unlocked?
-        query("SELECT IS_FREE_LOCK(#{quote(name)})") == 1
+        query("SELECT IS_FREE_LOCK(#{quote(internal_name)})") == 1
       end
 
-      # Returns true if this mutex is locked at the moment.
+      # The locked? method returns true if this mutex is currently locked by
+      # any database connection, the opposite of {unlocked?}.
+      #
+      # @return [ true, false ] true if the mutex is locked, false otherwise
       def locked?
         not unlocked?
       end
 
-      # Returns true if this mutex is locked by this database connection.
-      def aquired_lock?
-        query("SELECT CONNECTION_ID() = IS_USED_LOCK(#{quote(name)})") == 1
+      # Returns true if the mutex is was acquired on this database connection.
+      def owned?
+        query("SELECT CONNECTION_ID() = IS_USED_LOCK(#{quote(internal_name)})") == 1
       end
 
-      # Returns true if this mutex is not locked by this database connection.
-      def not_aquired_lock?
-        not aquired_lock?
+      # Returns true if this mutex was not acquired on this database connection,
+      # the opposite of {owned?}.
+      def not_owned?
+        not owned?
       end
 
-      # Returns a string representation of this DatabaseMutex instance.
+      # The to_s method returns a string representation of this DatabaseMutex
+      # instance.
+      #
+      # @return [ String ] the string representation of this DatabaseMutex instance
       def to_s
         "#<#{self.class} #{name}>"
       end
@@ -132,43 +215,84 @@ module ActiveRecord
 
       private
 
+      # The quote method returns a string that is suitable for inclusion in an
+      # SQL query as the value of a parameter.
+      #
+      # @param value [ Object ] the object to be quoted
+      #
+      # @return [ String ] the quoted string
       def quote(value)
         ActiveRecord::Base.connection.quote(value)
       end
 
+      # The counter method generates a unique name for the mutex's internal
+      # counter variable. This name is used as part of the SQL query to set and
+      # retrieve the counter value.
+      #
+      # @return [String] the unique name for the mutex's internal counter variable.
       def counter
-        encoded_name = ?$ + Base64.encode64(name).delete('^A-Za-z0-9+/').
-          gsub(/[+\/]/, ?+ => ?_, ?/ => ?.)
-        if !self.class.check_size? || encoded_name.size <= 64 # mysql 5.7 only allows size <=64 variable names
-          "@#{encoded_name}"
-        end
+        "@#{internal_name}"
       end
 
-      def increase_counter
+      # The increment_counter method increments the internal counter value for
+      # this mutex instance.
+      def increment_counter
         query("SET #{counter} = IF(#{counter} IS NULL OR #{counter} = 0, 1, #{counter} + 1)")
       end
 
-      def decrease_counter
+      # The decrement_counter method decrements the internal counter value for #
+      # this mutex instance.
+      def decrement_counter
         query("SET #{counter} = #{counter} - 1")
       end
 
+      # The reset_counter method resets the internal counter value for this
+      # mutex instance to zero.
+      def reset_counter
+        query("SET #{counter} = 0")
+      end
+
+      # The counter_value method returns the current value of the internal
+      # counter variable for this mutex instance as an integer number.
+      #
+      # @return [ Integer ] the current value of the internal counter variable
       def counter_value
         query("SELECT #{counter}").to_i
       end
 
+      # The counter_zero? method checks whether the internal counter value for
+      # this mutex instance is zero.
+      #
+      # @return [ true, false ] true if the counter value is zero, false otherwise
       def counter_zero?
         counter_value.zero?
       end
 
+      # The lock_with_timeout method attempts to acquire the mutex lock for the
+      # given name and returns true if successful.
+      #
+      # If the :timeout option was given as a nonnegative value of seconds, it
+      # raises a MutexLocked exception if unable to acquire lock within that
+      # time period, otherwise the method blocks forever.
+      #
+      # @param opts [ Hash ] options hash containing the :timeout key
+      #
+      # @option opts [ Integer ] timeout, defaults to nil, but is required
+      #
+      # @raise [ ArgumentError ] if no :timeout option is provided in the options hash
+      # @raise [ MutexLocked ] if the mutex is already locked in another database connection
+      # @raise [ MutexSystemError ] if a system error occured
+      #
+      # @return [ true, false ] depending on whether lock was acquired
       def lock_with_timeout(opts = {})
-        if aquired_lock?
-          increase_counter
+        timeout = opts.fetch(:timeout) { raise ArgumentError, 'require :timeout argument' }
+        if owned?
+          increment_counter
           true
         else
-          timeout = opts[:timeout] || 1
-          case query("SELECT GET_LOCK(#{quote(name)}, #{timeout})")
+          case query("SELECT GET_LOCK(#{quote(internal_name)}, #{timeout})")
           when 1
-            increase_counter
+            increment_counter
             true
           when 0
             raise MutexLocked, "mutex '#{name}' is already locked"
@@ -178,6 +302,12 @@ module ActiveRecord
         end
       end
 
+      # The query method executes an SQL statement and returns the result.
+      #
+      # @param sql [ String ] the SQL statement to be executed
+      #
+      # @return [ Integer, nil ] the result of the SQL execution or nil if it
+      # failed
       def query(sql)
         if result = self.class.db.execute(sql)
           result = result.first.first.to_i
@@ -190,4 +320,3 @@ module ActiveRecord
     end
   end
 end
-

data/lib/active_record/database_mutex/version.rb

@@ -1,6 +1,6 @@
 module ActiveRecord::DatabaseMutex
   # ActiveRecord::DatabaseMutex version
-  VERSION         = '2.5.1'
+  VERSION         = '3.1.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/active_record/database_mutex.rb

@@ -1,6 +1,7 @@
 require 'active_record'
 require 'active_record/database_mutex/version'
 require 'active_record/database_mutex/implementation'
+require 'ostruct'
 
 module ActiveRecord
   # This module is mixed into ActiveRecord::Base to provide the mutex methods
@@ -9,42 +10,85 @@ module ActiveRecord
     # This is the base exception of all mutex exceptions.
     class MutexError < ActiveRecordError; end
 
-    # This exception is raised if a mutex of the given name isn't locked at the
-    # moment and unlock was called.
+    # This exception is raised when an attempt to unlock a mutex fails,
+    # typically due to the lock not being held by the current database
+    # connection or other system errors.
     class MutexUnlockFailed < MutexError; end
 
-    # This exception is raised if a mutex of the given name is locked at the
-    # moment and lock was called again.
+    # This exception is raised when attempting to acquire a lock that is
+    # already held by another database connection.
     class MutexLocked < MutexError; end
 
+    # This exception raised when an unexpected situation occurs while managing
+    # the mutex lock, such as incorrect encoding or handling of internal mutex
+    # names.
     class MutexInvalidState < MutexError; end
 
+    # This exception is raised when an unexpected system-related issue prevents
+    # the mutex (lock) from being acquired or managed properly, often due to
+    # disk I/O errors, database connection issues, resource limitations, or
+    # lock file permissions problems.
     class MutexSystemError < MutexError; end
 
+    # The MutexInfo class is a subclass of OpenStruct, serving as a wrapper for
+    # information related to database mutexes. It allows dynamic attribute
+    # access.
+    MutexInfo = Class.new OpenStruct
+
     def self.included(modul)
       modul.instance_eval do
         extend ClassMethods
       end
     end
 
-    # Return a mutex implementation for the mutex named +name+.
+    # The for method returns an instance of
+    # ActiveRecord::DatabaseMutex::Implementation that is initialized with the
+    # given name.
+    #
+    # @param name [ String ] the mutex name
+    #
+    # @return [ ActiveRecord::DatabaseMutex::Implementation ]
     def self.for(name)
-      Implementation.new(:name => name)
+      Implementation.new(name: name)
     end
 
     module ClassMethods
-      # Returns a mutex instance for this ActiveRecord subclass.
+      def mutex_name
+        @mutex_name ||= [ name, defined?(Rails) ? Rails.env : ENV['RAILS_ENV'] ].compact * ?@
+      end
+
+      # The mutex method returns an instance of
+      # ActiveRecord::DatabaseMutex::Implementation that is initialized with
+      # the name given by the class and environment variables.
+      #
+      # @return [ActiveRecord::DatabaseMutex::Implementation] the mutex instance
       def mutex
-        @mutex ||= Implementation.new(
-          :name => [ name, defined?(Rails) ? Rails.env : ENV['RAILS_ENV'] ].compact * ?@
-        )
+        @mutex ||= Implementation.new(name: mutex_name)
+      end
+
+      # The all_mutexes method returns an array of MutexInfo objects
+      # representing all mutexes currently held by database connections. The
+      # MutexInfo#OBJECT_NAME is the
+      # {ActiveRecord::DatabaseMutex::Implementation#internal_name}.
+      #
+      # @return [Array] An array of MutexInfo objects.
+      def all_mutexes
+        connection.select_all(<<~EOT).map { MutexInfo.new(_1) }
+          SELECT * FROM performance_schema.metadata_locks
+          WHERE OBJECT_TYPE = 'USER LEVEL LOCK'
+          AND OBJECT_NAME LIKE "$%"
+        EOT
       end
     end
 
-    # Returns a mutex instance for this ActiveRecord instance.
+    # The mutex method returns an instance of
+    # ActiveRecord::DatabaseMutex::Implementation that is initialized with the
+    # name given by the id, the class and environment variables.
+    #
+    # @return [ActiveRecord::DatabaseMutex::Implementation] the mutex instance
     def mutex
       if persisted?
-        @mutex ||= Implementation.new(:name => "#{id}@#{self.class.name}")
+        @mutex ||= Implementation.new(name: "#{id}@#{self.class.mutex_name}")
       else
         raise MutexInvalidState, "instance #{inspect} not persisted"
       end