Merging 'dev' branch for release 1.2.0

Author: kzdev-net

.github/workflows/docfx-publish.yml

@@ -28,7 +28,7 @@ jobs:
     - name: Dotnet Setup
       uses: actions/setup-dotnet@v4
       with:
-        dotnet-version: 8.x
+        dotnet-version: 9.x
 
     - run: dotnet tool update -g docfx
     - run: docfx Source/Docs/docfx.json

README.md

@@ -1,6 +1,6 @@
 # KZDev.PerfUtils
 
-This is the repository for the ['KZDev.PerfUtils'](https://www.nuget.org/packages/KZDev.PerfUtils) nuget package that contains the `MemoryStreamSlim` class; a high-performance, memory-efficient, and easy-to-use replacement for the `MemoryStream` class that provides particular benefits for large or frequently used streams.
+This is the repository for the ['KZDev.PerfUtils'](https://www.nuget.org/packages/KZDev.PerfUtils) nuget package that contains the `MemoryStreamSlim` class; a high-performance, memory-efficient, and easy-to-use replacement for the `MemoryStream` class that provides particular benefits for large or frequently used streams. As well as the `StringBuilderCache` which allows better performance when using `StringBuilder` instances, and the `InterlockedOps` class, which provides additional atomic thread-safe operations to extend the functionality of the `Interlocked` class in the .NET Class Library.
 
 ## Features
 
@@ -12,19 +12,38 @@ This is the repository for the ['KZDev.PerfUtils'](https://www.nuget.org/package
 * Simple replacement for `MemoryStream` with the same API, other than the constructor.
 * Optionally allows using native memory for storage, which allows even more flexibility to minimize GC pressure.
 
-## Future Features
+`StringBuilderCache` is a static class that provides a thread-safe cache of `StringBuilder` instances to reduce the number of allocations and deallocations of `StringBuilder` objects in high-throughput scenarios with simple operations:
+
+* Acquire : Get a `StringBuilder` instance from the cache.
+* Release : Return a `StringBuilder` instance to the cache.
+* GetStringAndRelease : Get the string from a `StringBuilder` instance and return it to the cache.
+* GetScope : Get a `using` scoped `StringBuilder` instance from the cache and return it to the cache when the scope is exited.
+* Monitoring with `Events` feature of the .NET runtime for detailed cache management.
+
+`InterlockedOps` is a static class providing the following thread-safe atomic operations:
 
-The roadmap plan for this package is to add several additional helpful performance focused utilities. These will be forthcoming as time permits, so this first release is focused just on the `MemoryStreamSlim` class.
+* Xor : Exclusive OR operation on any integer types.
+* ClearBits : Clear bits on any integer types.
+* SetBits : Set bits on any integer types.
+* ConditionAnd : Conditionally update bits using an AND operation on any integer types.
+* ConditionOr : Conditionally update bits using an OR operation on any integer types.
+* ConditionXor : Conditionally update bits using an XOR operation on any integer types.
+* ConditionClearBits : Conditionally clear bits on any integer types.
+* ConditionSetBits : Conditionally set bits on any integer types.
 
 ## Documentation
 
 Full documentation for the package is available on the [PerfUtils Documentation](https://kzdev-net.github.io/kzdev.perfutils/) page.
 
+## Future Features
+
+The roadmap plan for this package is to add several additional helpful performance focused utilities as time allows.
+
 ## Contribution Guidelines
 
 At this time, I am not accepting external pull requests. However, any feedback or suggestions are welcome and can be provided through the following channels:
 
-- **Feature Requests:** Please use GitHub Discussions to discuss new new features or enhancements before opening a feature request. This will help ensure that your request is in line with the project's goals and vision.
+- **Feature Requests:** Please use GitHub Discussions to discuss new features or enhancements before opening a feature request. This will help ensure that your request is in line with the project's goals and vision.
 - **Bug Reports:** If you encounter any issues, feel free to open an issue so it can be addressed promptly.
 
 I appreciate your understanding and look forward to collaborating with you through discussions and issue tracking.

Source/.editorconfig

@@ -68,7 +68,6 @@ dotnet_style_parentheses_in_other_binary_operators = always_for_clarity:none
 dotnet_style_parentheses_in_relational_binary_operators = never_if_unnecessary:none
 dotnet_style_predefined_type_for_locals_parameters_members = true:suggestion
 dotnet_style_predefined_type_for_member_access = true:suggestion
-dotnet_style_qualification_for_field = true:none
 dotnet_style_require_accessibility_modifiers = for_non_interface_members:suggestion
 
 # ReSharper properties
@@ -147,3 +146,47 @@ csharp_style_expression_bodied_indexers = true:silent
 csharp_style_expression_bodied_accessors = true:silent
 csharp_style_expression_bodied_lambdas = true:silent
 csharp_style_expression_bodied_local_functions = false:silent
+csharp_prefer_system_threading_lock = true:suggestion
+dotnet_style_qualification_for_field = false:silent
+dotnet_style_qualification_for_property = false:silent
+dotnet_style_qualification_for_method = false:silent
+dotnet_style_qualification_for_event = false:silent
+dotnet_style_prefer_compound_assignment = true:suggestion
+dotnet_style_prefer_simplified_interpolation = true:suggestion
+dotnet_style_prefer_collection_expression = when_types_loosely_match:suggestion
+dotnet_style_namespace_match_folder = false:silent
+csharp_style_throw_expression = true:suggestion
+csharp_style_prefer_null_check_over_type_check = true:suggestion
+csharp_prefer_simple_default_expression = true:suggestion
+csharp_style_prefer_local_over_anonymous_function = true:suggestion
+csharp_style_prefer_index_operator = true:suggestion
+csharp_style_prefer_range_operator = true:suggestion
+csharp_style_implicit_object_creation_when_type_is_apparent = true:suggestion
+csharp_style_prefer_tuple_swap = true:suggestion
+csharp_style_inlined_variable_declaration = true:suggestion
+csharp_style_deconstructed_variable_declaration = true:suggestion
+csharp_style_unused_value_assignment_preference = discard_variable:suggestion
+csharp_style_unused_value_expression_statement_preference = discard_variable:silent
+dotnet_style_readonly_field = true:suggestion
+csharp_prefer_static_local_function = true:suggestion
+csharp_prefer_static_anonymous_function = true:suggestion
+csharp_style_prefer_readonly_struct = true:suggestion
+csharp_style_prefer_readonly_struct_member = true:suggestion
+dotnet_style_allow_multiple_blank_lines_experimental = true:silent
+dotnet_style_allow_statement_immediately_after_block_experimental = true:silent
+csharp_style_allow_embedded_statements_on_same_line_experimental = true:silent
+csharp_style_allow_blank_lines_between_consecutive_braces_experimental = true:silent
+csharp_style_allow_blank_line_after_colon_in_constructor_initializer_experimental = true:silent
+csharp_style_allow_blank_line_after_token_in_conditional_expression_experimental = true:silent
+csharp_style_allow_blank_line_after_token_in_arrow_expression_clause_experimental = true:silent
+csharp_style_conditional_delegate_call = true:suggestion
+dotnet_code_quality_unused_parameters = all:suggestion
+dotnet_style_parentheses_in_other_operators = never_if_unnecessary:silent
+csharp_style_prefer_switch_expression = true:suggestion
+csharp_style_prefer_pattern_matching = true:silent
+csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
+csharp_style_pattern_matching_over_as_with_null_check = true:suggestion
+csharp_style_prefer_not_pattern = true:suggestion
+csharp_style_prefer_extended_property_pattern = true:suggestion
+csharp_style_var_when_type_is_apparent = false:silent
+csharp_style_var_elsewhere = false:silent

Source/Dev/KZDev.PerfUtils.Examples/InterlockedOperations/ConditionAndExample.cs

@@ -1,13 +1,12 @@
-namespace KZDev.PerfUtils.Examples
+namespace KZDev.PerfUtils.Examples;
+
+public class ConditionXorExample
 {
-    public class ConditionXorExample
-    {
-        private int _flags;
+    private int _flags;
 
-        public bool ToggleFlags (Predicate<int> condition, int flagBits)
-        {
-            (int originalValue, int newValue) = InterlockedOps.ConditionXor(ref _flags, condition, flagBits);
-            return originalValue != newValue;
-        }
+    public bool ToggleFlags (Predicate<int> condition, int flagBits)
+    {
+        (int originalValue, int newValue) = InterlockedOps.ConditionXor(ref _flags, condition, flagBits);
+        return originalValue != newValue;
     }
-}
+}

Source/Dev/KZDev.PerfUtils.Examples/InterlockedOperations/ConditionClearBitsExample.cs

@@ -1,13 +1,12 @@
-namespace KZDev.PerfUtils.Examples
+namespace KZDev.PerfUtils.Examples;
+
+public class ConditionClearBitsExample
 {
-    public class ConditionClearBitsExample
-    {
-        private int _flags;
+    private int _flags;
 
-        public bool ClearFlags<T> (Func<int, T, bool> condition, T conditionArgument, int flagBits)
-        {
-            (int originalValue, int newValue) = InterlockedOps.ConditionClearBits(ref _flags, condition, conditionArgument, flagBits);
-            return originalValue != newValue;
-        }
+    public bool ClearFlags<T> (Func<int, T, bool> condition, T conditionArgument, int flagBits)
+    {
+        (int originalValue, int newValue) = InterlockedOps.ConditionClearBits(ref _flags, condition, conditionArgument, flagBits);
+        return originalValue != newValue;
     }
-}
+}

Source/Dev/KZDev.PerfUtils.Examples/InterlockedOperations/XorExample.cs

@@ -1,13 +1,12 @@
-namespace KZDev.PerfUtils.Examples
+namespace KZDev.PerfUtils.Examples;
+
+public class XorExample
 {
-    public class XorExample
-    {
-        private int _flag;
+    private int _flag;
 
-        public bool ToggleFlag ()
-        {
-            int originalValue = InterlockedOps.Xor(ref _flag, 1);
-            return originalValue == 0;
-        }
+    public bool ToggleFlag ()
+    {
+        int originalValue = InterlockedOps.Xor(ref _flag, 1);
+        return originalValue == 0;
     }
-}
+}

Source/Dev/KZDev.PerfUtils.Examples/KZDev.PerfUtils.Examples.csproj

@@ -1,17 +1,21 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-  <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-  </PropertyGroup>
+	<PropertyGroup>
+		<TargetFramework>net8.0</TargetFramework>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<Nullable>enable</Nullable>
+	</PropertyGroup>
 
-  <ItemGroup>
-    <Folder Include="MemoryStreamSlim\" />
-  </ItemGroup>
+	<ItemGroup>
+		<AssemblyAttribute Include="System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage" />
+	</ItemGroup>
 
-  <ItemGroup>
-    <ProjectReference Include="..\..\Src\KZDev.PerfUtils\KZDev.PerfUtils.csproj" />
-  </ItemGroup>
+	<ItemGroup>
+		<ProjectReference Include="..\..\Src\KZDev.PerfUtils\KZDev.PerfUtils.csproj" />
+	</ItemGroup>
+
+	<ItemGroup>
+	  <Folder Include="MemoryStreamSlim\" />
+	</ItemGroup>
 
 </Project>

Source/Dev/KZDev.PerfUtils.Examples/StringBuilderCache/StringBuilderExample.cs

@@ -0,0 +1,32 @@
+using System.Text;
+
+namespace KZDev.PerfUtils.Examples;
+
+public class StringBuilderExample
+{
+    public static void SimpleRelease ()
+    {
+        StringBuilder stringBuilder = StringBuilderCache.Acquire();
+        stringBuilder.Append("Hello, ");
+        stringBuilder.Append("World!");
+        Console.WriteLine(stringBuilder.ToString());
+        StringBuilderCache.Release(stringBuilder);
+    }
+
+    public static void GetStringAndRelease ()
+    {
+        StringBuilder stringBuilder = StringBuilderCache.Acquire();
+        stringBuilder.Append("Hello, ");
+        stringBuilder.Append("World!");
+        Console.WriteLine(StringBuilderCache.GetStringAndRelease(stringBuilder));
+    }
+
+    public static void GetScopeAndString()
+    {
+        using StringBuilderScope builderScope = StringBuilderCache.GetScope();
+        StringBuilder builder = builderScope.Builder;
+        builder.Append("Hello, ");
+        builder.Append("World!");
+        Console.WriteLine(builderScope.ToString());
+    }
+}