Implement Tar async APIs (#70574)

* ref: TarEntry.ExtractToFileAsync
* src: Implement TarEntry.ExtractToFileAsync
* ref: Add TarReader.GetNextEntryAsync
* src: Implement TarReader.GetNextEntryAsync
* ref: Add TarWriter.WriteEntryAsync
* src: Implement TarWriter.WriteEntryAsync
* ref: Add TarFile.CreateFromDirectoryAsync
* src: Implement TarFile.CreateFromDirectoryAsync
* ref: Add TarFile.ExtractToDirectoryAsync
* src: Implement TarFile.ExtractToDirectoryAsync
* ref: Add TarWriter.DisposeAsync
* src: Implement TarWriter.DisposeAsync
* ref: Add TarReader.DisposeAsync
* src: Implement TarReader.DisposeAsync
* tests: Async tests, analogous to the sync ones.

Author: carlossanlop

src/libraries/System.Formats.Tar/ref/System.Formats.Tar.cs

@@ -48,6 +48,7 @@ internal TarEntry() { }
         public string Name { get { throw null; } set { } }
         public int Uid { get { throw null; } set { } }
         public void ExtractToFile(string destinationFileName, bool overwrite) { }
+        public System.Threading.Tasks.Task ExtractToFileAsync(string destinationFileName, bool overwrite, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public override string ToString() { throw null; }
     }
     public enum TarEntryFormat
@@ -83,24 +84,33 @@ public static partial class TarFile
     {
         public static void CreateFromDirectory(string sourceDirectoryName, System.IO.Stream destination, bool includeBaseDirectory) { }
         public static void CreateFromDirectory(string sourceDirectoryName, string destinationFileName, bool includeBaseDirectory) { }
+        public static System.Threading.Tasks.Task CreateFromDirectoryAsync(string sourceDirectoryName, System.IO.Stream destination, bool includeBaseDirectory, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public static System.Threading.Tasks.Task CreateFromDirectoryAsync(string sourceDirectoryName, string destinationFileName, bool includeBaseDirectory, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public static void ExtractToDirectory(System.IO.Stream source, string destinationDirectoryName, bool overwriteFiles) { }
         public static void ExtractToDirectory(string sourceFileName, string destinationDirectoryName, bool overwriteFiles) { }
+        public static System.Threading.Tasks.Task ExtractToDirectoryAsync(System.IO.Stream source, string destinationDirectoryName, bool overwriteFiles, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public static System.Threading.Tasks.Task ExtractToDirectoryAsync(string sourceFileName, string destinationDirectoryName, bool overwriteFiles, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
-    public sealed partial class TarReader : System.IDisposable
+    public sealed partial class TarReader : System.IAsyncDisposable, System.IDisposable
     {
         public TarReader(System.IO.Stream archiveStream, bool leaveOpen = false) { }
         public void Dispose() { }
+        public System.Threading.Tasks.ValueTask DisposeAsync() { throw null; }
         public System.Formats.Tar.TarEntry? GetNextEntry(bool copyData = false) { throw null; }
+        public System.Threading.Tasks.ValueTask<System.Formats.Tar.TarEntry?> GetNextEntryAsync(bool copyData = false, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
-    public sealed partial class TarWriter : System.IDisposable
+    public sealed partial class TarWriter : System.IAsyncDisposable, System.IDisposable
     {
         public TarWriter(System.IO.Stream archiveStream) { }
         public TarWriter(System.IO.Stream archiveStream, bool leaveOpen = false) { }
         public TarWriter(System.IO.Stream archiveStream, System.Formats.Tar.TarEntryFormat format = System.Formats.Tar.TarEntryFormat.Pax, bool leaveOpen = false) { }
         public System.Formats.Tar.TarEntryFormat Format { get { throw null; } }
         public void Dispose() { }
+        public System.Threading.Tasks.ValueTask DisposeAsync() { throw null; }
         public void WriteEntry(System.Formats.Tar.TarEntry entry) { }
         public void WriteEntry(string fileName, string? entryName) { }
+        public System.Threading.Tasks.Task WriteEntryAsync(System.Formats.Tar.TarEntry entry, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public System.Threading.Tasks.Task WriteEntryAsync(string fileName, string? entryName, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     public sealed partial class UstarTarEntry : System.Formats.Tar.PosixTarEntry
     {

src/libraries/System.Formats.Tar/src/Resources/Strings.resx

@@ -234,7 +234,7 @@
   <data name="TarSizeFieldNegative" xml:space="preserve">
     <value>The size field is negative in the tar entry '{0}'.</value>
   </data>
-  <data name="TarSizeFieldTooLargeForExtendedAttribute" xml:space="preserve">
+  <data name="TarSizeFieldTooLargeForEntryType" xml:space="preserve">
     <value>The value of the size field for the current entry of type '{0}' is beyond the expected length.</value>
   </data>
   <data name="TarSymbolicLinkTargetNotExists" xml:space="preserve">

src/libraries/System.Formats.Tar/src/System/Formats/Tar/SeekableSubReadStream.cs

@@ -71,6 +71,10 @@ public override int Read(Span<byte> destination)
 
         public override ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
         {
+            if (cancellationToken.IsCancellationRequested)
+            {
+                return ValueTask.FromCanceled<int>(cancellationToken);
+            }
             ThrowIfDisposed();
             VerifyPositionInSuperStream();
             return ReadAsyncCore(buffer, cancellationToken);

src/libraries/System.Formats.Tar/src/System/Formats/Tar/SubReadStream.cs

@@ -132,12 +132,20 @@ public override int ReadByte()
 
         public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)
         {
+            if (cancellationToken.IsCancellationRequested)
+            {
+                return Task.FromCanceled<int>(cancellationToken);
+            }
             ValidateBufferArguments(buffer, offset, count);
             return ReadAsync(new Memory<byte>(buffer, offset, count), cancellationToken).AsTask();
         }
 
         public override ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
         {
+            if (cancellationToken.IsCancellationRequested)
+            {
+                return ValueTask.FromCanceled<int>(cancellationToken);
+            }
             ThrowIfDisposed();
             ThrowIfBeyondEndOfStream();
             return ReadAsyncCore(buffer, cancellationToken);
@@ -147,6 +155,8 @@ protected async ValueTask<int> ReadAsyncCore(Memory<byte> buffer, CancellationTo
         {
             Debug.Assert(!_hasReachedEnd);
 
+            cancellationToken.ThrowIfCancellationRequested();
+
             if (_positionInSuperStream > _endInSuperStream - buffer.Length)
             {
                 buffer = buffer.Slice(0, (int)(_endInSuperStream - _positionInSuperStream));

src/libraries/System.Formats.Tar/src/System/Formats/Tar/TarEntry.Unix.cs

@@ -11,28 +11,28 @@ namespace System.Formats.Tar
     public abstract partial class TarEntry
     {
         // Unix specific implementation of the method that extracts the current entry as a block device.
-        partial void ExtractAsBlockDevice(string destinationFileName)
+        private void ExtractAsBlockDevice(string destinationFileName)
         {
             Debug.Assert(EntryType is TarEntryType.BlockDevice);
             Interop.CheckIo(Interop.Sys.CreateBlockDevice(destinationFileName, (uint)Mode, (uint)_header._devMajor, (uint)_header._devMinor), destinationFileName);
         }
 
         // Unix specific implementation of the method that extracts the current entry as a character device.
-        partial void ExtractAsCharacterDevice(string destinationFileName)
+        private void ExtractAsCharacterDevice(string destinationFileName)
         {
             Debug.Assert(EntryType is TarEntryType.CharacterDevice);
             Interop.CheckIo(Interop.Sys.CreateCharacterDevice(destinationFileName, (uint)Mode, (uint)_header._devMajor, (uint)_header._devMinor), destinationFileName);
         }
 
         // Unix specific implementation of the method that extracts the current entry as a fifo file.
-        partial void ExtractAsFifo(string destinationFileName)
+        private void ExtractAsFifo(string destinationFileName)
         {
             Debug.Assert(EntryType is TarEntryType.Fifo);
             Interop.CheckIo(Interop.Sys.MkFifo(destinationFileName, (uint)Mode), destinationFileName);
         }
 
         // Unix specific implementation of the method that extracts the current entry as a hard link.
-        partial void ExtractAsHardLink(string targetFilePath, string hardLinkFilePath)
+        private void ExtractAsHardLink(string targetFilePath, string hardLinkFilePath)
         {
             Debug.Assert(EntryType is TarEntryType.HardLink);
             Debug.Assert(!string.IsNullOrEmpty(targetFilePath));
@@ -41,7 +41,7 @@ partial void ExtractAsHardLink(string targetFilePath, string hardLinkFilePath)
         }
 
         // Unix specific implementation of the method that specifies the file permissions of the extracted file.
-        partial void SetModeOnFile(SafeFileHandle handle, string destinationFileName)
+        private void SetModeOnFile(SafeFileHandle handle)
         {
             // Only extract USR, GRP, and OTH file permissions, and ignore
             // S_ISUID, S_ISGID, and S_ISVTX bits.

src/libraries/System.Formats.Tar/src/System/Formats/Tar/TarEntry.Windows.cs

@@ -10,28 +10,28 @@ namespace System.Formats.Tar
     public abstract partial class TarEntry
     {
         // Throws on Windows. Block devices are not supported on this platform.
-        partial void ExtractAsBlockDevice(string destinationFileName)
+        private void ExtractAsBlockDevice(string destinationFileName)
         {
             Debug.Assert(EntryType is TarEntryType.BlockDevice or TarEntryType.CharacterDevice);
             throw new InvalidOperationException(SR.IO_DeviceFiles_NotSupported);
         }
 
         // Throws on Windows. Character devices are not supported on this platform.
-        partial void ExtractAsCharacterDevice(string destinationFileName)
+        private void ExtractAsCharacterDevice(string destinationFileName)
         {
             Debug.Assert(EntryType is TarEntryType.BlockDevice or TarEntryType.CharacterDevice);
             throw new InvalidOperationException(SR.IO_DeviceFiles_NotSupported);
         }
 
         // Throws on Windows. Fifo files are not supported on this platform.
-        partial void ExtractAsFifo(string destinationFileName)
+        private void ExtractAsFifo(string destinationFileName)
         {
             Debug.Assert(EntryType is TarEntryType.Fifo);
             throw new InvalidOperationException(SR.IO_FifoFiles_NotSupported);
         }
 
         // Windows specific implementation of the method that extracts the current entry as a hard link.
-        partial void ExtractAsHardLink(string targetFilePath, string hardLinkFilePath)
+        private void ExtractAsHardLink(string targetFilePath, string hardLinkFilePath)
         {
             Debug.Assert(EntryType is TarEntryType.HardLink);
             Debug.Assert(!string.IsNullOrEmpty(targetFilePath));
@@ -41,7 +41,7 @@ partial void ExtractAsHardLink(string targetFilePath, string hardLinkFilePath)
 
         // Mode is not used on Windows.
 #pragma warning disable CA1822 //  Member 'SetModeOnFile' does not access instance data and can be marked as static
-        partial void SetModeOnFile(SafeFileHandle handle, string destinationFileName)
+        private void SetModeOnFile(SafeFileHandle handle)
 #pragma warning restore CA1822
         {
             // TODO: Verify that executables get their 'executable' permission applied on Windows when extracted, if applicable. https://github.com/dotnet/runtime/issues/68230