Merge pull request #1354 from adamhathcock/adam/instance-buffer-size

Instanced buffer size

Author: adamhathcock

.config/dotnet-tools.json

@@ -3,11 +3,11 @@
   "isRoot": true,
   "tools": {
     "csharpier": {
-      "version": "1.2.6",
+      "version": "1.3.0",
       "commands": [
         "csharpier"
       ],
       "rollForward": false
     }
   }
-}
+}

docs/API.md

@@ -92,7 +92,8 @@ using (var archive = GZipArchive.CreateArchive())
 // With fluent options (preferred)
 var options = WriterOptions.ForZip()
     .WithCompressionLevel(9)
-    .WithLeaveStreamOpen(false);
+    .WithLeaveStreamOpen(false)
+    .WithBufferSize(131072);
 using (var archive = ZipArchive.CreateArchive())
 {
     archive.SaveTo("output.zip", options);
@@ -102,10 +103,13 @@ using (var archive = ZipArchive.CreateArchive())
 var options2 = new WriterOptions(CompressionType.Deflate)
 {
     CompressionLevel = 9,
-    LeaveStreamOpen = false
+    LeaveStreamOpen = false,
+    BufferSize = 131072
 };
 ```
 
+`WriterOptions.BufferSize` controls stream copy buffers used while writing archive entries. If it is not set, SharpCompress falls back to `Constants.BufferSize`.
+
 ---
 
 ## Archive API Methods
@@ -315,6 +319,9 @@ var safeOptions = ExtractionOptions.SafeExtract;  // No overwrite
 var flatOptions = ExtractionOptions.FlatExtract;  // No directory structure
 var metadataOptions = ExtractionOptions.PreserveMetadata; // Keep timestamps and attributes
 
+// Tune extraction copy buffering
+var extractionOptions = new ExtractionOptions { BufferSize = 131072 };
+
 // Factory defaults:
 // - file path / FileInfo overloads use LeaveStreamOpen = false
 // - stream overloads use LeaveStreamOpen = true
@@ -334,6 +341,13 @@ var options = new ReaderOptions
     BufferSize = 81920,
     RewindableBufferSize = 1_048_576,
 };
+
+var extractionOptions = new ExtractionOptions
+{
+    ExtractFullPath = true,
+    Overwrite = true,
+    BufferSize = 131072,
+};
 ```
 
 ### WriterOptions

docs/USAGE.md

@@ -100,7 +100,12 @@ using (var archive = RarArchive.OpenArchive("Test.rar", ReaderOptions.ForFilePat
     // Simple extraction with RarArchive; this WriteToDirectory pattern works for all archive types
     archive.WriteToDirectory(
         @"D:\temp",
-        new ExtractionOptions { ExtractFullPath = true, Overwrite = true }
+        new ExtractionOptions
+        {
+            ExtractFullPath = true,
+            Overwrite = true,
+            BufferSize = 131072,
+        }
     );
 }
 ```

global.json

@@ -1,6 +1,6 @@
 {
   "sdk": {
     "version": "10.0.300",
-    "rollForward": "latestPatch"
+    "rollForward": "disable"
   }
 }

src/SharpCompress/Archives/IArchiveEntryExtensions.cs

@@ -17,7 +17,14 @@ public static class IArchiveEntryExtensions
         /// </summary>
         /// <param name="streamToWriteTo">The stream to write the entry content to.</param>
         /// <param name="progress">Optional progress reporter for tracking extraction progress.</param>
-        public void WriteTo(Stream streamToWriteTo, IProgress<ProgressReport>? progress = null)
+        public void WriteTo(Stream streamToWriteTo, IProgress<ProgressReport>? progress = null) =>
+            archiveEntry.WriteTo(streamToWriteTo, null, progress);
+
+        private void WriteTo(
+            Stream streamToWriteTo,
+            int? bufferSize,
+            IProgress<ProgressReport>? progress = null
+        )
         {
             if (archiveEntry.IsDirectory)
             {
@@ -26,7 +33,7 @@ public void WriteTo(Stream streamToWriteTo, IProgress<ProgressReport>? progress
 
             using var entryStream = archiveEntry.OpenEntryStream();
             var sourceStream = WrapWithProgress(entryStream, archiveEntry, progress);
-            sourceStream.CopyTo(streamToWriteTo, Constants.BufferSize);
+            sourceStream.CopyTo(streamToWriteTo, bufferSize ?? Constants.BufferSize);
         }
 
         /// <summary>
@@ -40,6 +47,18 @@ public async ValueTask WriteToAsync(
             IProgress<ProgressReport>? progress = null,
             CancellationToken cancellationToken = default
         )
+        {
+            await archiveEntry
+                .WriteToAsync(streamToWriteTo, Constants.BufferSize, progress, cancellationToken)
+                .ConfigureAwait(false);
+        }
+
+        private async ValueTask WriteToAsync(
+            Stream streamToWriteTo,
+            int? bufferSize,
+            IProgress<ProgressReport>? progress = null,
+            CancellationToken cancellationToken = default
+        )
         {
             if (archiveEntry.IsDirectory)
             {
@@ -57,7 +76,7 @@ public async ValueTask WriteToAsync(
 #endif
             var sourceStream = WrapWithProgress(entryStream, archiveEntry, progress);
             await sourceStream
-                .CopyToAsync(streamToWriteTo, Constants.BufferSize, cancellationToken)
+                .CopyToAsync(streamToWriteTo, bufferSize ?? Constants.BufferSize, cancellationToken)
                 .ConfigureAwait(false);
         }
     }
@@ -133,16 +152,18 @@ await entry.WriteToFileAsync(path, options, ct).ConfigureAwait(false),
         /// <summary>
         /// Extract to specific file
         /// </summary>
-        public void WriteToFile(string destinationFileName, ExtractionOptions? options = null) =>
+        public void WriteToFile(string destinationFileName, ExtractionOptions? options = null)
+        {
             entry.WriteEntryToFile(
                 destinationFileName,
                 options,
                 (x, fm) =>
                 {
-                    using var fs = File.Open(destinationFileName, fm);
-                    entry.WriteTo(fs);
+                    using var fs = File.Open(x, fm);
+                    entry.WriteTo(fs, options?.BufferSize ?? Constants.BufferSize);
                 }
             );
+        }
 
         /// <summary>
         /// Extract to specific file asynchronously
@@ -158,8 +179,10 @@ await entry
                     options,
                     async (x, fm, ct) =>
                     {
-                        using var fs = File.Open(destinationFileName, fm);
-                        await entry.WriteToAsync(fs, null, ct).ConfigureAwait(false);
+                        using var fs = File.Open(x, fm);
+                        await entry
+                            .WriteToAsync(fs, options?.BufferSize, null, ct)
+                            .ConfigureAwait(false);
                     },
                     cancellationToken
                 )

src/SharpCompress/Common/Constants.cs

@@ -8,6 +8,7 @@ public static class Constants
     /// The default buffer size for stream operations, matching .NET's Stream.CopyTo default of 81920 bytes.
     /// This can be modified globally at runtime.
     /// </summary>
+    // TODO: Revisit remaining non-extraction usages after extraction buffering moves to ExtractionOptions.
     public static int BufferSize { get; set; } = 81920;
 
     /// <summary>

src/SharpCompress/Common/ExtractionOptions.cs

@@ -38,6 +38,11 @@ public sealed record ExtractionOptions : IExtractionOptions
     /// </summary>
     public bool PreserveAttributes { get; set; }
 
+    /// <summary>
+    /// Buffer size for extraction stream copy operations.
+    /// </summary>
+    public int BufferSize { get; set; } = Constants.BufferSize;
+
     /// <summary>
     /// Delegate for writing symbolic links to disk.
     /// The first parameter is the source path (where the symlink is created).

src/SharpCompress/Common/Options/IExtractionOptions.cs

@@ -30,6 +30,11 @@ public interface IExtractionOptions
     /// </summary>
     bool PreserveAttributes { get; set; }
 
+    /// <summary>
+    /// Buffer size for extraction stream copy operations.
+    /// </summary>
+    int BufferSize { get; set; }
+
     /// <summary>
     /// Delegate for writing symbolic links to disk.
     /// The first parameter is the source path (where the symlink is created).

src/SharpCompress/Common/Options/IWriterOptions.cs

@@ -19,6 +19,11 @@ public interface IWriterOptions : IStreamOptions, IEncodingOptions, IProgressOpt
     /// </summary>
     int CompressionLevel { get; set; }
 
+    /// <summary>
+    /// Buffer size for writer stream copy operations.
+    /// </summary>
+    int BufferSize { get; set; }
+
     /// <summary>
     /// Registry of compression providers.
     /// Defaults to <see cref="CompressionProviderRegistry.Default" /> but can be replaced with custom providers, such as

src/SharpCompress/Readers/AbstractReader.Async.cs

@@ -5,7 +5,6 @@
 using System.Threading;
 using System.Threading.Tasks;
 using SharpCompress.Common;
-using SharpCompress.IO;
 
 namespace SharpCompress.Readers;
 
@@ -138,19 +137,19 @@ public async ValueTask WriteEntryToAsync(
         _wroteCurrentEntry = true;
     }
 
-    internal async ValueTask WriteAsync(Stream writeStream, CancellationToken cancellationToken)
+    private async ValueTask WriteAsync(Stream writeStream, CancellationToken cancellationToken)
     {
 #if LEGACY_DOTNET
         using Stream s = await OpenEntryStreamAsync(cancellationToken).ConfigureAwait(false);
         var sourceStream = WrapWithProgress(s, Entry);
         await sourceStream
-            .CopyToAsync(writeStream, Constants.BufferSize, cancellationToken)
+            .CopyToAsync(writeStream, Options.BufferSize, cancellationToken)
             .ConfigureAwait(false);
 #else
         await using Stream s = await OpenEntryStreamAsync(cancellationToken).ConfigureAwait(false);
         var sourceStream = WrapWithProgress(s, Entry);
         await sourceStream
-            .CopyToAsync(writeStream, Constants.BufferSize, cancellationToken)
+            .CopyToAsync(writeStream, Options.BufferSize, cancellationToken)
             .ConfigureAwait(false);
 #endif
     }
@@ -187,9 +186,7 @@ internal virtual ValueTask<bool> NextEntryForCurrentStreamAsync() =>
     /// <summary>
     /// Moves the current async enumerator to the next entry.
     /// </summary>
-    internal virtual ValueTask<bool> NextEntryForCurrentStreamAsync(
-        CancellationToken cancellationToken
-    )
+    private ValueTask<bool> NextEntryForCurrentStreamAsync(CancellationToken cancellationToken)
     {
         if (_entriesForCurrentReadStreamAsync is not null)
         {
@@ -202,6 +199,9 @@ CancellationToken cancellationToken
     // Async iterator method
     protected virtual async IAsyncEnumerable<TEntry> GetEntriesAsync(Stream stream)
     {
+#pragma warning disable VSTHRD111
+        await Task.CompletedTask;
+#pragma warning restore VSTHRD111
         foreach (var entry in GetEntries(stream))
         {
             yield return entry;