You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Implements mutex lock using redis as described in [redis docs](https://redis.io/commands/set#patterns). The term **simple** is opposed to the more complex **Redlock**, that was also proposed by Redis in their [docs](https://redis.io/topics/distlock) for use in case of distributed redis instances.
30
+
Implements distributed mutex lock using redis as described in [redis docs](https://redis.io/commands/set#patterns). The term **simple** is opposed to the more complex **Redlock**, that was also proposed by Redis in their [docs](https://redis.io/topics/distlock) for use in case of distributed redis instances.
31
31
32
-
This implementation of redis lock introduces some fine tuning features to the lock such as lock expire time, and acquire retry time, and acquire timeout (all described below).
33
-
34
-
Also acquiring the lock in a **FIFO** manner is supported by just providing a boolean option `fifo: true`, this will make the lock behave like a mutex queue and allow only one instance to acquire the lock at a time, and once the lock is released the first one to wait for it is the first one to acquire it and so on.
32
+
Locks have timeout (expire time) and fail after options. Also, Redis Pub/Sub is used so that released lock can be immediately acquired by another waiting process instead of depending on polling. Manual polling is still supported though in case lock expires.
To acquire the lock you just call the `lock` function exported from the package, and pass to it [ioredis](https://github.com/luin/ioredis) client, and the resource name for the lock. You can also pass any optional options to fine-tune the lock as needed (see API below).
84
+
There are 2 methods to acquire a lock:
85
+
-`lock`: which attempts to acquire the lock in a blocking way, if lock is already acquired, it blocks until lock is available.
86
+
-`tryLock`: which attempts to acquire the lock, if lock is already acquired it returns immediately.
68
87
69
88
## API
70
89
71
-
The package exports one named function `lock`, that acquires the lock and returns another function that releases the lock. The API for the `lock` function is as follows ...
-**lockName**\<String>: This is the name of the lock, and this is what distinguishes one lock from another, so that the part that needs mutual exclusion would always require a lock with the same name to be acquired by any process that attempts to enter that part. The key in redis database will be derived from this name.
83
-
-**retryTimeMillis**\<Number>: (default `100`) This defines how much should a process wait before trying to acquire the same lock again, provided time is milliseconds, this time cannot be null.
84
-
-**timeoutMillis**\<Number>: (default `null`) This defines the expiry time of the lock after it's acquired, so after that expiry time another process can acquire the lock even if the current holder did not release it, time provided is in milliseconds, `null` timeout value means that the lock will never expire.
85
-
-**failAfterMillis**\<Number>: (default `null`) This defines the maximum time a process should wait for the lock until it can acquire it, when this time has passes and the process has not acquired the lock yet, the function will throw an Error saying that the lock could not be acquired in the given time, the provided time is in milliseconds, `null` value means that the function will not fail until it has acquired the lock.
86
-
-**fifo**\<Boolean>: (default `false`) If this is set the waiting instances will be acquire the lock in a FIFO manner, i.e. the first one to wait will be the first one to acquire the lock once it's released and so on.
87
-
- Return type \<`Promise<Function>`>: The `unlock` function, that is an async function, and should be called to release the lock.
128
+
### `tryLock`
129
+
Asperthecode:
130
+
```typescript
131
+
/**
132
+
* Try to acquire the lock, if failed will return immediately.
133
+
* Returns whether or not the lock was acquired, and a release function.
134
+
*
135
+
* If the lock was acquired, release function is idempotent,
136
+
* calling it after the first time has no effect.
137
+
*
138
+
* If lock was not acquired, release function is a no-op.
139
+
*
140
+
* @param redis redis client
141
+
* @param lockName lock name
142
+
* @param options lock options
143
+
* @param options.timeout lock timeout in milliseconds, default: 30 seconds
144
+
* @returns whether or not the lock was acquired and release function.
- This package has **Peer Dependency** on [ioredis](https://github.com/luin/ioredis).
92
-
- It's taken into account the case that process A acquires the lock, then it expires, then process B acquires the lock. When process A try to release the lock, it will not be released, as it's now acquired by B.
93
-
- The same lock can be acquired with different options each time, so one time it can have an expiry time, and the next acquire it can lock indefinitely, the same with all the other options, although this behavior is not encouraged as it can be hard to debug.
155
+
### RedisClient
156
+
Thispackagehas**PeerDependency**on [redis](https://www.npmjs.com/package/redis), the is the redis client that must be passed to lock functions.
Once`release`function has been called all following calls are no-op, so same function cannot release the lock again from a different holder.
179
+
180
+
It's also taken into consideration that an expired lock cannot be released so it does not release the lock from another holder. i.e. if process A acquires the lock, then it expires, then process B acquires the lock. When process A tries to release the lock, it will not be released, as it's now acquired by B.
181
+
182
+
### Migration from v1.x
183
+
Breaking Changes in v2:
184
+
- Redis client is now `redis` and not `ioredis`
185
+
- options have been renamed:
186
+
- `timeoutMillis` -> `timeout`
187
+
- `retryTimeMillis` -> `pollingInterval` -- and it is now only used for expired locks, other wise pub/sub is used with released locks
188
+
- `failAfterMillis` -> `failAfter`
189
+
- FIFO option has been removed: existing implementation was wrong, it failed on lock-holder crash or failing to acquire the lock, and I could not come up with an implementation that would retain the functionality using redis only -- I sincerely apologize to anyone who have used it.
190
+
- `timeout` and `pollingInterval` have defaults. Locks are now allowed to lock indefinitely (exceptwithworkaroundmentionedin"Lock Options"sectionabove).
191
+
192
+
## Contribution
97
193
You are welcome to [open a ticket](https://github.com/AmrSaber/simple-redis-mutex/issues) anytime, if you find a bug or have a feature request.
0 commit comments