DotNetVault 0.2.1.22-beta

DotNetVault is a library and static code analysis tool that makes managing shared mutable state in multi-threaded applications more manageable and less error prone.  It also provides a common abstraction over several commonly used synchronization mechanisms, allowing you to change from one underlying type to another (such as from lock free synchronization to mutex/monitor lock based) without needing to refactor your code. Where errors do still occur, they are easier to locate and identify.

     It provides an abstraction over several different underlying synchronization mechanisms: lock-free synchronization using atomics, Monitor.Enter (i.e. C# lock(syncObj) {}) and ReaderWriterLockSlim. Because the common functionality shared by vaults providing these varied underlying mechanism is exposed by a common (compile-time) API, it is easier than ever to experiment with changing the underlying mechanism without need for much code refactoring.  Simply change the type of vault you instantiate to one that uses the synchronization mechanism you desire.

     A full project description is included in "DotNetVault Description.pdf".  Source code, example projects, unit tests, stress test and quick start guide on GitHub.

This is a prerelease version of DotNetVault.
Install-Package DotNetVault -Version 0.2.1.22-beta
dotnet add package DotNetVault --version 0.2.1.22-beta
<PackageReference Include="DotNetVault" Version="0.2.1.22-beta" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add DotNetVault --version 0.2.1.22-beta
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

DotNetVault

Synchronization Library and Static Analysis Tool for C# 8

DotNetVault takes its inspiration from the synchronization mechanisms provided
by Rust language and the Facebook Folly C++ synchronization library. These
synchronization mechanisms observe that the mutex should own the data they
protect. You literally cannot access the protected data without first obtaining
the lock. RAII destroys the lock when it goes out of scope – even if an
exception is thrown or early return taken.

Advantages:

Deadlock avoidance: by default, all locks are timed. If the resource has
already been obtained or you have accidentally changed the acquisition order of
various locks somewhere in the code, you get a TimeoutException, allowing you
to identify your mistake. In addition to being able to base termination of an
acquisition attempt on timeout, you can also use a cancellation token to
propagate the cancellation request.

RAII (Scope-based) Lock Acquisition and Release: Locks are stack-only
objects (ref structs) and the integrated Roslyn analyzer forces you to declare
the lock inline in a using statement or declaration, or it will cause a
compilation error. There is no danger of accidentally holding the lock open
longer than its scope even in the presence of an exception or early return.

Incredible Flexibility to Change Underlying Synchronization Mechanism:
Vaults are provided that use varied underyling mechanisms (Monitor Locks,
Atomic Exchanges, and ReaderWriterLockSlim).These vaults provide a common
compile time API for their common functionality. Thus, you can easily change
from a synchronization mechanism using Monitor.Enter (which is used by C#'s
lock statement) to a mechanism based on lock free atomics or even
ReaderWriterLock. This flexibility will allow you to profile code and
make changes without needing to extensively refactor your code.

Isolation of Protected Resources: The need for programmer discipline is
reduced:
1. programmers do not need to remember which mutexes protect which resources,
2. programmers cannot access the protected resource before they obtain the
lock and cannot access any mutable state from the protected resource after
releasing the lock, and
3. static analysis rules enforced by compilation errors emitted from the
integrated Roslyn analyzer prevent references to mutable state from outside the
protected resource from becoming part of the protected resource and prevent the
leaking of references to mutable state inside the protected resource to the
outside.

The ubiquity of shared mutable state in Garbage Collected languages like C# can
work at cross purposes to thread-safety. One approach to thread-safety in such
languages is to elimate the use of mutable state. Because this is not always
possible or even desireable, the synchronization mechanisms employed in C#
typically rely on programmer knowledge and discipline. DotNetVault uses
Disposable Ref Structs together with custom language rules enforced by an
integrated Roslyn analyzer to prevent unsynchronized sharing of protected
resources. Locks cannot be held longer than their scope and, by default, will
timeout. This enables deadlock-avoidance.

Try DotNetVault. There is a learning curve because it is restrictive about
sharing protected resources. There are plenty of documents and example projects
provided with the source code of this project that can ease you into that
learning curve and demonstrate DotNetVault's suitability for use in highly
complex concurrent code. Armed with the resources that DotNetVault provides, you
will be able to approach concurrent programming, including use of shared mutable
state, with a high degree of confidence.

See DotNetVault Description.pdf for full description of this project.

RELEASE NOTES VERSION 0.2.1.22-beta

 This is a beta release.  Current stable release is 0.1.5.4.
 
 This release adds a ReadWriteStringBuffer vault that provides thread-safe readonly, upgradable readonly and writable access to a StringBuilder object.  It also (when binaries or source retrieved from GitHub) includes the "Clorton Game" which demonstrates usage of the readwrite vault and provides a stress test to validate its functionality.

 "DotNetVault.Description.pdf" updated to reflect changes.

RELEASE NOTES VERSION 0.2.1.9-alpha

This release contains MAJOR feature updates but is still considered unstable alpha.

Major new feature: vaults with varying underlying synchronization mechanisms.  You may now chose lock=free atomics (only mechanism before), the .NET standard Monitor.Enter (used by C# lock statement) or ReaderWriterLockSlim.  Because these vaults have a compatible (at compile-time) API, you can easily switch between synchronization mechanisms without any extensive refactoring required.  Also, the new vault based on ReaderWriterLock slim allows for shared readonly locks, upgradable readonly locks and exclusive read-write locks.  If you are coming from an old version of this project, you may need to refactor in some places as their are a significant number of small breaking changes.  It should, however, be a quick and painless process.

Fixed Bug 76.  Illegal references to non-vault-safe types inside mutable vault's locked resource objects delegates where not being detected in the case of local functions or using anonymous function syntax. 

More unit tests.  There are now two unit test projects included.  The older one (DotNetVault.Test) tests the functionality of the built-in static analyzer.  The newer unit test project (VaultUnitTests) tests the functionality and synchronization mechanisms provided for the vaults.  It may also serve, in addition to the pre-existing sample code projects, as an introduction to this library.

Documentation (including "DotNetVault Description.pdf") updated to reflect changes.

RELEASE NOTES VERSION 0.2.0.2-alpha

This is an unstable alpha release.  The current stable release is 0.1.5.2.  

The "Value" property of the BasicVault's locked resource object is now returned by reference.  This enables more efficient use of large mutable structs as protected resource objects.  An additional analysis rule was added to prevent ref local aliasing of the property, to prevent possible unsynchronized access.  Documentation updated to reflect.

DotNetVault

Synchronization Library and Static Analysis Tool for C# 8

DotNetVault takes its inspiration from the synchronization mechanisms provided
by Rust language and the Facebook Folly C++ synchronization library. These
synchronization mechanisms observe that the mutex should own the data they
protect. You literally cannot access the protected data without first obtaining
the lock. RAII destroys the lock when it goes out of scope – even if an
exception is thrown or early return taken.

Advantages:

Deadlock avoidance: by default, all locks are timed. If the resource has
already been obtained or you have accidentally changed the acquisition order of
various locks somewhere in the code, you get a TimeoutException, allowing you
to identify your mistake. In addition to being able to base termination of an
acquisition attempt on timeout, you can also use a cancellation token to
propagate the cancellation request.

RAII (Scope-based) Lock Acquisition and Release: Locks are stack-only
objects (ref structs) and the integrated Roslyn analyzer forces you to declare
the lock inline in a using statement or declaration, or it will cause a
compilation error. There is no danger of accidentally holding the lock open
longer than its scope even in the presence of an exception or early return.

Incredible Flexibility to Change Underlying Synchronization Mechanism:
Vaults are provided that use varied underyling mechanisms (Monitor Locks,
Atomic Exchanges, and ReaderWriterLockSlim).These vaults provide a common
compile time API for their common functionality. Thus, you can easily change
from a synchronization mechanism using Monitor.Enter (which is used by C#'s
lock statement) to a mechanism based on lock free atomics or even
ReaderWriterLock. This flexibility will allow you to profile code and
make changes without needing to extensively refactor your code.

Isolation of Protected Resources: The need for programmer discipline is
reduced:
1. programmers do not need to remember which mutexes protect which resources,
2. programmers cannot access the protected resource before they obtain the
lock and cannot access any mutable state from the protected resource after
releasing the lock, and
3. static analysis rules enforced by compilation errors emitted from the
integrated Roslyn analyzer prevent references to mutable state from outside the
protected resource from becoming part of the protected resource and prevent the
leaking of references to mutable state inside the protected resource to the
outside.

The ubiquity of shared mutable state in Garbage Collected languages like C# can
work at cross purposes to thread-safety. One approach to thread-safety in such
languages is to elimate the use of mutable state. Because this is not always
possible or even desireable, the synchronization mechanisms employed in C#
typically rely on programmer knowledge and discipline. DotNetVault uses
Disposable Ref Structs together with custom language rules enforced by an
integrated Roslyn analyzer to prevent unsynchronized sharing of protected
resources. Locks cannot be held longer than their scope and, by default, will
timeout. This enables deadlock-avoidance.

Try DotNetVault. There is a learning curve because it is restrictive about
sharing protected resources. There are plenty of documents and example projects
provided with the source code of this project that can ease you into that
learning curve and demonstrate DotNetVault's suitability for use in highly
complex concurrent code. Armed with the resources that DotNetVault provides, you
will be able to approach concurrent programming, including use of shared mutable
state, with a high degree of confidence.

See DotNetVault Description.pdf for full description of this project.

RELEASE NOTES VERSION 0.2.1.22-beta

 This is a beta release.  Current stable release is 0.1.5.4.
 
 This release adds a ReadWriteStringBuffer vault that provides thread-safe readonly, upgradable readonly and writable access to a StringBuilder object.  It also (when binaries or source retrieved from GitHub) includes the "Clorton Game" which demonstrates usage of the readwrite vault and provides a stress test to validate its functionality.

 "DotNetVault.Description.pdf" updated to reflect changes.

RELEASE NOTES VERSION 0.2.1.9-alpha

This release contains MAJOR feature updates but is still considered unstable alpha.

Major new feature: vaults with varying underlying synchronization mechanisms.  You may now chose lock=free atomics (only mechanism before), the .NET standard Monitor.Enter (used by C# lock statement) or ReaderWriterLockSlim.  Because these vaults have a compatible (at compile-time) API, you can easily switch between synchronization mechanisms without any extensive refactoring required.  Also, the new vault based on ReaderWriterLock slim allows for shared readonly locks, upgradable readonly locks and exclusive read-write locks.  If you are coming from an old version of this project, you may need to refactor in some places as their are a significant number of small breaking changes.  It should, however, be a quick and painless process.

Fixed Bug 76.  Illegal references to non-vault-safe types inside mutable vault's locked resource objects delegates where not being detected in the case of local functions or using anonymous function syntax. 

More unit tests.  There are now two unit test projects included.  The older one (DotNetVault.Test) tests the functionality of the built-in static analyzer.  The newer unit test project (VaultUnitTests) tests the functionality and synchronization mechanisms provided for the vaults.  It may also serve, in addition to the pre-existing sample code projects, as an introduction to this library.

Documentation (including "DotNetVault Description.pdf") updated to reflect changes.

RELEASE NOTES VERSION 0.2.0.2-alpha

This is an unstable alpha release.  The current stable release is 0.1.5.2.  

The "Value" property of the BasicVault's locked resource object is now returned by reference.  This enables more efficient use of large mutable structs as protected resource objects.  An additional analysis rule was added to prevent ref local aliasing of the property, to prevent possible unsynchronized access.  Documentation updated to reflect.

Release Notes

RELEASE NOTES VERSION 0.2.1.22-beta

    This release adds a ReadWriteStringBuffer vault that provides thread-safe readonly, upgradable readonly and writable access to a StringBuilder object.  It also (when binaries or source retrieved from GitHub) includes the "Clorton Game" which demonstrates usage of the readwrite vault and provides a stress test to validate its functionality.

"DotNetVault.Description.pdf" updated to reflect changes.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
0.2.1.22-beta 100 4/7/2020
0.2.1.9-alpha 187 3/15/2020
0.2.0.2-alpha 87 2/13/2020
0.1.5.4 151 2/17/2020
0.1.5.2 108 2/8/2020
0.1.5 114 2/2/2020
0.1.4.2-beta 227 2/1/2020
0.1.4.1-beta 176 1/26/2020
0.1.4-beta 154 1/21/2020
0.1.3.13-beta 165 1/11/2020
0.1.3.11-beta 201 1/8/2020
0.1.3.8-beta 311 1/4/2020
0.1.3.5-beta 220 1/1/2020