Add async version of concurrent first usage test

Author: stevejgordon

tests/Tests/ClientConcepts/ConnectionPooling/BuildingBlocks/RequestPipelines.doc.cs

@@ -189,6 +189,77 @@ public void FirstUsageCheckConcurrentThreads()
 			semaphoreSlim.CurrentCount.Should().Be(1);
 		}
 
+		// hide
+		[U] public async Task FirstUsageCheckConcurrentThreadsAsync()
+		{
+			//hide
+			var response = new
+			{
+				cluster_name = "elasticsearch",
+				nodes = new
+				{
+					node1 = new
+					{
+						name = "Node Name 1",
+						transport_address = "127.0.0.1:9300",
+						host = "127.0.0.1",
+						ip = "127.0.01",
+						version = "5.0.0-alpha3",
+						build_hash = "e455fd0",
+						roles = new List<string>(),
+						http = new
+						{
+							bound_address = new[] { "127.0.0.1:9200" }
+						},
+						settings = new Dictionary<string, object>
+						{
+							{ "cluster.name", "elasticsearch" },
+							{ "node.name", "Node Name 1" }
+						}
+					}
+				}
+			};
+
+			//hide
+			var responseBody = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(response));
+
+			/** We can demonstrate this with the following example. First, let's configure
+			 * a custom `IConnection` implementation that's simply going to return a known
+			 * 200 response after one second
+			 */
+			var inMemoryConnection = new WaitingInMemoryConnection(
+				TimeSpan.FromSeconds(1),
+				responseBody);
+
+			/**
+			 * Next, we create a <<sniffing-connection-pool, Sniffing connection pool>> using our
+			 * custom connection and a timeout for how long a request can take before the client
+			 * times out
+			 */
+			var sniffingPipeline = CreatePipeline(
+				uris => new SniffingConnectionPool(uris),
+				connection: inMemoryConnection,
+				settingsSelector: s => s.RequestTimeout(TimeSpan.FromSeconds(2)));
+
+			/**Now, with a `SemaphoreSlim` in place that allows only one thread to enter at a time,
+			 * start three tasks that will initiate a sniff on startup.
+			 *
+			 * The first task will successfully sniff on startup with the remaining two waiting
+			 * tasks exiting without exception. The `SemaphoreSlim` is also released, ready for
+			 * when sniffing needs to take place again
+			 */
+			var semaphoreSlim = new SemaphoreSlim(1, 1);
+
+			var task1 = sniffingPipeline.FirstPoolUsageAsync(semaphoreSlim, CancellationToken.None);
+			var task2 = sniffingPipeline.FirstPoolUsageAsync(semaphoreSlim, CancellationToken.None);
+			var task3 = sniffingPipeline.FirstPoolUsageAsync(semaphoreSlim, CancellationToken.None);
+
+			var exception = await Record.ExceptionAsync(async () => await Task.WhenAll(task1, task2, task3));
+
+			exception.Should().BeNull();
+			semaphoreSlim.CurrentCount.Should().Be(1);
+		}
+
 		/**==== Sniff on connection failure */
 		[U]
 		public void SniffsOnConnectionFailure()