active_record_mutex 2.5.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c06234eeb9430aa24c776af33c606bd631ca1dac
-  data.tar.gz: dbf5f5346968fa6918f8bb4aa9d46bdfb973754f
+SHA256:
+  metadata.gz: 337ab2cfb637dc992dda05b67bc12098b0d8d7266591dc741d4918dbb3238aee
+  data.tar.gz: e812c787de8cb82696027803eafa426793af334d4c1d847c9956473a7d1faf20
 SHA512:
-  metadata.gz: 54758225bd9d0e17e8f8eafada346686df7023f3d152da0e5af5bf233d0cc167cee453350c1f2fb85d12b7b422de690137e6c2f037b47470bf4abc3e0140939c
-  data.tar.gz: 869b14192f5ea6b7ded849e22d54fa1dc6eed56d15fed0de0ffedb18a8ff871f195bbf11c6e11cf6fc87880a443e2bdf05c8b2062fe46074ccff1cf9d309f20a
+  metadata.gz: f8cb37ec99b0a52267f964b032b8f061801bef3000a11d355af5cddef3d5f075c471bd51e3fa79310136cbc53b3cd0376c293a501363b4f48f979fc774f03efc
+  data.tar.gz: 1418b58e067e151bb33e92cdd7beb215cb3fdce4ea9f7439e34ae6315b452c80d9e0cafa5f368f399ec2abb7d48c0479a1a233b1fc01f4ff364043042647faa1

data/.envrc

@@ -0,0 +1 @@
+export DATABASE_URL="mysql2://root@127.0.0.1:3336/test"

data/CHANGES.md

@@ -0,0 +1,151 @@
+# Changes
+
+## 2024-10-16 v3.1.0
+
+* Changes for **3.1.0**:
+  * Implemented `all_mutexes` method in ActiveRecord::DatabaseMutex
+  * Added `MutexInfo` class as a subclass of OpenStruct
+  * Updated `active_record_mutex.gemspec` to use **0.6** version of `ostruct`
+  * Removed `tins` dependency
+
+## 2024-10-15 v3.0.0
+
+### Major Enhancements
+
+* **Renamed method names**: Updated `acquired_lock?` to `owned?` and
+  `not_aquired_lock?` to `not_owned?` to better reflect their functionality.
+* **Enhanced documentation**: Improved documentation for several methods,
+  providing clearer explanations of their purpose and behavior.
+* **Synchronize method updates**: The synchronize method now accepts a `:block`
+  option instead of `:nonblock`, allowing for more flexibility in locking and
+  unlocking mutexes. Additionally, the `lock` method has been updated to handle
+  this new option.
+
+### New Features
+
+* **Timeout handling**: Introduced the `:raise` option to the lock method,
+  which defaults to true. If set to false, no MutexLocked exception is raised
+  when the timeout expires.
+* **Internal name generation**: Added the `internal_name` method for generating
+  internal mutex names, replacing encoded names in counter logic.
+* **Improved unlock behavior**: Modified the unlock method to raise
+  MutexUnlockFailed if the lock doesn't belong to this connection or return
+  false if `:raise` is false.
+
+### Refactorings
+
+* **Simplified database setup**: Updated test helper to use a more
+  straightforward approach for setting up databases.
+* **Ensured counter length**: Added checks to ensure counter names are within
+  the allowed range, preventing potential issues with MySQL variable name
+  lengths.
+* **Refactored support for DATABASE_URL**: Improved support for the
+  `DATABASE_URL` environment variable in tests.
+
+### Other Changes
+
+* **Updated documentation**: Reflected current gem installation methods and API
+  changes in README.md.
+* **Improved testing**: Added test cases for lock acquisition, release, and
+  timeout handling, as well as multiple threads scenarios.
+* **Removed Travis CI config**: Removed configuration files related to Ruby
+  versioning and CodeClimate reporting.
+
+### Documentation Updates
+
+* **Added CHANGES.md file**: Included a changelog file to keep track of changes
+  across releases.
+* **Refactored database mutex documentation**: Improved documentation for
+  methods and exception classes.
+* **Updated test cases**: Updated example usage, test updates, and refactorings
+  related to the `DATABASE_URL` environment variable.
+
+## 2016-12-07 v2.5.1
+
+* **Specify correct version of activerecord**
+
+## 2016-12-07 v2.5.0
+
+* Be compatible with rails ~>5.0 versions
+  + Updated dependencies to support Rails **5.0**
+* Start simplecov
+  + Added SimpleCov integration using `simplecov`
+* use command to push reports
+  + Updated CodeClimate reporting to use a custom command
+* Use new way to use codeclimate
+  + Switched to the latest CodeClimate API usage method
+
+## 2016-11-23 v2.4.0
+
+* Revert changes made in later **2.3** versions
+* Only check size for `mysql` version `>= 5.7`
+
+## 2016-09-07 v2.3.8
+
+* **Significant Changes**
+  + Test more rubies
+  + Use a normal table for counters instead of temporary tables to avoid issues
+    on replicating setups with enforced GTID consistency.
+
+…
+
+## 2016-08-24 v2.3.3
+
+* **Only check size for MySQL version >= 5.7**
+  + Changed logic to only consider size checks for MySQL versions greater than
+    or equal to **5.7**.
+
+## 2016-08-23 v2.3.2
+
+* **Restrictions on variable name length**:
+  + Added check to prevent long variable names in MySQL 5.7
+
+## 2016-08-23 v2.3.1
+
+* **Encode counter name to conform to MySQL rules**
+  + Changed `counter_name` to use
+  `code:mysql_real_escape_string(code:counter_name)` in the code.
+
+## 2016-08-23 v2.3.0
+
+* Use shorter method names
+* Implement counter logic to allow nesting of locks (using `code`: `counter_logic`)
+* Work with mysql 5.5 and 5.6 semantics
+
+## 2016-08-19 v2.2.1
+
+* **Added support for `Rails.env`**
+  + Now uses `Rails.env` instead of hardcoded environment variable names.
+
+## 2016-08-19 v2.2.0
+
+* Make locks rails environments independent
+* Disable workaround for wonky mysql behavior
+  + Use `simplecov` for code coverage instead of a workaround
+* Update to work with Rails environments independently 
+
+## 2014-12-12 v2.0.0
+
+#### Changes
+
+* Change semantic of `ActiveRecord::Base#mutex`
+
+#### Documentation
+
+* Improve and reflect changes
+* Add license information
+* Add codeclimate token
+
+## 2013-11-18 v1.0.1
+
+* **Avoid annoying rubygems warning**
+  + Added a fix to prevent the RubyGems warning from appearing.
+
+## 2012-05-07 v1.0.0
+
+* **Avoid conflicts with top level `Mutex` class**
+  + Changes to avoid naming conflict with Ruby's built-in `Mutex` class.
+
+## 2011-07-18 v0.0.1
+
+  * Start

data/Gemfile

@@ -3,5 +3,3 @@
 source 'https://rubygems.org'
 
 gemspec
-
-gem "codeclimate-test-reporter", group: :test, require: nil

data/README.md

@@ -12,33 +12,123 @@ You can use rubygems to fetch the gem and install it for you:
 
     # gem install active_record_mutex
 
-You can also put this line into your Rails environment.rb file
+You can also put this line into your Gemfile
 
-    config.gem 'active_record_mutex'
-
-and install the gem via
-
-    $ rake gems:install
+    gem 'active_record_mutex'
 
 ## Usage
 
-If you want to synchronize method calls to your model's methods you can easily
-do this by passing a mutex instance to ActiveRecord's synchronize class method.
-This mutex instance will be named Foo like the ActiveRecord was named:
+### Using synchronize for critical sections
+
+To synchronize on a specific ActiveRecord instance you can do this:
 
-  class Foo < ActiveRecord::Base
-    def foo
+    class Foo < ActiveRecord::Base
     end
 
-    synchronize :foo, :with => :mutex
-  end
+    foo = Foo.find(666)
+    foo.mutex.synchronize do
+      # Critical section of code here
+    end
 
 If you want more control over the mutex and/or give it a special name you can
 create Mutex instance like this:
 
-    my_mutex = ActiveRecord::Mutex::Mutex.new(:name => 'my_mutex')
+    my_mutex = ActiveRecord::DatabaseMutex.for('my_mutex')
+
+Now you can send all messages directly to the Mutex instance or use the custom
+mutex instance to `synchronize` method calls or other operations:
+
+    my_mutex.synchronize do
+      # Critical section of code here
+    end
+
+### Low-Level Demonstration: Multiple Process Example
+
+The following example demonstrates how the Mutex works at a lower level, using
+direct MySQL connections. This is not intended as a real-world use case, but
+rather to illustrate the underlying behavior.
+
+If two processes are connected to the same database, configured via e.g.
+`DATABASE_URL=mysql2://root@127.0.0.1:3336/test` and this is process 1:
+
+    # process1.rb
+    …
+    mutex = ActiveRecord::DatabaseMutex.for('my_mutex')
+
+    lock_result1 = mutex.lock(timeout: 5)
+    puts "Process 1: Lock acquired (first): #{lock_result1}"
+
+    puts "Process 1: Waiting for 10s"
+    sleep(10)
+
+    lock_result2 = mutex.lock(timeout: 5)
+    puts "Process 1: Lock acquired (second): #{lock_result2}"
+
+    mutex.unlock # first
+    mutex.unlock # second
+
+    puts "Process 1: Unlocked the mutex twice"
+
+    puts "Process 1: Waiting for 10s"
+    sleep(10)
+
+    puts "Process 1: Exiting"
+
+and this process 2:
+
+    # process2.rb
+    …
+    mutex = ActiveRecord::DatabaseMutex.for('my_mutex')
+
+    begin
+      lock_result3 = mutex.lock(timeout: 5)
+      puts "Process 2: Lock acquired (first): #{lock_result3}"
+    rescue ActiveRecord::DatabaseMutex::MutexLocked
+      puts "Process 2: Mutex locked by another process, waiting..."
+    end
+
+    puts "Process 2: Waiting for 10s"
+    sleep(10)
+
+    puts "Process 2: Trying to lock again"
+    lock_result4 = mutex.lock(timeout: 5)
+    puts "Process 2: Lock acquired (second): #{lock_result4}"
+
+    puts "Process 2: Exiting"
+
+Running these processes in parallel will output the following:
+
+    Process 1: Lock acquired (first): true
+    Process 1: Waiting for 10s
+    Process 2: Mutex locked by another process, waiting...
+    Process 2: Waiting for 10s
+    Process 1: Lock acquired (second): true
+    Process 1: Unlocked the mutex twice
+    Process 1: Waiting for 10s
+    Process 2: Trying to lock again
+    Process 2: Lock acquired (second): true
+    Process 2: Exiting
+    Process 1: Exiting
+
+The two ruby files can be found in the examples subdirectory as
+`examples/process1.rb` and `examples/process2.rb`. The necessary configuration
+files, `.envrc` (`direnv allow`) and `docker-compose.yml`
+(`docker compose up -d`), are also located in the root of this repository.
+
+## Running the tests
+
+First start mysql in docker via `docker compose up -d` and configure your
+environment via `direnv allow` as before and then run
+
+    rake test
+
+or with coverage:
+
+    rake test START_SIMPLECOV=1
+
+To test for different ruby versions in docker, run:
 
-Now you can send all messages directly to the Mutex instance.
+    all_images
 
 ## Download
 

data/Rakefile

@@ -14,13 +14,16 @@ GemHadar do
   test_dir    'test'
   ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', '.DS_Store', 'coverage',
     '.byebug_history'
+  package_ignore '.all_images.yml', '.utilsrc', '.gitignore', 'VERSION',
+    *Dir.glob('.github/**/*', File::FNM_DOTMATCH)
   readme      'README.md'
   licenses    << 'GPL-2'
 
-  dependency             'mysql2',       '~>0.3.0'
-  dependency             'activerecord', '>= 4.0', '<6'
-  dependency             'tins',         '~> 1.12'
-  development_dependency 'test-unit',    '~>3.0'
-  development_dependency 'byebug'
+  dependency             'mysql2',       '~> 0.3'
+  dependency             'activerecord', '>= 4.0'
+  dependency             'ostruct',      '~> 0.6'
+  development_dependency 'all_images',   '~> 0.6'
+  development_dependency 'test-unit',    '~> 3.0'
+  development_dependency 'debug'
   development_dependency 'simplecov'
 end

data/active_record_mutex.gemspec

@@ -1,52 +1,33 @@
 # -*- encoding: utf-8 -*-
-# stub: active_record_mutex 2.5.1 ruby lib
+# stub: active_record_mutex 3.1.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "active_record_mutex".freeze
-  s.version = "2.5.1"
+  s.version = "3.1.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
   s.authors = ["Florian Frank".freeze]
-  s.date = "2016-12-07"
+  s.date = "2024-10-16"
   s.description = "Mutex that can be used to synchronise ruby processes via an ActiveRecord datababase connection. (Only Mysql is supported at the moment.)".freeze
   s.email = "flori@ping.de".freeze
   s.extra_rdoc_files = ["README.md".freeze, "lib/active_record/database_mutex.rb".freeze, "lib/active_record/database_mutex/implementation.rb".freeze, "lib/active_record/database_mutex/version.rb".freeze, "lib/active_record/mutex.rb".freeze, "lib/active_record_mutex.rb".freeze]
-  s.files = [".gitignore".freeze, ".travis.yml".freeze, "COPYING".freeze, "Gemfile".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "active_record_mutex.gemspec".freeze, "lib/active_record/database_mutex.rb".freeze, "lib/active_record/database_mutex/implementation.rb".freeze, "lib/active_record/database_mutex/version.rb".freeze, "lib/active_record/mutex.rb".freeze, "lib/active_record_mutex.rb".freeze, "test/database_mutex_test.rb".freeze, "test/test_helper.rb".freeze]
+  s.files = [".envrc".freeze, "CHANGES.md".freeze, "COPYING".freeze, "Gemfile".freeze, "README.md".freeze, "Rakefile".freeze, "active_record_mutex.gemspec".freeze, "docker-compose.yml".freeze, "examples/process1.rb".freeze, "examples/process2.rb".freeze, "lib/active_record/database_mutex.rb".freeze, "lib/active_record/database_mutex/implementation.rb".freeze, "lib/active_record/database_mutex/version.rb".freeze, "lib/active_record/mutex.rb".freeze, "lib/active_record_mutex.rb".freeze, "test/database_mutex_test.rb".freeze, "test/test_helper.rb".freeze]
   s.homepage = "http://github.com/flori/active_record_mutex".freeze
   s.licenses = ["GPL-2".freeze]
   s.rdoc_options = ["--title".freeze, "ActiveRecordMutex - Implementation of a Mutex for Active Record".freeze, "--main".freeze, "README.md".freeze]
-  s.rubygems_version = "2.6.8".freeze
+  s.rubygems_version = "3.5.18".freeze
   s.summary = "Implementation of a Mutex for Active Record".freeze
   s.test_files = ["test/database_mutex_test.rb".freeze, "test/test_helper.rb".freeze]
 
-  if s.respond_to? :specification_version then
-    s.specification_version = 4
+  s.specification_version = 4
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.9.1"])
-      s.add_development_dependency(%q<test-unit>.freeze, ["~> 3.0"])
-      s.add_development_dependency(%q<byebug>.freeze, [">= 0"])
-      s.add_development_dependency(%q<simplecov>.freeze, [">= 0"])
-      s.add_runtime_dependency(%q<mysql2>.freeze, ["~> 0.3.0"])
-      s.add_runtime_dependency(%q<activerecord>.freeze, ["< 6", ">= 4.0"])
-      s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.12"])
-    else
-      s.add_dependency(%q<gem_hadar>.freeze, ["~> 1.9.1"])
-      s.add_dependency(%q<test-unit>.freeze, ["~> 3.0"])
-      s.add_dependency(%q<byebug>.freeze, [">= 0"])
-      s.add_dependency(%q<simplecov>.freeze, [">= 0"])
-      s.add_dependency(%q<mysql2>.freeze, ["~> 0.3.0"])
-      s.add_dependency(%q<activerecord>.freeze, ["< 6", ">= 4.0"])
-      s.add_dependency(%q<tins>.freeze, ["~> 1.12"])
-    end
-  else
-    s.add_dependency(%q<gem_hadar>.freeze, ["~> 1.9.1"])
-    s.add_dependency(%q<test-unit>.freeze, ["~> 3.0"])
-    s.add_dependency(%q<byebug>.freeze, [">= 0"])
-    s.add_dependency(%q<simplecov>.freeze, [">= 0"])
-    s.add_dependency(%q<mysql2>.freeze, ["~> 0.3.0"])
-    s.add_dependency(%q<activerecord>.freeze, ["< 6", ">= 4.0"])
-    s.add_dependency(%q<tins>.freeze, ["~> 1.12"])
-  end
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.19".freeze])
+  s.add_development_dependency(%q<all_images>.freeze, ["~> 0.6".freeze])
+  s.add_development_dependency(%q<test-unit>.freeze, ["~> 3.0".freeze])
+  s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])
+  s.add_runtime_dependency(%q<mysql2>.freeze, ["~> 0.3".freeze])
+  s.add_runtime_dependency(%q<activerecord>.freeze, [">= 4.0".freeze])
+  s.add_runtime_dependency(%q<ostruct>.freeze, ["~> 0.6".freeze])
 end

data/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  mysql:
+    image: mysql:8.0
+    restart: unless-stopped
+    ports:
+    - "127.0.0.1:3336:3306"
+    volumes:
+    - "mysql-data:/var/lib/mysql:delegated"
+    environment:
+      - "MYSQL_ALLOW_EMPTY_PASSWORD=1"
+
+volumes:
+  mysql-data:

data/examples/process1.rb

@@ -0,0 +1,31 @@
+# process1.rb
+
+require 'active_record_mutex'
+
+database_url = URI.parse(ENV.fetch('DATABASE_URL'))
+database = File.basename(database_url.path)
+database_url_without_db = database_url.dup.tap { _1.path = '' }
+ch = ActiveRecord::Base.establish_connection(database_url_without_db.to_s)
+ch.with_connection { _1.execute %{ CREATE DATABASE IF NOT EXISTS #{database} } }
+ActiveRecord::Base.establish_connection(database_url.to_s)
+
+mutex = ActiveRecord::DatabaseMutex.for('my_mutex')
+
+lock_result1 = mutex.lock(timeout: 5)
+puts "Process 1: Lock acquired (first): #{lock_result1}"
+
+puts "Process 1: Waiting for 10s"
+sleep(10)
+
+lock_result2 = mutex.lock(timeout: 5)
+puts "Process 1: Lock acquired (second): #{lock_result2}"
+
+mutex.unlock # first
+mutex.unlock # second
+
+puts "Process 1: Unlocked the mutex twice"
+
+puts "Process 1: Waiting for 10s"
+sleep(10)
+
+puts "Process 1: Exiting"

data/examples/process2.rb

@@ -0,0 +1,28 @@
+# process2.rb
+
+require 'active_record_mutex'
+
+database_url = URI.parse(ENV.fetch('DATABASE_URL'))
+database = File.basename(database_url.path)
+database_url_without_db = database_url.dup.tap { _1.path = '' }
+ch = ActiveRecord::Base.establish_connection(database_url_without_db.to_s)
+ch.with_connection { _1.execute %{ CREATE DATABASE IF NOT EXISTS #{database} } }
+ActiveRecord::Base.establish_connection(database_url.to_s)
+
+mutex = ActiveRecord::DatabaseMutex.for('my_mutex')
+
+begin
+  lock_result3 = mutex.lock(timeout: 5)
+  puts "Process 2: Lock acquired (first): #{lock_result3}"
+rescue ActiveRecord::DatabaseMutex::MutexLocked
+  puts "Process 2: Mutex locked by another process, waiting..."
+end
+
+puts "Process 2: Waiting for 10s"
+sleep(10)
+
+puts "Process 2: Trying to lock again"
+lock_result4 = mutex.lock(timeout: 5)
+puts "Process 2: Lock acquired (second): #{lock_result4}"
+
+puts "Process 2: Exiting"