Improve docs and naming of LeaderElector methods. Also introduce LeaderElector.AcquireLeadershipForever()

Author: PSanetra

src/KubernetesClient/LeaderElection/LeaderElector.cs

@@ -49,7 +49,12 @@ public string GetLeader()
             return observedRecord?.HolderIdentity;
         }
 
-        public async Task RunAsync(CancellationToken cancellationToken = default)
+        /// <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>
+        /// <param name="cancellationToken">A token to cancel the operation.</param>
+        public async Task AcquireLeadershipOnce(CancellationToken cancellationToken = default)
         {
             await AcquireAsync(cancellationToken).ConfigureAwait(false);
 
@@ -107,6 +112,31 @@ public async Task RunAsync(CancellationToken cancellationToken = default)
             }
         }
 
+        /// <summary>
+        /// Tries to acquire leadership once via a Kubernetes Lease resource.
+        /// Will retry to acquire leadership again after leadership was lost.
+        /// </summary>
+        /// <param name="cancellationToken">A token to cancel the operation.</param>
+        public async Task AcquireLeadershipForever(CancellationToken cancellationToken = default)
+        {
+            while (!cancellationToken.IsCancellationRequested)
+            {
+                await AcquireLeadershipOnce(cancellationToken);
+            }
+        }
+
+        /// <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="AcquireLeadershipOnce"/>
+        /// <param name="cancellationToken">A token to cancel the operation.</param>
+        [Obsolete("Replaced by AcquireLeadershipOnce to encode behavior in method name.")]
+        public Task RunAsync(CancellationToken cancellationToken = default)
+        {
+            return AcquireLeadershipOnce(cancellationToken);
+        }
+
         private async Task<bool> TryAcquireOrRenew(CancellationToken cancellationToken)
         {
             var l = config.Lock;

tests/KubernetesClient.Tests/LeaderElection/LeaderElectionTests.cs

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