Merge pull request #1005 from szabosteve/review.pre-rq.fm

[DOCS] Fine-tunes per-request conf and futures pages in PHP client book

Author: szabosteve

docs/futures.asciidoc

@@ -1,24 +1,31 @@
 [[future_mode]]
 == Future Mode
 
-The client offers a mode called "future" or "async" mode.  This allows batch processing of requests (sent in parallel
-to the cluster), which can have a dramatic impact on performance and throughput.
+The client offers a mode called "future" or "async" mode. This allows batch 
+processing of requests (sent in parallel to the cluster), which can have a 
+dramatic impact on performance and throughput.
 
-PHP is fundamentally single-threaded, however libcurl provides functionality called the "multi interface".  This allows
-languages like PHP to gain concurrency by providing a batch of requests to process.  The batch is executed in a parallel
-by the underlying multithreaded libcurl library, and the batch of responses is then returned to PHP.
+PHP is fundamentally single-threaded, however, libcurl provides a functionality 
+called the "multi interface". This functionality allows languages like PHP to 
+gain concurrency by providing a batch of requests to process. The batch is 
+executed in parallel by the underlying multithreaded libcurl library, and the 
+batch of responses is then returned to PHP.
 
-In a single-threaded environment, the time to execute `n` requests is the sum of those `n` request's latencies.  With
-the multi interface, the time to execute `n` requests is the latency of the slowest request (assuming enough handles
-are available to execute all requests in parallel).
+In a single-threaded environment, the time to execute `n` requests is the sum of 
+those `n` request's latencies. With the multi interface, the time to execute `n` 
+requests is the latency of the slowest request (assuming enough handles are 
+available to execute all requests in parallel).
+
+Furthermore, the multi-interface allows requests to different hosts 
+simultaneously, which means the Elasticsearch-PHP client can more effectively 
+utilize your full cluster.
 
-Furthermore, the multi-interface allows requests to different hosts simultaneously, which means the Elasticsearch-PHP
-client can more effectively utilize your full cluster.
 
 === Using Future Mode
 
-Utilizing this feature is relatively straightforward, but it does introduce more responsibility into your code.  To enable
-future mode, set the `future` flag in the client options to `'lazy'`:
+Utilizing this feature is straightforward, but it does introduce more 
+responsibility into your code. To enable future mode, set the `future` flag in 
+the client options to `'lazy'`:
 
 [source,php]
 ----
@@ -35,17 +42,22 @@ $params = [
 $future = $client->get($params);
 ----
 
-This will return a _future_, rather than the actual response.  A future represents a _future computation_ and acts like
-a placeholder.  You can pass a future around your code like a regular object.  When you need the result values, you
-can _resolve_ the future.  If the future has already resolved (due to some other activity), the values will be immediately
-available.  If the future has not resolved yet, the resolution will block until those values have become available (e.g.
+This returns a _future_, rather than the actual response. A future represents a 
+_future computation_ and acts like a placeholder. You can pass a future around 
+your code like a regular object. When you need the result values, you can 
+_resolve_ the future. If the future has already resolved (due to some other 
+activity), the values are immediately available. If the future has not resolved 
+yet, the resolution blocks until those values become available (for example, 
 after the API call completes).
 
-In practice, this means you can queue up a batch of requests by using `future: lazy` and they will pend until you resolve
-the futures, at which time all requests will be sent in parallel to the cluster and return asynchronously to curl.
+In practice, this means you can queue up a batch of requests by using 
+`future: lazy` and they pend until you resolve the futures, at which time all 
+requests will be sent in parallel to the cluster and return asynchronously to 
+curl.
 
-This sounds tricky, but it is actually very simple thanks to RingPHP's `FutureArray` interface, which makes the future
-act like a simple associative array.  For example:
+This sounds tricky, but it is actually simple thanks to RingPHP's `FutureArray` 
+interface, which makes the future act like a simple associative array. For 
+example:
 
 [source,php]
 ----
@@ -61,11 +73,12 @@ $params = [
 
 $future = $client->get($params);
 
-$doc = $future['_source'];    // This call will block and force the future to resolve
+$doc = $future['_source'];    // This call blocks and forces the future to resolve
 ----
 
-Interacting with the future as an associative array, just like a normal response, will cause the future to resolve
-that particular value (which in turn resolves all pending requests and values).  This allows patterns such as:
+Interacting with the future as an associative array, just like a normal 
+response, causes the future to resolve that particular value (which in turn 
+resolves all pending requests and values). This allows patterns such as:
 
 [source,php]
 ----
@@ -91,11 +104,11 @@ foreach ($futures as $future) {
 }
 ----
 
-The queued requests will execute in parallel and populate their futures after execution.  Batch size defaults to
-100 requests-per-batch.
+The queued requests will execute in parallel and populate their futures after 
+execution. Batch size defaults to 100 requests/batch.
 
-If you wish to force future resolution, but don't actually need the values immediately, you can call `wait()` on the future
-to force resolution too:
+If you wish to force future resolution, but don't need the values immediately, 
+you can call `wait()` on the future to force resolution, too:
 
 [source,php]
 ----
@@ -120,9 +133,10 @@ $futures[999]->wait();
 
 === Changing batch size
 
-The default batch size is 100, meaning 100 requests will queue up before the client forces futures to begin resolving
-(e.g. initiate a `curl_multi` call).  The batch size can be changed depending on your preferences.  The batch size
-is controllable via the `max_handles` setting when configuring the handler:
+The default batch size is 100, meaning 100 requests queue up before the client 
+forces futures to begin resolving (for example, initiate a `curl_multi` call). 
+The batch size can be changed depending on your preferences. The batch size can 
+be set via the `max_handles` setting when configuring the handler:
 
 [source,php]
 ----
@@ -137,10 +151,11 @@ $client = ClientBuilder::create()
             ->build();
 ----
 
-This will change the behavior to wait on 500 queued requests before sending the batch.  Note, however, that forcing a
-future to resolve will cause the underlying curl batch to execute, regardless of if the batch is "full" or not.  In this
-example, only 499 requests are added to the queue...but the final future resolution will force the batch to flush
-anyway:
+This changes the behavior to wait on 500 queued requests before sending the 
+batch. Note, however, that forcing a future to resolve causes the underlying 
+curl batch to execute, regardless of if the batch is "full" or not. In this 
+example, only 499 requests are added to the queue, but the final future 
+resolution forces the batch to flush anyway:
 
 [source,php]
 ----
@@ -172,10 +187,11 @@ for ($i = 0; $i < 499; $i++) {
 $body = $future[499]['body'];
 ----
 
+
 === Heterogeneous batches are OK
 
-It is possible to queue up heterogeneous batches of requests.  For example, you can queue up several GETs, indexing requests
-and a search:
+It is possible to queue up heterogeneous batches of requests. For example, you 
+can queue up several GETs, indexing requests, and a search:
 
 [source,php]
 ----
@@ -228,24 +244,30 @@ $searchResults = $futures['searchRequest']['hits'];
 $doc = $futures['getRequest']['_source'];
 ----
 
+
 === Caveats to Future mode
 
-There are a few caveats to using future mode.  The biggest is also the most obvious: you need to deal with resolving the
-future yourself.  This is usually trivial, but can sometimes introduce unexpected complications.
+There are a few caveats to using future mode. The biggest is also the most 
+obvious: you need to deal with resolving the future yourself. This is usually 
+trivial, but can sometimes introduce unexpected complications.
 
-For example, if you resolve manually using `wait()`, you may need to call `wait()` several times if there were retries.
-This is because each retry will introduce another layer of wrapped futures, and each needs to be resolved to get the
-final result.
+For example, if you resolve manually using `wait()`, you may need to call 
+`wait()` several times if there were retries. This is because each retry 
+introduces another layer of wrapped futures, and each needs to be resolved to 
+get the final result.
 
-This is not needed if you access values via the ArrayInterface however (e.g. `$response['hits']['hits']`), since
-FutureArrayInterface will automatically and fully resolve the future to provide values.
+However, this is not needed if you access values via the ArrayInterface (for 
+example, `$response['hits']['hits']`) since FutureArrayInterface automatically 
+and fully resolves the future to provide values.
 
-Another caveat is that certain APIs will lose their "helper" functionality.  For example, "exists" APIs (e.g.
-`$client->exists()`, `$client->indices()->exists`, `$client->indices->templateExists()`, etc) typically return a true
-or false under normal operation.
+Another caveat is that certain APIs will lose their "helper" functionality. For 
+example, "exists" APIs (`$client->exists()`, `$client->indices()->exists`, 
+`$client->indices->templateExists()`, and so on) typically return a true or 
+false under normal operation.
 
-When operated in future mode, unwrapping of the future is left to your application,
-which means the client can no longer inspect the response and return a simple true/false.  Instead, you'll see the raw
-response from Elasticsearch and will have to take action appropriately.
+When operated in future mode, the unwrapping of the future is left to your 
+application, which means the client can no longer inspect the response and 
+return a simple true/false. Instead, you'll see the raw response from {es} and 
+will have to take action appropriately.
 
 This also applies to `ping()`.