diff --git a/README.md b/README.md index 705772f..a3dbc84 100644 --- a/README.md +++ b/README.md @@ -10,36 +10,52 @@ RedLock.net is available using NuGet - search for [RedLock.net](https://www.nuge ## Usage -Construct a `RedisLockFactory`, passing in a set of Redis endpoints. Each endpoint passed to the constructor should be independent (i.e. not replicated masters/slaves). See below for more information on using RedLock.net with replicated instances. +Construct a `RedLockFactory`, passing in a set of Redis endpoints. Each endpoint passed to the constructor should be independent (i.e. not replicated masters/slaves). See below for more information on using RedLock.net with replicated instances. -You should keep hold of the `RedisLockFactory` and reuse it in your application. Each instance maintains its own connections with the configured Redis instances. Remember to dispose it when your app shuts down. +You should keep hold of the `RedLockFactory` and reuse it in your application. Each instance maintains its own connections with the configured Redis instances. Remember to dispose it when your app shuts down. -With the factory, create a `RedisLock` in a using block, making sure to check that that the lock `IsAcquired` inside the block before performing any actions. A lock is acquired if `RedisLock` can set a lock key in more than half of the redis instances. +With the factory, create a `RedLock` in a using block, making sure to check that that the lock `IsAcquired` inside the block before performing any actions. A lock is acquired if `RedLock` can set a lock key in more than half of the redis instances. -Internally `RedisLock` has a timer that automatically tries to keep the redis lock key alive. In the worst case of a process crashing without releasing the lock, it will automatically be expired by redis after the specified expiry time. +Internally `RedLock` has a timer that automatically tries to keep the redis lock key alive. In the worst case of a process crashing without releasing the lock, it will automatically be expired by redis after the specified expiry time. -#### On app init: +### On app init: +#### To have RedLock maintain its own redis connections: ```csharp -var endPoints = new[] +var endPoints = new List { new DnsEndPoint("redis1", 6379), new DnsEndPoint("redis2", 6379), new DnsEndPoint("redis3", 6379) }; -var redisLockFactory = new RedisLockFactory(endPoints); +var redlockFactory = RedLockFactory.Create(endPoints); ``` -If you require more detailed configuration for the redis instances you are connecting to (e.g. password, SSL, connection timeout), you can use the `RedisLockEndPoint` class. +#### To have RedLock use existing redis connections: +```csharp +var existingConnectionMultiplexer1 = ConnectionMultiplexer.Connect("redis1:6379"); +var existingConnectionMultiplexer2 = ConnectionMultiplexer.Connect("redis2:6379"); +var existingConnectionMultiplexer3 = ConnectionMultiplexer.Connect("redis3:6379"); + +var multiplexers = new List +{ + existingConnectionMultiplexer1, + existingConnectionMultiplexer2, + existingConnectionMultiplexer3 +}; +var redlockFactory = RedLockFactory.Create(multiplexers); +``` + +If you require more detailed configuration for the redis instances you are connecting to (e.g. password, SSL, connection timeout, redis database, key format), you can use the `RedLockEndPoint` or `RedLockMultiplexer` classes. -#### When you want to lock on a resource (giving up immediately if the lock is not available): +### When you want to lock on a resource (giving up immediately if the lock is not available): ```csharp var resource = "the-thing-we-are-locking-on"; var expiry = TimeSpan.FromSeconds(30); -using (var redisLock = await redisLockFactory.CreateAsync(resource, expiry)) // there are also non async Create() methods +using (var redLock = await redlockFactory.CreateLockAsync(resource, expiry)) // there are also non async Create() methods { // make sure we got the lock - if (redisLock.IsAcquired) + if (redLock.IsAcquired) { // do stuff } @@ -47,7 +63,7 @@ using (var redisLock = await redisLockFactory.CreateAsync(resource, expiry)) // // the lock is automatically released at the end of the using block ``` -#### When you want to lock on a resource (blocking and retrying every `retry` seconds until the lock is available, or `wait` seconds have passed): +### When you want to lock on a resource (blocking and retrying every `retry` seconds until the lock is available, or `wait` seconds have passed): ```csharp var resource = "the-thing-we-are-locking-on"; var expiry = TimeSpan.FromSeconds(30); @@ -55,10 +71,10 @@ var wait = TimeSpan.FromSeconds(10); var retry = TimeSpan.FromSeconds(1); // blocks until acquired or 'wait' timeout -using (var redisLock = await redisLockFactory.CreateAsync(resource, expiry, wait, retry)) // there are also non async Create() methods +using (var redLock = await redlockFactory.CreateLockAsync(resource, expiry, wait, retry)) // there are also non async Create() methods { // make sure we got the lock - if (redisLock.IsAcquired) + if (redLock.IsAcquired) { // do stuff } @@ -66,17 +82,17 @@ using (var redisLock = await redisLockFactory.CreateAsync(resource, expiry, wait // the lock is automatically released at the end of the using block ``` -You can also pass a `CancellationToken` to the blocking `Create` methods if you want to be able to cancel the blocking wait. +You can also pass a `CancellationToken` to the blocking `CreateLock` methods if you want to be able to cancel the blocking wait. -#### On app shutdown: +### On app shutdown: ```csharp -redisLockFactory.Dispose(); +redlockFactory.Dispose(); ``` -#### Azure Redis Cache: +### Azure Redis Cache: If you are connecting to Azure Redis Cache, use the following configuration settings: ```csharp -var azureEndPoint = new RedisLockEndPoint +var azureEndPoint = new RedLockEndPoint { EndPoint = new DnsEndPoint("YOUR_CACHE.redis.cache.windows.net", 6380), Password = "YOUR_ACCESS_KEY", @@ -84,17 +100,17 @@ var azureEndPoint = new RedisLockEndPoint }; ``` -#### Usage with replicated instances: +### Usage with replicated instances: The Redlock algorithm is designed to be used with multiple independent Redis instances (see http://redis.io/topics/distlock#why-failover-based-implementations-are-not-enough for more detail on why this is the case). -However, since RedLock.net 1.7.3 there is support for replicated master/slave instances. To do so, configure RedLock using the `RedisLockEndPoint` class, providing the replicated redis instances with the `EndPoints` property. -Each `RedisLockEndPoint` that is passed to the `RedisLockFactory` constructor will be treated as a single unit as far as the RedLock algorithm is concerned. +However, since RedLock.net 1.7.3 there is support for replicated master/slave instances. To do so, configure RedLock using the `RedLockEndPoint` class, providing the replicated redis instances with the `EndPoints` property. +Each `RedLockEndPoint` that is passed to the `RedLockFactory` constructor will be treated as a single unit as far as the RedLock algorithm is concerned. -If you have multiple independent sets of replicated Redis instances, you can use those with RedLock.net in the same way you would use multiple non-replicated independent Redis instances. +If you have multiple independent sets of replicated Redis instances, you can use those with RedLock.net in the same way you would use multiple non-replicated independent Redis instances: ```csharp -var redisLockEndPoints = new[] +var redlockEndPoints = new List { - new RedisLockEndPoint + new RedLockEndPoint { EndPoints = { @@ -103,7 +119,7 @@ var redisLockEndPoints = new[] new DnsEndPoint("replicatedset1-server3", 6379) } }, - new RedisLockEndPoint + new RedLockEndPoint { EndPoints = { @@ -112,16 +128,30 @@ var redisLockEndPoints = new[] new DnsEndPoint("replicatedset2-server3", 6379) } }, - new RedisLockEndPoint + new RedLockEndPoint { EndPoint = new DnsEndPoint("independent-server", 6379) } }; -var redisLockFactory = new RedisLockFactory(endPoints); +var redlockFactory = RedLockFactory.Create(redlockEndPoints); +``` +or, if you have existing redis connections: +```csharp +var existingConnectionMultiplexer1 = ConnectionMultiplexer.Connect("replicatedset1-server1:6379,replicatedset1-server2:6379,replicatedset1-server3:6379"); +var existingConnectionMultiplexer2 = ConnectionMultiplexer.Connect("replicatedset2-server1:6379,replicatedset2-server2:6379,replicatedset2-server3:6379"); +var existingConnectionMultiplexer3 = ConnectionMultiplexer.Connect("independent-server:6379"); + +var multiplexers = new List +{ + existingConnectionMultiplexer1, + existingConnectionMultiplexer2, + existingConnectionMultiplexer3 +}; +var redlockFactory = RedLockFactory.Create(multiplexers); ``` -##### Considerations when using replicated instances +#### Considerations when using replicated instances Using replicated instances is not the suggested way to use RedLock, however if your environment is configured that way and you are aware of the potential risks it is possible to configure. Since all operations that RedLock.net performs in Redis (Lock, Extend and Unlock) require writing, they can only be performed on the master. If your replicated Redis instances are not configured to automatically promote one of the slaves to master in the case of the master becoming inaccessible, the replicated instances will be unable to be used by RedLock until there is manual intervention to reinstate a master.