TryPause -> PauseIfRunning (Azure#36246)

jaschrep-msft · web-flow · commit 7aba53b5e355 · 2023-05-12T13:47:46.000-04:00
* TryPause -&gt; PauseIfRunning

* exportapi
diff --git a/sdk/storage/Azure.Storage.DataMovement/api/Azure.Storage.DataMovement.net6.0.cs b/sdk/storage/Azure.Storage.DataMovement/api/Azure.Storage.DataMovement.net6.0.cs
@@ -8,7 +8,7 @@ internal DataTransfer() { }
         public Azure.Storage.DataMovement.StorageTransferStatus TransferStatus { get { throw null; } }
         public System.Threading.Tasks.Task AwaitCompletion(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public void EnsureCompleted(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { }
-        public System.Threading.Tasks.Task<bool> TryPauseAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public System.Threading.Tasks.Task PauseIfRunningAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     [System.FlagsAttribute]
     public enum ErrorHandlingOptions
@@ -117,11 +117,11 @@ public partial class TransferManager : System.IAsyncDisposable
     {
         protected TransferManager() { }
         public TransferManager(Azure.Storage.DataMovement.TransferManagerOptions options = null) { }
+        public virtual System.Threading.Tasks.Task PauseTransferIfRunningAsync(Azure.Storage.DataMovement.DataTransfer transfer, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Threading.Tasks.Task PauseTransferIfRunningAsync(string transferId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Storage.DataMovement.DataTransfer> StartTransferAsync(Azure.Storage.DataMovement.StorageResource sourceResource, Azure.Storage.DataMovement.StorageResource destinationResource, Azure.Storage.DataMovement.Models.TransferOptions transferOptions = null) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Storage.DataMovement.DataTransfer> StartTransferAsync(Azure.Storage.DataMovement.StorageResourceContainer sourceResource, Azure.Storage.DataMovement.StorageResourceContainer destinationResource, Azure.Storage.DataMovement.Models.TransferOptions transferOptions = null) { throw null; }
         System.Threading.Tasks.ValueTask System.IAsyncDisposable.DisposeAsync() { throw null; }
-        public virtual System.Threading.Tasks.Task<bool> TryPauseTransferAsync(Azure.Storage.DataMovement.DataTransfer transfer, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public virtual System.Threading.Tasks.Task<bool> TryPauseTransferAsync(string transferId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     public partial class TransferManagerOptions
     {
diff --git a/sdk/storage/Azure.Storage.DataMovement/api/Azure.Storage.DataMovement.netstandard2.0.cs b/sdk/storage/Azure.Storage.DataMovement/api/Azure.Storage.DataMovement.netstandard2.0.cs
@@ -8,7 +8,7 @@ internal DataTransfer() { }
         public Azure.Storage.DataMovement.StorageTransferStatus TransferStatus { get { throw null; } }
         public System.Threading.Tasks.Task AwaitCompletion(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public void EnsureCompleted(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { }
-        public System.Threading.Tasks.Task<bool> TryPauseAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public System.Threading.Tasks.Task PauseIfRunningAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     [System.FlagsAttribute]
     public enum ErrorHandlingOptions
@@ -117,11 +117,11 @@ public partial class TransferManager : System.IAsyncDisposable
     {
         protected TransferManager() { }
         public TransferManager(Azure.Storage.DataMovement.TransferManagerOptions options = null) { }
+        public virtual System.Threading.Tasks.Task PauseTransferIfRunningAsync(Azure.Storage.DataMovement.DataTransfer transfer, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Threading.Tasks.Task PauseTransferIfRunningAsync(string transferId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Storage.DataMovement.DataTransfer> StartTransferAsync(Azure.Storage.DataMovement.StorageResource sourceResource, Azure.Storage.DataMovement.StorageResource destinationResource, Azure.Storage.DataMovement.Models.TransferOptions transferOptions = null) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Storage.DataMovement.DataTransfer> StartTransferAsync(Azure.Storage.DataMovement.StorageResourceContainer sourceResource, Azure.Storage.DataMovement.StorageResourceContainer destinationResource, Azure.Storage.DataMovement.Models.TransferOptions transferOptions = null) { throw null; }
         System.Threading.Tasks.ValueTask System.IAsyncDisposable.DisposeAsync() { throw null; }
-        public virtual System.Threading.Tasks.Task<bool> TryPauseTransferAsync(Azure.Storage.DataMovement.DataTransfer transfer, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public virtual System.Threading.Tasks.Task<bool> TryPauseTransferAsync(string transferId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     public partial class TransferManagerOptions
     {
diff --git a/sdk/storage/Azure.Storage.DataMovement/api/Azure.Storage.DataMovement.netstandard2.1.cs b/sdk/storage/Azure.Storage.DataMovement/api/Azure.Storage.DataMovement.netstandard2.1.cs
@@ -8,7 +8,7 @@ internal DataTransfer() { }
         public Azure.Storage.DataMovement.StorageTransferStatus TransferStatus { get { throw null; } }
         public System.Threading.Tasks.Task AwaitCompletion(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public void EnsureCompleted(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { }
-        public System.Threading.Tasks.Task<bool> TryPauseAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public System.Threading.Tasks.Task PauseIfRunningAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     [System.FlagsAttribute]
     public enum ErrorHandlingOptions
@@ -117,11 +117,11 @@ public partial class TransferManager : System.IAsyncDisposable
     {
         protected TransferManager() { }
         public TransferManager(Azure.Storage.DataMovement.TransferManagerOptions options = null) { }
+        public virtual System.Threading.Tasks.Task PauseTransferIfRunningAsync(Azure.Storage.DataMovement.DataTransfer transfer, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Threading.Tasks.Task PauseTransferIfRunningAsync(string transferId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Storage.DataMovement.DataTransfer> StartTransferAsync(Azure.Storage.DataMovement.StorageResource sourceResource, Azure.Storage.DataMovement.StorageResource destinationResource, Azure.Storage.DataMovement.Models.TransferOptions transferOptions = null) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Storage.DataMovement.DataTransfer> StartTransferAsync(Azure.Storage.DataMovement.StorageResourceContainer sourceResource, Azure.Storage.DataMovement.StorageResourceContainer destinationResource, Azure.Storage.DataMovement.Models.TransferOptions transferOptions = null) { throw null; }
         System.Threading.Tasks.ValueTask System.IAsyncDisposable.DisposeAsync() { throw null; }
-        public virtual System.Threading.Tasks.Task<bool> TryPauseTransferAsync(Azure.Storage.DataMovement.DataTransfer transfer, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public virtual System.Threading.Tasks.Task<bool> TryPauseTransferAsync(string transferId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
     public partial class TransferManagerOptions
     {
diff --git a/sdk/storage/Azure.Storage.DataMovement/src/Shared/DataTransfer.cs b/sdk/storage/Azure.Storage.DataMovement/src/Shared/DataTransfer.cs
@@ -91,9 +91,9 @@ public async Task AwaitCompletion(CancellationToken cancellationToken = default)
         ///
         /// Will return true if the pause has taken place.
         /// </returns>
-        public Task<bool> TryPauseAsync(CancellationToken cancellationToken = default)
+        public async Task PauseIfRunningAsync(CancellationToken cancellationToken = default)
         {
-            return _state.TryPauseAsync(cancellationToken);
+            await _state.PauseIfRunningAsync(cancellationToken).ConfigureAwait(false);
         }
     }
 }
diff --git a/sdk/storage/Azure.Storage.DataMovement/src/Shared/DataTransferState.cs b/sdk/storage/Azure.Storage.DataMovement/src/Shared/DataTransferState.cs
@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 
 using System;
+using System.Collections.Generic;
 using System.Threading;
 using System.Threading.Tasks;
 using Azure.Core;
@@ -172,14 +173,14 @@ public void UpdateTransferBytes(long transferredBytes)
             }
         }
 
-        public async Task<bool> TryPauseAsync(CancellationToken cancellationToken)
+        public async Task PauseIfRunningAsync(CancellationToken cancellationToken)
         {
             if (StorageTransferStatus.Paused == _status ||
                 StorageTransferStatus.Completed == _status ||
                 StorageTransferStatus.CompletedWithSkippedTransfers == _status ||
                 StorageTransferStatus.CompletedWithFailedTransfers == _status)
             {
-                return false;
+                return;
             }
             CancellationHelper.ThrowIfCancellationRequested(cancellationToken);
             // Call the inner cancellation token to stop the transfer job
@@ -188,9 +189,7 @@ public async Task<bool> TryPauseAsync(CancellationToken cancellationToken)
             {
                 // Wait until full pause has completed.
                 await CompletionSource.Task.AwaitWithCancellation(cancellationToken);
-                return true;
             }
-            return false;
         }
 
         internal bool TriggerCancellation()
diff --git a/sdk/storage/Azure.Storage.DataMovement/src/Shared/TransferManager.cs b/sdk/storage/Azure.Storage.DataMovement/src/Shared/TransferManager.cs
@@ -232,8 +232,8 @@ private async Task NotifyOfPendingJobChunkProcessing()
         /// Return true once the transfer has been successfully paused or false if the transfer
         /// was already completed.
         /// </returns>
-        public virtual Task<bool> TryPauseTransferAsync(DataTransfer transfer, CancellationToken cancellationToken = default)
-            => TryPauseTransferAsync(transfer.Id, cancellationToken);
+        public virtual Task PauseTransferIfRunningAsync(DataTransfer transfer, CancellationToken cancellationToken = default)
+            => PauseTransferIfRunningAsync(transfer.Id, cancellationToken);
 
         /// <summary>
         /// Attempts to pause the transfer of the respective id.
@@ -247,17 +247,14 @@ public virtual Task<bool> TryPauseTransferAsync(DataTransfer transfer, Cancellat
         /// Return true once the transfer has been successfully paused or false if the transfer
         /// was already completed.
         /// </returns>
-        public virtual Task<bool> TryPauseTransferAsync(string transferId, CancellationToken cancellationToken = default)
+        public virtual async Task PauseTransferIfRunningAsync(string transferId, CancellationToken cancellationToken = default)
         {
             Argument.AssertNotNullOrEmpty(transferId, nameof(transferId));
-            if (_dataTransfers.TryGetValue(transferId, out DataTransfer transfer))
+            if (!_dataTransfers.TryGetValue(transferId, out DataTransfer transfer))
             {
-                return transfer.TryPauseAsync(cancellationToken: cancellationToken);
-            }
-            else
-            {
-                throw Errors.InvalidTransferId(nameof(TryPauseTransferAsync), transferId);
+                throw Errors.InvalidTransferId(nameof(PauseTransferIfRunningAsync), transferId);
             }
+            await transfer.PauseIfRunningAsync(cancellationToken: cancellationToken).ConfigureAwait(false);
         }
 
         /// <summary>
diff --git a/sdk/storage/Azure.Storage.DataMovement/src/StorageTransferStatus.cs b/sdk/storage/Azure.Storage.DataMovement/src/StorageTransferStatus.cs
@@ -31,7 +31,7 @@ public enum StorageTransferStatus
         InProgress = 2,
 
         /// <summary>
-        /// The Job has been paused. When transfer is paused (e.g. see <see cref="TransferManager.TryPauseTransferAsync(string, System.Threading.CancellationToken)"/>) during the transfer,
+        /// The Job has been paused. When transfer is paused (e.g. see <see cref="TransferManager.PauseTransferIfRunningAsync(string, System.Threading.CancellationToken)"/>) during the transfer,
         /// this will be the value.
         ///
         /// This status is a resumable state, only
diff --git a/sdk/storage/Azure.Storage.DataMovement/tests/DataTransferTests.cs b/sdk/storage/Azure.Storage.DataMovement/tests/DataTransferTests.cs
@@ -95,7 +95,7 @@ public async Task TryPauseAsync()
         {
             DataTransfer transfer = new DataTransfer(StorageTransferStatus.InProgress);
 
-            Task<bool> pauseTask = transfer.TryPauseAsync();
+            Task pauseTask = transfer.PauseIfRunningAsync();
 
             Assert.AreEqual(StorageTransferStatus.PauseInProgress, transfer.TransferStatus);
 
@@ -104,9 +104,9 @@ public async Task TryPauseAsync()
                 Assert.Fail("Unable to set the transfer status internally to the DataTransfer.");
             }
 
-            bool pauseResult = await pauseTask;
+            await pauseTask;
 
-            Assert.IsTrue(pauseResult);
+            Assert.AreEqual(StorageTransferStatus.Paused, transfer.TransferStatus);
             Assert.IsFalse(transfer.HasCompleted);
         }
 
@@ -119,9 +119,9 @@ public async Task TryPauseAsync_AlreadyPaused(StorageTransferStatus status)
         {
             DataTransfer transfer = new DataTransfer(status);
 
-            bool pauseResult = await transfer.TryPauseAsync();
-
-            Assert.IsFalse(pauseResult);
+            Assert.AreEqual(status, transfer.TransferStatus);
+            await transfer.PauseIfRunningAsync();
+            Assert.AreEqual(status, transfer.TransferStatus);
         }
 
         [Test]
@@ -132,7 +132,7 @@ public async Task TryPauseAsync_CancellationToken()
 
             try
             {
-                await transfer.TryPauseAsync(cancellationTokenSource.Token);
+                await transfer.PauseIfRunningAsync(cancellationTokenSource.Token);
             }
             catch (OperationCanceledException exception)
             {
diff --git a/sdk/storage/Azure.Storage.DataMovement/tests/PauseResumeTransferTests.cs b/sdk/storage/Azure.Storage.DataMovement/tests/PauseResumeTransferTests.cs

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@ internal DataTransfer() { }`
`8`	`8`	`public Azure.Storage.DataMovement.StorageTransferStatus TransferStatus { get { throw null; } }`
`9`	`9`	`public System.Threading.Tasks.Task AwaitCompletion(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }`
`10`	`10`	`public void EnsureCompleted(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { }`
`11`		`- public System.Threading.Tasks.Task<bool> TryPauseAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }`
	`11`	`+ public System.Threading.Tasks.Task PauseIfRunningAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }`
`12`	`12`	`}`
`13`	`13`	`[System.FlagsAttribute]`
`14`	`14`	`public enum ErrorHandlingOptions`
`@@ -117,11 +117,11 @@ public partial class TransferManager : System.IAsyncDisposable`
`117`	`117`	`{`
`118`	`118`	`protected TransferManager() { }`
`119`	`119`	`public TransferManager(Azure.Storage.DataMovement.TransferManagerOptions options = null) { }`
	`120`	`+ public virtual System.Threading.Tasks.Task PauseTransferIfRunningAsync(Azure.Storage.DataMovement.DataTransfer transfer, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }`
	`121`	`+ public virtual System.Threading.Tasks.Task PauseTransferIfRunningAsync(string transferId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }`
`120`	`122`	`public virtual System.Threading.Tasks.Task<Azure.Storage.DataMovement.DataTransfer> StartTransferAsync(Azure.Storage.DataMovement.StorageResource sourceResource, Azure.Storage.DataMovement.StorageResource destinationResource, Azure.Storage.DataMovement.Models.TransferOptions transferOptions = null) { throw null; }`
`121`	`123`	`public virtual System.Threading.Tasks.Task<Azure.Storage.DataMovement.DataTransfer> StartTransferAsync(Azure.Storage.DataMovement.StorageResourceContainer sourceResource, Azure.Storage.DataMovement.StorageResourceContainer destinationResource, Azure.Storage.DataMovement.Models.TransferOptions transferOptions = null) { throw null; }`
`122`	`124`	`System.Threading.Tasks.ValueTask System.IAsyncDisposable.DisposeAsync() { throw null; }`
`123`		`- public virtual System.Threading.Tasks.Task<bool> TryPauseTransferAsync(Azure.Storage.DataMovement.DataTransfer transfer, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }`
`124`		`- public virtual System.Threading.Tasks.Task<bool> TryPauseTransferAsync(string transferId, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }`
`125`	`125`	`}`
`126`	`126`	`public partial class TransferManagerOptions`
`127`	`127`	`{`
Original file line number	Diff line number	Diff line change
`@@ -91,9 +91,9 @@ public async Task AwaitCompletion(CancellationToken cancellationToken = default)`
`91`	`91`	`///`
`92`	`92`	`/// Will return true if the pause has taken place.`
`93`	`93`	`/// </returns>`
`94`		`- public Task<bool> TryPauseAsync(CancellationToken cancellationToken = default)`
	`94`	`+ public async Task PauseIfRunningAsync(CancellationToken cancellationToken = default)`
`95`	`95`	`{`
`96`		`- return _state.TryPauseAsync(cancellationToken);`
	`96`	`+ await _state.PauseIfRunningAsync(cancellationToken).ConfigureAwait(false);`
`97`	`97`	`}`
`98`	`98`	`}`
`99`	`99`	`}`
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@`
`2`	`2`	`// Licensed under the MIT License.`
`3`	`3`
`4`	`4`	`using System;`
	`5`	`+using System.Collections.Generic;`
`5`	`6`	`using System.Threading;`
`6`	`7`	`using System.Threading.Tasks;`
`7`	`8`	`using Azure.Core;`
`@@ -172,14 +173,14 @@ public void UpdateTransferBytes(long transferredBytes)`
`172`	`173`	`}`
`173`	`174`	`}`
`174`	`175`
`175`		`- public async Task<bool> TryPauseAsync(CancellationToken cancellationToken)`
	`176`	`+ public async Task PauseIfRunningAsync(CancellationToken cancellationToken)`
`176`	`177`	`{`
`177`	`178`	`if (StorageTransferStatus.Paused == _status \|\|`
`178`	`179`	`StorageTransferStatus.Completed == _status \|\|`
`179`	`180`	`StorageTransferStatus.CompletedWithSkippedTransfers == _status \|\|`
`180`	`181`	`StorageTransferStatus.CompletedWithFailedTransfers == _status)`
`181`	`182`	`{`
`182`		`- return false;`
	`183`	`+ return;`
`183`	`184`	`}`
`184`	`185`	`CancellationHelper.ThrowIfCancellationRequested(cancellationToken);`
`185`	`186`	`// Call the inner cancellation token to stop the transfer job`
`@@ -188,9 +189,7 @@ public async Task<bool> TryPauseAsync(CancellationToken cancellationToken)`
`188`	`189`	`{`
`189`	`190`	`// Wait until full pause has completed.`
`190`	`191`	`await CompletionSource.Task.AwaitWithCancellation(cancellationToken);`
`191`		`- return true;`
`192`	`192`	`}`
`193`		`- return false;`
`194`	`193`	`}`
`195`	`194`
`196`	`195`	`internal bool TriggerCancellation()`
Original file line number	Diff line number	Diff line change
`@@ -95,7 +95,7 @@ public async Task TryPauseAsync()`
`95`	`95`	`{`
`96`	`96`	`DataTransfer transfer = new DataTransfer(StorageTransferStatus.InProgress);`
`97`	`97`
`98`		`- Task<bool> pauseTask = transfer.TryPauseAsync();`
	`98`	`+ Task pauseTask = transfer.PauseIfRunningAsync();`
`99`	`99`
`100`	`100`	`Assert.AreEqual(StorageTransferStatus.PauseInProgress, transfer.TransferStatus);`
`101`	`101`
`@@ -104,9 +104,9 @@ public async Task TryPauseAsync()`
`104`	`104`	`Assert.Fail("Unable to set the transfer status internally to the DataTransfer.");`
`105`	`105`	`}`
`106`	`106`
`107`		`- bool pauseResult = await pauseTask;`
	`107`	`+ await pauseTask;`
`108`	`108`
`109`		`- Assert.IsTrue(pauseResult);`
	`109`	`+ Assert.AreEqual(StorageTransferStatus.Paused, transfer.TransferStatus);`
`110`	`110`	`Assert.IsFalse(transfer.HasCompleted);`
`111`	`111`	`}`
`112`	`112`
`@@ -119,9 +119,9 @@ public async Task TryPauseAsync_AlreadyPaused(StorageTransferStatus status)`
`119`	`119`	`{`
`120`	`120`	`DataTransfer transfer = new DataTransfer(status);`
`121`	`121`
`122`		`- bool pauseResult = await transfer.TryPauseAsync();`
`123`		`-`
`124`		`- Assert.IsFalse(pauseResult);`
	`122`	`+ Assert.AreEqual(status, transfer.TransferStatus);`
	`123`	`+ await transfer.PauseIfRunningAsync();`
	`124`	`+ Assert.AreEqual(status, transfer.TransferStatus);`
`125`	`125`	`}`
`126`	`126`
`127`	`127`	`[Test]`
`@@ -132,7 +132,7 @@ public async Task TryPauseAsync_CancellationToken()`
`132`	`132`
`133`	`133`	`try`
`134`	`134`	`{`
`135`		`- await transfer.TryPauseAsync(cancellationTokenSource.Token);`
	`135`	`+ await transfer.PauseIfRunningAsync(cancellationTokenSource.Token);`
`136`	`136`	`}`
`137`	`137`	`catch (OperationCanceledException exception)`
`138`	`138`	`{`