mongoid-locker 0.3.5 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f041c4f1e34322978f337ddf9aa20727aa152974
-  data.tar.gz: 7be9a12c2137ae7174a16956742a418cff02470a
+SHA256:
+  metadata.gz: 4dc56290fe20687a98a9a031da8334d833f76b64ce44ae28efb1a8facf5db9eb
+  data.tar.gz: a8c1dccc297c272bc46182e9adc5409c9d9d8add0fd66492bad3344811a896f3
 SHA512:
-  metadata.gz: beb254ea3282c54d9977703ecd9d670b9caf17e1ce1cfa598169b8d1f3a981654fbdf4b0bb2ddc626a3dfb7f2ac06c6e5858ee3531e70e8a850593e57a9bec4b
-  data.tar.gz: 96966c6237c4081b4477d0e774cddc131392c40d7125c782f5f427daaf881b9e45466eecd0fb331d28cd737f2badfbf48e3de4049db69d3ed24117c34579adef
+  metadata.gz: b73d8474bbdc7f106ff2d562614937c9cfeb1c925a3d6dd01f7d50cc57ffca2e742ff34c6c192f6cde7e86a9766939b4aa96b10e280a4e5a6109180aa981e793
+  data.tar.gz: 8d31f7452bd7d83bf2c54373c309698135f066a32bf006b608fc70fb1caf0bfed15fc6c38b1cc08b7e804ed0cbf1c27bc691b32997331c2e035a3408b383d57a

data/.gitignore

@@ -1,19 +1,14 @@
-# rcov
+# simplecov
 coverage
-coverage.data
-
-# rdoc
-rdoc
 
 # yard
 doc
 .yardoc
 
 # bundler
+pkg
 .bundle
+Gemfile.lock
 
 # guard
 tmp
-
-# bundler
-Gemfile.lock

data/.rspec

@@ -1,2 +1 @@
---color
---format documentation
+--require spec_helper

data/.rubocop.yml

@@ -1,7 +1,2 @@
-AllCops:
-  Exclude:
-    - vendor/**/*
-    - bin/**/*
-    - mongoid-locker.gemspec
-
 inherit_from: .rubocop_todo.yml
+require: rubocop-rspec

data/.rubocop_todo.yml

@@ -1,58 +1,139 @@
-# This configuration was generated by `rubocop --auto-gen-config`
-# on 2015-10-21 11:03:44 -0400 using RuboCop version 0.29.1.
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2020-04-05 22:21:29 +0300 using RuboCop version 0.81.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 1
+# Offense count: 3
+# Configuration parameters: Include.
+# Include: **/*.gemfile, **/Gemfile, **/gems.rb
+Bundler/DuplicatedGem:
+  Exclude:
+    - 'Gemfile'
+
+# Offense count: 2
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - 'spec/test_examples_spec.rb'
+
+# Offense count: 4
+# Configuration parameters: IgnoredMethods.
 Metrics/AbcSize:
-  Max: 18
+  Max: 24
 
-# Offense count: 37
-# Configuration parameters: AllowURI, URISchemes.
-Metrics/LineLength:
-  Max: 184
+# Offense count: 11
+# Configuration parameters: CountComments, ExcludedMethods.
+# ExcludedMethods: refine
+Metrics/BlockLength:
+  Max: 290
 
-# Offense count: 3
-# Configuration parameters: CountComments.
+# Offense count: 5
+# Configuration parameters: CountComments, ExcludedMethods.
 Metrics/MethodLength:
-  Max: 25
+  Max: 31
 
-# Offense count: 6
-# Cop supports --auto-correct.
-Style/Blocks:
-  Enabled: false
-
-# Offense count: 3
-Style/Documentation:
-  Enabled: false
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/ModuleLength:
+  Max: 105
 
 # Offense count: 2
-Style/DoubleNegation:
-  Enabled: false
+# Configuration parameters: ExpectMatchingDefinition, Regex, IgnoreExecutableScripts, AllowedAcronyms.
+# AllowedAcronyms: CLI, DSL, ACL, API, ASCII, CPU, CSS, DNS, EOF, GUID, HTML, HTTP, HTTPS, ID, IP, JSON, LHS, QPS, RAM, RHS, RPC, SLA, SMTP, SQL, SSH, TCP, TLS, TTL, UDP, UI, UID, UUID, URI, URL, UTF8, VM, XML, XMPP, XSRF, XSS
+Naming/FileName:
+  Exclude:
+    - 'lib/mongoid-locker.rb'
+    - 'spec/mongoid-locker_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros.
+# NamePrefix: is_, has_, have_
+# ForbiddenPrefixes: is_, has_, have_
+# AllowedMethods: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicateName:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/mongoid/locker.rb'
 
 # Offense count: 2
-# Configuration parameters: Exclude.
-Style/FileName:
-  Enabled: false
+RSpec/BeforeAfterAll:
+  Exclude:
+    - 'spec/spec_helper.rb'
+    - 'spec/rails_helper.rb'
+    - 'spec/support/**/*.rb'
+    - 'spec/test_examples_spec.rb'
+
+# Offense count: 12
+# Configuration parameters: Prefixes.
+# Prefixes: when, with, without
+RSpec/ContextWording:
+  Exclude:
+    - 'spec/support/configurations_shared_context.rb'
+    - 'spec/support/populate_database_shared_context.rb'
+    - 'spec/support/reset_shared_context.rb'
 
 # Offense count: 1
-# Configuration parameters: NamePrefix, NamePrefixBlacklist.
-Style/PredicateName:
-  Enabled: false
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/test_examples_spec.rb'
+
+# Offense count: 8
+# Configuration parameters: Max.
+RSpec/ExampleLength:
+  Exclude:
+    - 'spec/support/locker_is_included_shared_examples.rb'
+    - 'spec/test_examples_spec.rb'
 
 # Offense count: 1
-# Configuration parameters: SupportedStyles.
-Style/RaiseArgs:
-  EnforcedStyle: compact
+# Configuration parameters: CustomTransform, IgnoreMethods.
+RSpec/FilePath:
+  Exclude:
+    - 'spec/mongoid-locker_spec.rb'
 
-# Offense count: 2
-Style/RegexpLiteral:
-  MaxSlashes: 0
+# Offense count: 7
+RSpec/LeakyConstantDeclaration:
+  Exclude:
+    - 'spec/support/configurations_shared_context.rb'
+    - 'spec/test_examples_spec.rb'
+
+# Offense count: 12
+# Configuration parameters: .
+# SupportedStyles: have_received, receive
+RSpec/MessageSpies:
+  EnforcedStyle: receive
+
+# Offense count: 10
+# Configuration parameters: AggregateFailuresByDefault.
+RSpec/MultipleExpectations:
+  Max: 3
 
 # Offense count: 1
+RSpec/SubjectStub:
+  Exclude:
+    - 'spec/support/delegated_methods_shared_examples.rb'
+
+# Offense count: 2
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/mongoid/locker.rb'
+
+# Offense count: 2
+# Cop supports --auto-correct.
+# Configuration parameters: AutoCorrect, EnforcedStyle, IgnoredMethods.
+# SupportedStyles: predicate, comparison
+Style/NumericPredicate:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/mongoid/locker.rb'
+
+# Offense count: 35
 # Cop supports --auto-correct.
-# Configuration parameters: ExactNameMatch, AllowPredicates, AllowDSLWriters, Whitelist.
-Style/TrivialAccessors:
-  Enabled: false
+# Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 250

data/.travis.yml

@@ -5,30 +5,50 @@ language: ruby
 
 cache: bundler
 
-before_install:
-  - gem update --system
-  - gem install bundler
+script:
+  - bundle exec rspec
+
+rvm:
+  - 2.3.8
+  - 2.4.7
+  - 2.5.7
+  - 2.6.6
+  - 2.7.1
+  - jruby-9.1.17.0
+  - jruby-9.2.11.1
+
+env:
+  - MONGOID_VERSION=5
+  - MONGOID_VERSION=6
+  - MONGOID_VERSION=7
 
 matrix:
   include:
-    - rvm: 2.3.1
-      env: MONGOID_VERSION=2
-    - rvm: 2.3.1
-      env: MONGOID_VERSION=3
-    - rvm: 2.3.1
-      env: MONGOID_VERSION=4
-    - rvm: 2.3.1
-      env: MONGOID_VERSION=5
-    - rvm: 2.3.1
-      env: MONGOID_VERSION=6
+    - rvm: 2.6.6
+      env:
+        - MONGOID_VERSION=7
+        - COVERAGE=true
       before_script:
+        - bundle exec rubocop
         - bundle exec danger
-    - rvm: rbx-2
+      after_script:
+        - if [[ "$TRAVIS_TEST_RESULT" == 0 ]]; then
+            curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter;
+            chmod +x ./cc-test-reporter;
+            ./cc-test-reporter before-build;
+            ./cc-test-reporter format-coverage -t simplecov -o coverage/codeclimate.json coverage/.resultset.json;
+            ./cc-test-reporter upload-coverage;
+          fi
     - rvm: ruby-head
+      env: MONGOID_VERSION=7
     - rvm: jruby-head
+      env: MONGOID_VERSION=7
+  exclude:
+    - rvm: 2.7.1
+      env: MONGOID_VERSION=5
+  fast_finish: true
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
-    - rvm: rbx-2
 
 bundler_args: --without development

data/CHANGELOG.md

@@ -1,6 +1,39 @@
 ## Changelog
 
-### 0.3.5 (1/24/2017)
+### 2.0.1 (2020-06-17)
+
+* [#86](https://github.com/mongoid/mongoid-locker/pull/86): Upgraded to RuboCop 0.81.0 - [@dks17](https://github.com/dks17).
+* [#86](https://github.com/mongoid/mongoid-locker/pull/86): Fixed issue with `ruby` `delegate` method - [@dks17](https://github.com/dks17).
+* [#86](https://github.com/mongoid/mongoid-locker/pull/86): Update Ruby and JRUby versions for Travis config - [@dks17](https://github.com/dks17).
+* [#88](https://github.com/mongoid/mongoid-locker/pull/88): Add RSpec test examples - [@dks17](https://github.com/dks17).
+
+### 2.0.0 (2019-10-23)
+
+* [#79](https://github.com/mongoid/mongoid-locker/pull/79): Update find_and_lock and find_and_unlock methods - [@dks17](https://github.com/dks17).
+* [#78](https://github.com/mongoid/mongoid-locker/pull/78): Upgrade to v2.0 - [@dks17](https://github.com/dks17).
+* [#83](https://github.com/mongoid/mongoid-locker/pull/83): Upgraded to RuboCop 0.75.1 - [@dblock](https://github.com/dblock).
+
+### 1.0.1 (2019-03-23)
+
+* [#74](https://github.com/mongoid/mongoid-locker/pull/74): Add JRuby tests - [@dks17](https://github.com/dks17).
+* [#68](https://github.com/mongoid/mongoid-locker/pull/68): Fix Rubocop offenses, refactoring, update `ruby` versions, add `COVERAGE` test env, update `.travis.yml` matrix - [@dks17](https://github.com/dks17).
+* [#67](https://github.com/mongoid/mongoid-locker/pull/67): Deprecate `:wait` in favor of `:retries` option, which can attempt to grab a lock multiple times - [@afeld](https://github.com/afeld), [@dks17](https://github.com/dks17).
+* [#66](https://github.com/mongoid/mongoid-locker/pull/66): Fix Mongoid::Locker::LockError for not persisted document - [@dks17](https://github.com/dks17).
+* [#65](https://github.com/mongoid/mongoid-locker/pull/65): Drop `mongoid-compatibility` gem dependency - [@dks17](https://github.com/dks17).
+* [#64](https://github.com/mongoid/mongoid-locker/pull/64): Exclude demo files from the gem - [@dks17](https://github.com/dks17).
+* [#60](https://github.com/mongoid/mongoid-locker/pull/60): Drop support for `mongoid` version `2` and `3` - [@dks17](https://github.com/dks17).
+* [#60](https://github.com/mongoid/mongoid-locker/pull/60): Add SimpleCov - [@dks17](https://github.com/dks17).
+
+### 1.0.0 (2018-09-02)
+
+* [#57](https://github.com/mongoid/mongoid-locker/pull/57): `Time.now` replaced by `Time.now.utc` - [@dks17](https://github.com/dks17).
+* [#55](https://github.com/mongoid/mongoid-locker/pull/55): Customizable :locked_at and :locked_until fields - [@dks17](https://github.com/dks17).
+
+### 0.3.6 (2018-04-18)
+
+* [#52](https://github.com/mongoid/mongoid-locker/pull/52): Added support for Mongoid 7 - [@wuhuizuo](https://github.com/wuhuizuo).
+
+### 0.3.5 (2017-01-24)
 
 * [#43](https://github.com/mongoid/mongoid-locker/pull/43): Added support for Mongoid 6 - [@sivagollapalli](https://github.com/sivagollapalli).
 * [#38](https://github.com/mongoid/mongoid-locker/issues/38): Fixed unlock already destroyed object - [@sivagollapalli](https://github.com/sivagollapalli).

data/Dangerfile

@@ -1 +1,3 @@
-danger.import_dangerfile(gem: "mongoid-danger")
+# frozen_string_literal: true
+
+danger.import_dangerfile(gem: 'mongoid-danger')

data/Gemfile

@@ -1,34 +1,31 @@
-source 'http://rubygems.org'
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
 
 case ENV['MONGOID_VERSION']
+when /^7/
+  gem 'mongoid', '~> 7.0'
 when /^6/
-  gem 'mongoid', '~> 6.0'
+  gem 'mongoid', '~> 6.4'
 when /^5/
-  gem 'mongoid', '~> 5.0'
-when /^4/
-  gem 'mongoid', '~> 4.0'
-when /^3/
-  gem 'mongoid', '~> 3.1'
-when /^2/
-  gem 'bson_ext', platforms: :ruby
-  gem 'mongoid', '~> 2.8'
+  gem 'mongoid', '~> 5.4'
 else
-  gem 'mongoid', '>= 2.8', '< 6.0'
+  gem 'mongoid', '>= 5.0'
 end
 
-gemspec
+gem 'rake'
 
 group :development do
-  gem 'bundler', '~> 1.1'
   gem 'guard-rspec'
-  gem 'rb-fsevent', '~> 0.9.1'
 end
 
 group :development, :test do
-  gem 'mongoid-compatibility'
-  gem 'rack', '~> 1.5'
-  gem 'rspec', '~> 3.0'
-  gem 'rake', '11.3.0'
-  gem 'rubocop', '0.29.1'
+  gem 'pry-byebug', platforms: :mri
+
   gem 'mongoid-danger', '~> 0.1.1'
+  gem 'rspec', '~> 3.9'
+  gem 'rubocop', '0.81.0'
+  gem 'rubocop-rspec', '1.38.1'
+  gem 'simplecov', require: false
 end

data/Guardfile

@@ -1,10 +1,19 @@
+# frozen_string_literal: true
+
 # More info at https://github.com/guard/guard#readme
 
-guard 'rspec' do
-  watch(%r{^spec/.+_spec\.rb$})
+guard :rspec, cmd: 'bundle exec rspec', all_on_start: true do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files) { rspec.spec_dir }
+
+  watch('Gemfile.lock') { rspec.spec_dir }
 
-  watch('Gemfile')              { 'spec' }
-  watch('Gemfile.lock')         { 'spec' }
-  watch(%r{^lib/(.+)\.rb$})     { 'spec' }
-  watch('spec/spec_helper.rb')  { 'spec' }
+  ruby = dsl.ruby
+  watch(ruby.lib_files) { rspec.spec_dir }
 end

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012-2017 Aidan Feldman & Contributors
+Copyright (c) 2012-2019 Aidan Feldman & Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,11 +1,22 @@
-# mongoid-locker
-[![Gem Version](https://badge.fury.io/rb/mongoid-locker.svg)](http://badge.fury.io/rb/mongoid-locker)
-[![Build Status](https://secure.travis-ci.org/mongoid/mongoid-locker.svg?branch=master)](http://travis-ci.org/mongoid/mongoid-locker)
-[![Code Climate](https://codeclimate.com/github/mongoid/mongoid-locker.svg)](https://codeclimate.com/github/mongoid/mongoid-locker)
+# Mongoid-Locker
 
-Document-level locking for MongoDB via Mongoid.  The need arose at [Jux](https://jux.com) from multiple processes on multiple servers trying to act upon the same document and stepping on each other's toes.  Mongoid-Locker is an easy way to ensure only one process can perform a certain operation on a document at a time.
+[![Gem Version](https://badge.fury.io/rb/mongoid-locker.svg)](https://badge.fury.io/rb/mongoid-locker)
+[![Build Status](https://travis-ci.org/mongoid/mongoid-locker.svg?branch=master)](https://travis-ci.org/mongoid/mongoid-locker)
+[![Maintainability](https://api.codeclimate.com/v1/badges/04ee4ee75ff54659300a/maintainability)](https://codeclimate.com/github/mongoid/mongoid-locker/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/04ee4ee75ff54659300a/test_coverage)](https://codeclimate.com/github/mongoid/mongoid-locker/test_coverage)
 
-[Tested](http://travis-ci.org/mongoid/mongoid-locker) against MRI 2.3.1 with Mongoid 2, 3, 4, 5 and 6. See [.travis.yml](.travis.yml) for the latest test matrix.
+Document-level optimistic locking for MongoDB via Mongoid. Mongoid-Locker is an easy way to ensure only one process can perform a certain operation on a document at a time.
+
+**NOTE:** Since version `2` Mongoid-Locker relies on MongoDB server time and not current client time, and does not perform any time calculation to get lock or release it. The basis of the current version are unique name of locking and time is set by MongoDB.
+
+**NOTE:** Please refer to [1-x-stable](https://github.com/mongoid/mongoid-locker/tree/1-x-stable) branch for `1.x.x` documentation. See the [UPGRADING](UPGRADING.md) guide and [CHANGELOG](CHANGELOG.md) for an overview of the changes.
+
+[Tested](https://travis-ci.org/mongoid/mongoid-locker) against:
+- MRI: `2.3.8`, `2.4.7`, `2.5.7`, `2.6.6`, `2.7.1`
+- JRuby `9.1.17.0`, `9.2.11.1`
+- Mongoid: `5`, `6`, `7`
+
+See [.travis.yml](.travis.yml) for the latest test matrix.
 
 ## Usage
 
@@ -15,46 +26,140 @@ Add to your `Gemfile`:
 gem 'mongoid-locker'
 ```
 
-and run `bundle install`.  In the model you wish to lock, include `Mongoid::Locker` after `Mongoid::Document`.  For example:
+and run `bundle install`. In the model you wish to lock, include `Mongoid::Locker` after `Mongoid::Document`. For example:
 
 ```ruby
-class QueueItem
+class User
   include Mongoid::Document
   include Mongoid::Locker
 
-  field :completed_at, :type => Time
+  field :locking_name, type: String
+  field :locked_at, type: Time
+
+  field :age, type: Integer
+
+  index({ _id: 1, locking_name: 1 }, name: 'mongoid_locker_index', sparse: true, unique: true, expire_after_seconds: lock_timeout)
 end
 ```
 
 Then, execute any code you like in a block like so:
 
 ```ruby
-queue_item.with_lock do
+user.with_lock do
+  user.age = 17
+  user.save!
+end
+```
+
+The `#with_lock` function takes an optional handful of options, so make sure to take a look.
 
-  # do stuff
+Note that these locks are only enforced when using `#with_lock`, not at the database level. It's useful for transactional operations, where you can make atomic modification of the document with checks. For example, you could deduct a purchase from a user's balance ... _unless_ they are broke.
 
-  queue_item.completed_at = Time.now
-  queue_item.save!
+More in-depth method documentation can be found at [RubyDoc.info](https://www.rubydoc.info/gems/mongoid-locker).
+
+### Customizable :locking_name and :locked_at field names
+By default, Locker uses fields with `:locking_name` and `:locked_at` names which should be defined in a model.
+```ruby
+class User
+  include Mongoid::Document
+  include Mongoid::Locker
+
+  field :locking_name, type: String
+  field :locked_at, type: Time
 end
 ```
 
-`#with_lock` takes an optional [handful of options around retrying](http://rdoc.info/github/mongoid/mongoid-locker/Mongoid/Locker:with_lock), so make sure to take a look.
+Use `Mongoid::Locker.configure` to setup parameters which used by Locker for all models where it's included.
+```ruby
+Mongoid::Locker.configure do |config|
+  config.locking_name_field = :global_locking_name
+  config.locked_at_field    = :global_locked_at
+end
 
-The default timeout can also be set on a per-class basis:
+class User
+  include Mongoid::Document
+  include Mongoid::Locker
 
+  field :global_locking_name, type: String
+  field :global_locked_at, type: Time
+end
+```
+
+The `locker` method in your model accepts options to setup parameters for the model.
 ```ruby
-class QueueItem
-  # ...
-  timeout_lock_after 10
+class User
+  include Mongoid::Document
+  include Mongoid::Locker
+
+  field :locker_locking_name, type: String
+  field :locker_locked_at, type: Time
+
+  locker locked_at_field: :locker_locking_name,
+         locked_at_field: :locker_locked_at
+end
+```
+
+### Available parameters for Mongoid::Locker, a class where it's included
+| parameter | default | options | description |
+|---|---|---|---|
+| locking_name_field | `:locking_name` | any field name | field where name of locking is storing, must be of type `String` |
+| locked_at_field | `:locked_at` | any field name | field where it is storing the time of beginning a lock of a document, must be of type `Time` |
+| lock_timeout | `5` | | within this time (in seconds) a document is considered as locked |
+| locker_write_concern | `{ w: 1 }` | see [MongoDB Write Concern](https://docs.mongodb.com/manual/reference/write-concern/#write-concern-specification)| a write concern only used for lock and unlock operations |
+| maximum_backoff | `60.0` | | the highest timeout (in seconds) between retires to lock a document, reaching that value `#with_lock` method raises `Mongoid::Locker::Errors::DocumentCouldNotGetLock` |
+| backoff_algorithm | `:exponential_backoff` | `:locked_at_backoff` or [custom algorithm](#custom-backoff_algorithm-and-locking_name_generator) | algorithm used for timeout calculating between retries to lock a document|
+| locking_name_generator | `:secure_locking_name` | [custom generator](#custom-backoff_algorithm-and-locking_name_generator) | generator used to generate unique name of a lock |
+
+For instances of a class where `Mongoid::Locker` is included, all parameters of a class are available for reading.
+```ruby
+  document.lock_timeout
+  #=> 5
+```
+
+### Custom :backoff_algorithm and :locking_name_generator
+A method which is defined in `Mongoid::Locker` are available in a class where it is included.
+
+Method `#with_lock` passes to the methods a document to which apply `#with_lock` and a hash of options. The hash may look like this:
+```ruby
+  { retries: Infinity, reload: true, attempt: 0, locking_name: "71c1ccd4-72d9-4a83-bbed-adf65803bd5d" }
+```
+
+A custom backoff algorithmoff **must return** a value more or equal `maximum_backoff` value to force `#with_lock` quit trying to lock a document, otherwise `#with_lock` will be trying to lock a document `INFINITY` times.
+```ruby
+Mongoid::Locker.configure do |config|
+  config.backoff_algorithm = :custom_backoff
+end
+
+module Mongoid
+  module Locker
+    def self.custom_backoff(doc, _opts)
+      rand > 0.5 ? 5 : doc.maximum_backoff
+    end
+  end
 end
 ```
 
-Note that these locks are only enforced when using `#with_lock`, not at the database level.  It is useful for transactional operations, where you can make atomic modification of the document with checks.  For exmple, you could deduct a purchase from a user's balance... _unless_ they are broke.
+A custom locking name generator **must return** a string to secure uniqueness name of locking.
+```ruby
+class User
+  include Mongoid::Document
+  include Mongoid::Locker
+
+  locker locking_name_generator: :custom_locking_name
+
+  field :locker_locking_name, type: String
+  field :locker_locked_at, type: Time
+
+  def self.custom_locking_name(_doc, _opts)
+    SecureRandom.uuid
+  end
+```
 
-More in-depth method documentation can be found at [rdoc.info](http://rdoc.info/github/mongoid/mongoid-locker/frames).  Enjoy!
+## Testing with RSpec
+Please see examples in [test_examples_spec.rb](spec/test_examples_spec.rb) file.
 
 ## Copyright & License
 
-Copyright (c) 2012-2017 Aidan Feldman & Contributors
+Copyright (c) 2012-2020 Aidan Feldman & Contributors
 
 MIT License, see [LICENSE](LICENSE.txt) for more information.