From 9c57b3b6e7f8c475d53c05d73cf95747ed6ac8b9 Mon Sep 17 00:00:00 2001 From: Mark Cilia Vincenti Date: Tue, 1 Oct 2024 09:13:08 +0200 Subject: [PATCH] Improve documentation. --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d77f53a..5dac1cd 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,12 @@ void DoThat() If you want to avoid limiting what you are able to do, you need a solution such as this library. ## Usage -### If only targeting .NET 5.0 or later +There are two methods for using this library, one that is clean but not hardened against thread aborts (which were removed since .NET 5.0), and another one that requires more work and the use of a factory method. + +If you are only targeting .NET 5.0 or greater, then you are strongly recommended to use the [clean method](#net50-or-greater). +If you need to target frameworks prior to .NET 5.0 (and that would also include .NET Standard 2.0 and 2.1), then you need to use the [factory method](#prior-to-net50). + +### Clean method: (if only targeting .NET 5.0 or greater) Use this library the same way you would use [System.Threading.Lock](https://learn.microsoft.com/en-us/dotnet/api/system.threading.lock?view=net-9.0). In order to get the performance benefits of `System.Threading.Lock`, you must however [multi-target frameworks](https://learn.microsoft.com/en-us/nuget/create-packages/multiple-target-frameworks-project-file) in your `.csproj` file. @@ -68,7 +73,7 @@ There is also no need to reference this library as a dependency for .NET 9.0+. Y ``` -### If targeting frameworks prior to .NET 5.0 +### Factory method: (if targeting frameworks prior to .NET 5.0) Due to frameworks prior to .NET 5.0 supporting the notorious `Thread.Abort`, we cannot use the same `System.Threading.Lock` namespace or else the locks would not be hardened against thread aborts, so we need to use a creator method instead. You must also [multi-target](https://learn.microsoft.com/en-us/nuget/create-packages/multiple-target-frameworks-project-file) .NET 9.0 in your `.csproj` file as well.