Improve docs and naming of LeaderElector methods. (#1468)

* Improve docs and naming of `LeaderElector` methods. Also introduce `LeaderElector.RunAndTryToHoldLeadershipForeverAsync()`

* fix build

---------

Co-authored-by: Boshi Lian <farmer1992@gmail.com>

src/KubernetesClient/LeaderElection/LeaderElector.cs

@@ -49,7 +49,12 @@ namespace k8s.LeaderElection
             return observedRecord?.HolderIdentity;
         }
 
-        public async Task RunAsync(CancellationToken cancellationToken = default)
+        /// <summary>
+        /// Tries to acquire and hold leadership once via a Kubernetes Lease resource.
+        /// Will complete the returned Task and not retry to acquire leadership again after leadership is lost once.
+        /// </summary>
+        /// <param name="cancellationToken">A token to cancel the operation.</param>
+        public async Task RunUntilLeadershipLostAsync(CancellationToken cancellationToken = default)
         {
             await AcquireAsync(cancellationToken).ConfigureAwait(false);
 
@@ -107,6 +112,32 @@ namespace k8s.LeaderElection
             }
         }
 
+        /// <summary>
+        /// Tries to acquire leadership via a Kubernetes Lease resource.
+        /// Will retry to acquire leadership again after leadership was lost.
+        /// </summary>
+        /// <returns>A Task which completes only on cancellation</returns>
+        /// <param name="cancellationToken">A token to cancel the operation.</param>
+        public async Task RunAndTryToHoldLeadershipForeverAsync(CancellationToken cancellationToken = default)
+        {
+            while (!cancellationToken.IsCancellationRequested)
+            {
+                await RunUntilLeadershipLostAsync(cancellationToken).ConfigureAwait(false);
+            }
+        }
+
+        /// <summary>
+        /// Tries to acquire leadership once via a Kubernetes Lease resource.
+        /// Will complete the returned Task and not retry to acquire leadership again after leadership is lost once.
+        /// </summary>
+        /// <seealso cref="RunUntilLeadershipLostAsync"/>
+        /// <param name="cancellationToken">A token to cancel the operation.</param>
+        [Obsolete("Replaced by RunUntilLeadershipLostAsync to encode behavior in method name.")]
+        public Task RunAsync(CancellationToken cancellationToken = default)
+        {
+            return RunUntilLeadershipLostAsync(cancellationToken);
+        }
+
         private async Task<bool> TryAcquireOrRenew(CancellationToken cancellationToken)
         {
             var l = config.Lock;

tests/KubernetesClient.Tests/LeaderElection/LeaderElectionTests.cs

@@ -71,7 +71,7 @@ namespace k8s.Tests.LeaderElection
                     countdown.Signal();
                 };
 
-                leaderElector.RunAsync().Wait();
+                leaderElector.RunUntilLeadershipLostAsync().Wait();
             });
 
             countdown.Wait(TimeSpan.FromSeconds(10));
@@ -164,7 +164,7 @@ namespace k8s.Tests.LeaderElection
                     lockAStopLeading.Set();
                 };
 
-                leaderElector.RunAsync().Wait();
+                leaderElector.RunUntilLeadershipLostAsync().Wait();
             });
 
 
@@ -186,7 +186,7 @@ namespace k8s.Tests.LeaderElection
                     testLeaderElectionLatch.Signal();
                 };
 
-                leaderElector.RunAsync().Wait();
+                leaderElector.RunUntilLeadershipLostAsync().Wait();
             });
 
             testLeaderElectionLatch.Wait(TimeSpan.FromSeconds(15));
@@ -272,7 +272,7 @@ namespace k8s.Tests.LeaderElection
                     countdown.Signal();
                 };
 
-                leaderElector.RunAsync().Wait();
+                leaderElector.RunUntilLeadershipLostAsync().Wait();
             });
 
             countdown.Wait(TimeSpan.FromSeconds(15));
@@ -305,7 +305,7 @@ namespace k8s.Tests.LeaderElection
 
             try
             {
-                leaderElector.RunAsync().Wait();
+                leaderElector.RunUntilLeadershipLostAsync().Wait();
             }
             catch (Exception e)
             {
@@ -362,7 +362,7 @@ namespace k8s.Tests.LeaderElection
                 countdown.Signal();
             };
 
-            Task.Run(() => leaderElector.RunAsync());
+            Task.Run(() => leaderElector.RunUntilLeadershipLostAsync());
             countdown.Wait(TimeSpan.FromSeconds(10));
 
             Assert.True(notifications.SequenceEqual(new[]
@@ -403,7 +403,7 @@ namespace k8s.Tests.LeaderElection
                 countdown.Signal();
             };
 
-            Task.Run(() => leaderElector.RunAsync());
+            Task.Run(() => leaderElector.RunUntilLeadershipLostAsync());
             countdown.Wait(TimeSpan.FromSeconds(10));
 
             Assert.True(notifications.SequenceEqual(new[] { "foo1" }));