Documentation Improvement

[adampal]

Hi,
Firstly, thanks for the great gem. I have been having some issues with keys getting stuck and I've been trying to find a good solution. In the process, I have been experimenting with the lock_timeout and lock_ttl settings but I think I've misinterpreted the documentation.

It would be great if the documentation included a description of what will actually happen with different settings and examples of when you might use them.

I am still not sure I am 100% correct on how these settings work. I have written out some suggestions for the documentation below based on my current understanding that may be useful as a starting point. However, if I'm off the mark in my understanding, please let me know as I think that is part of what is causing me issues with a current app I'm working on.

The setting I am actually trying to configure (and maybe it doesn't actually exist in the gem) is this:
I would like to be able to set a timeout on a lock where the lock will never exist for more than 1 minute. I have some jobs that I know should only ever take seconds to run so, if the lock still exists in 1 minute after the job started, I know the lock is stuck and should be ignored. Is there any way to do something like this with the current configuration options?

Here are my suggestions for documentation updates. I don't have as complete an understanding of the use cases for this gem as you do so I'm sure you would have better and more accurate examples to include.

lock_ttl
Lock TTL decides how long to wait after the job has been successfully processed before making it possible to reuse that lock.
Scenario:
lock_ttl: 10.minutes.to_i
In this situation, after the job is complete, the same job can not be re-processed in the next 10 minutes.
You may want to use this when you know a job should not be processed any more regularly than a certain interval.

lock_timeout
Lock timeout decides how long to wait for acquiring the lock. A value of nil means to wait indefinitely for a lock resource to become available.
Scenario:
lock_timeout: 1.minute.to_i
In this situation, if a job is currently processing when the new job is triggered, we wait up to 1 minute before declaring this job as a duplicate.
You may want to use this when...(I don't actually know when you would want to do this?)

[mhenrixon]

TTL (Time To Live)

This is a Redis term! Since we are backed by a Redis database I figured it would be cool to spread some of that lingo. It means how long, after the lock is created should we let it live. Think of it as the time to expire if you want or simply put; expiration!

Timeout

How long to wait for getting the lock until we timeout the attempt and fail. This is not at all needed and leads to some confusion for some people but there are times when you'd prefer to let the server wait a few seconds to see if a lock can be achieved.

I'll think about rephrasing some parts of the README over the next couple of weeks.

[adampal]

Thanks, that makes sense re the difference between TTL and Timeout.

Could you explain how TTL relates to the time a job takes to complete?
If I set a TTL of 30 seconds but the job takes 10 minutes, does this mean that the lock has expired and a duplicate job could start running?

[mhenrixon]

The lock would expire after 30 seconds then and duplicates would be allowed. Since v7.0.1 there is automatic cleanup of orphaned locks so you shouldn't really have to worry about expiration since it will get cleaned up on a regular schedule.

Have a look for an initial configuration of v7.0.1 #571 that should be a good start.

[adampal]

Thanks, I'll take a look at v7 👍