README.md in race_block-0.1.0 vs README.md in race_block-0.2.0
- old
+ new
@@ -1,12 +1,16 @@
# RaceBlock
+[](https://badge.fury.io/rb/race_block)
[](https://github.com/joeyparis/race_block/actions/workflows/main.yml)
+
+[](https://codeclimate.com/github/joeyparis/race_block/test_coverage)
+[](https://codeclimate.com/github/joeyparis/race_block/maintainability)
A Ruby code block wrapper to help prevent race conditions across multiple threads and even separate servers.
-**Disclaimer** This code has been used in production for several years now without incident, but I make no guarantee about the thread-safeness it has. Use at your own risk.
+>**Disclaimer** This code has been used in production for several years now without incident, but I make no guarantee about the thread-safeness it has. Use at your own risk.
## Concept
### Problem
Multiple servers all have the same cron jobs, but we only want one of them to actually execute the job.
@@ -27,20 +31,36 @@
$ bundle install
Or install it yourself as:
$ gem install race_block
+
+## Requirements:
+* Ruby >= 2.5
+* A Redis server
## Potential Use Cases
The original inspiration behind this gem was running cron jobs across multiple servers to send emails. Since all of the servers would trigger the cron job simultaneously, they would all attempt to send the same email at the same time leading to multiple copies of a single email being sent out. `RaceBlock` solved this problem by ensuring only one instance of `RaceBlock` across all the servers was allowed to work on a single email.
`RaceBlock` could also apply to any cron jobs or block of code that really should only be run once, regardless of which servers tried to initiate it.
## Usage
+Before calling `RaceBlock.start` you'll need to configure your own redis client in `RaceBlock.config`
+
+```ruby
+RaceBlock.config do |config|
+ config.redis = Redis.new
+end
+
+# or...
+
+RaceBlock.config.redis = Redis.new
+```
+
Any code that you want to be "thread-safe" and ensure is only executing in one location should be placed in a `RaceBlock` with a unique identifying key that will be checked across all instances.
```ruby
RaceBlock.start('unique_key', {}) do
# Insert code that should only be executed once at a time here...
@@ -51,12 +71,22 @@
|Option|Default|Description|
|------|-------|-----------|
|sleep_delay|0.5|How many seconds the RaceBlock should wait after generating its unique token before it checks if it can execute the RaceBlock. **Important** This value should be longer than the amount of time it takes your server to write to the Redis database. 0.5 seconds has worked for us, but longer `sleep_delay` values should technically be safer.|
|expire|60|How many seconds the key should be stored for while running. This number should be longer than the length of time the RaceBlock will take to execute once it starts. The key will be deleted 3 seconds after the block completes, regardless of the time left from `expire`.|
-|expire_immediately|false|Whether or not the key should expire immediately after block completion, or wait the default 3 seconds.|
-|debug|false|Can help debug why a RaceBlock call is running or not running.|
-|dsync_tokens|false| **TESTING ONLY** This is purely for testing purposes to simulate inconsistent request times. It should never be used in a production environment.|
+|expiration_delay|3|How long after block completion before the key is deleted. Setting to 0 will delete it instanttly upon block completion.|
+|desync_tokens|0| **TESTING ONLY** This is purely for testing purposes to simulate inconsistent request times. It should never be used in a production environment.|
+
+#### Changing default values
+You can change the default values using `RaceBlock.config`, otherwise they can be overridden on a per call basis.
+
+```ruby
+RaceBlock.config do |config|
+ config.sleep_delay = 1.5
+ config.expire = 14
+ config.expiration_delay = 4
+end
+```
## Development
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.