README.md in resque-rate_limited_queue-0.0.34 vs README.md in resque-rate_limited_queue-1.0.0

- old
+ new

@@ -1,9 +1,7 @@ # Resque Rate Limited Queue -PLEASE NOTE THIS IS NOW SUITABLE FOR TRIAL USE - I EXPECT TO RELEASE A STABLE VERSION IN EARLY JAN 2015 - A Resque plugin which makes handling jobs that use rate limited apis easier If you have a series of jobs in a queue, this gem will pause the queue when one of the jobs hits a rate limit, and re-start the queue when the rate limit has expired. There are two ways to use the gem. @@ -42,17 +40,17 @@ #### Un Pause Queues can be unpaused in two ways. The most elegant is using [resque-scheduler](https://github.com/resque/resque-scheduler), this works well as long as you aren't running on a platform like heroku which requires a dedicated worker to run the resque-scheduler. -To tell the gem to use resque-scheduler you need to include resque-scheduler in your Gemfile - and also let the gem know which queue to use to schedule the unpause job (make sure this isn't a queue that could get paused). Put this in an initializer. +To tell the gem to use `resque-scheduler` you need to include it in your Gemfile - and also let the gem know which queue to use to schedule the unpause job (make sure this isn't a queue that could get paused). Put this in an initializer. ```ruby Resque::Plugins::RateLimitedQueue::UnPause.queue = :my_queue ``` -Please see the section below on how to unpause on heroku as an alternative. If you don't install resque-scheduler AND configure the queue, then the gem will not schedule unpause jobs this way. +Please see the section below on how to unpause on heroku as an alternative. If you don't install `resque-scheduler` AND configure the queue, then the gem will not schedule unpause jobs this way. #### Workers Queues are paused by renaming them, so a resque queue called 'twitter\_api' will be renamed 'twitter\_api\_paused' when it hits a rate limit. Of course this will only work if your resque workers are not also taking jobs from the 'twitter\_api\_paused' queue. So your worker commands need to look like: Either @@ -113,11 +111,11 @@ WAIT_TIME = 60*60 def self.perform(*params) do_api_stuff rescue MyApiRateLimit - pause_for(Time.now + WAIT_TIME, name) + pause_until(Time.now + WAIT_TIME, name) rate_limited_requeue(self, *params) end def self.enqueue(*params) rate_limited_enqueue(self, *params) @@ -134,24 +132,82 @@ WAIT_TIME = 60*60 def self.perform(klass, *params) super rescue MyApiRateLimit - pause_for(Time.now + WAIT_TIME, name) + pause_until(Time.now + WAIT_TIME, name) rate_limited_requeue(self, klass, *params) end end ```` If you do this - please contribute - and I'll add to the gem. +## Development Documentation +All the functions are class methods + +```ruby +rate_limited_enqueue(klass, *params) +rate_limited_requeue(klass, *params) +```` +Queue the job specified to the resque queue specified by `@queue`. `rate_limited_requeue` is intended for use when you need the job to be pushed back to the queue; it just calls `rate_limited_queue`, but they are split to make testing with stubs easier. + +```ruby +pause +```` +Pauses the queue specified by `@queue`, if it is not already paused. +In most cases you should call `pause_until` to pause a queue when you hit a rate limit. + +```ruby +un_pause +```` +Un-pauses the queue specified by `@queue`, if it is paused. + +```ruby +pause_until(timestamp) +```` +Pauses the queue (specified by `@queue`) and then queues a job to unpause the queue specified by `@queue`, using resque-scheduler to the queue specified by `Resque::Plugins::RateLimitedQueue::UnPause.queue` at the timestamp specified. +If `resque-schedule` is not included, or `UnPause.queue` isn't specified this will just pause the queue. + +This is the prefered function to call when you hit a rate limit, since it with work regardless of the unpause method used by the application. + +```ruby +paused? +```` +This returns true or false to indicate wheher the queue is paused. Be aware that the queue state could change get after the call returns, but before your code executes. Use `with_lock` if you need to avoid this. + +```ruby +paused_queue_name +```` +Returns the name of the queue when it is paused. + +```ruby +with_lock(&block) +```` +Takes ownership of the PauseQueue semaphor before executing the block passed. Useful if you need to test the state of the queue and take some action without the state changing. + +```ruby +find_class(klass) +```` +Takes the parameter passed, and if it's a string class name, tries to turn it into a class. + + ## Contributing 1. Fork it ( https://github.com/[my-github-username]/resque_rate_limited_queue/fork ) 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create a new Pull Request + +## Version history + +0.0.x Mostly pre-release versions + +1.0.0 First release version. Breaking change - renamed `pause_for` to be `pause_until` to better reflect function + + + ## Final thoughts -Thanks to [Dominic](https://github.com/dominicsayers) for idea of renaming the redis key - and the sample code that does this. +Thanks to [Dominic](https://github.com/dominicsayers) for idea of renaming the redis key - and the sample code that does this. This is my first gem - so please forgive any errors - and feedback very welcome