Leasing patterns for mediating access to exclusive resources in distributed processes. A generic abstraction, with an Azure blob-based implementation.

It is built for netstandard2.0.

Corvus.Leasing provides a means to acquire, release and extend exclusive leases to mediate resource access in distributed processing.

Caution - you should be aware that using an exclusive leasing pattern, while essential for some activities, can introduce bottlenecks and deadlocks in your distributed processing (rather similar to the use of a mutex in multithreaded programming on a single instance), and you should be careful to understand the implications of introducing this into your system.

The ILeaseProvider interface supports a cycle from Acquire (for a duration), through an optional Extend (renewing a lease before it expires for another lease period) to Release (relinquish the lease).

Standard implementations of this are provided for Azure Blob storage, and an "in memory" version which is intended for testing, rather than production code..

Typically, you use the lease provider through one of the extension methods in LeaseProviderExtensions.

These give you a mutex model, with try-once or try-until-acquire-or-timeout semantics, and auto-renewal behaviour.

At its simplest, you can execute an action with guaranteed distributed mutex semantics.

leaseProvider.ExecuteWithMutexAsync(() => { /* my action */ }, "myuniqueleasename");

This will block until the lease is acquired, and then execute the action, holding the lease until it is done.

The operation has a default timeout. If the lease cannot be acquired in time, it will throw a LeaseAcquisitionUnsuccessfulException.

You can also use the "try once" semantics.

leaseProvider.ExecuteWithMutexTryOnceAsync(() => { /* my action */ }, "myuniqueleasename");

This will try to acquire the lease, and then execute the action, holding the lease until it is done. If it cannot acquire the lease, it will immediately throw a LeaseAcquisitionUnsuccessfulException without retrying.

If you do not want to see the LeaseAcquisitionUnsuccessfulException, you can suppress it and turn it into a boolean return value with an extension method.

leaseProvider.ExecuteWithMutexAsync(() => { /* my action */ }, "myuniqueleasename").DoNotThrowIfLeaseNotAcquired();

There are various overloads that allow you to control the duration of the lease, and the strategies and policy for retrying in the event of failure.

Most providers also have constraints on the lease name and lease duration - e.g. special characters, minimum duration. If you use an invalid parameter, it will raise an InvalidOperationException.

It is also possible that the leasing operation will fail during initialization. In that case you will see an InitializationFailureException

Corvus.Leasing is available under the Apache 2.0 open source license.

For any licensing questions, please email licensing@endjin.com

This project is sponsored by endjin, a UK based Microsoft Gold Partner for Cloud Platform, Data Platform, Data Analytics, DevOps, and a Power BI Partner.

For more information about our products and services, or for commercial support of this project, please contact us.

We produce two free weekly newsletters; Azure Weekly for all things about the Microsoft Azure Platform, and Power BI Weekly.

Keep up with everything that's going on at endjin via our blog, follow us on Twitter, or LinkedIn.

Our other Open Source projects can be found on GitHub

This project has adopted a code of conduct adapted from the Contributor Covenant to clarify expected behavior in our community. This code of conduct has been adopted by many other projects. For more information see the Code of Conduct FAQ or contact hello@endjin.com with any additional questions or comments.

The IMM is endjin's IP quality framework.