first commit

modules/inpostshipping/vendor/guzzlehttp/ringphp/docs/futures.rst

@@ -0,0 +1,164 @@
+=======
+Futures
+=======
+
+Futures represent a computation that may have not yet completed. RingPHP
+uses hybrid of futures and promises to provide a consistent API that can be
+used for both blocking and non-blocking consumers.
+
+Promises
+--------
+
+You can get the result of a future when it is ready using the promise interface
+of a future. Futures expose a promise API via a ``then()`` method that utilizes
+`React's promise library <https://github.com/reactphp/promise>`_. You should
+use this API when you do not wish to block.
+
+.. code-block:: php
+
+    use GuzzleHttp\Ring\Client\CurlMultiHandler;
+
+    $request = [
+        'http_method' => 'GET',
+        'uri'         => '/',
+        'headers'     => ['host' => ['httpbin.org']]
+    ];
+
+    $response = $handler($request);
+
+    // Use the then() method to use the promise API of the future.
+    $response->then(function ($response) {
+        echo $response['status'];
+    });
+
+You can get the promise used by a future, an instance of
+``React\Promise\PromiseInterface``, by calling the ``promise()`` method.
+
+.. code-block:: php
+
+    $response = $handler($request);
+    $promise = $response->promise();
+    $promise->then(function ($response) {
+        echo $response['status'];
+    });
+
+This promise value can be used with React's
+`aggregate promise functions <https://github.com/reactphp/promise#functions>`_.
+
+Waiting
+-------
+
+You can wait on a future to complete and retrieve the value, or *dereference*
+the future, using the ``wait()`` method. Calling the ``wait()`` method of a
+future will block until the result is available. The result is then returned or
+an exception is thrown if and exception was encountered while waiting on the
+the result. Subsequent calls to dereference a future will return the previously
+completed result or throw the previously encountered exception. Futures can be
+cancelled, which stops the computation if possible.
+
+.. code-block:: php
+
+    use GuzzleHttp\Ring\Client\CurlMultiHandler;
+
+    $response = $handler([
+        'http_method' => 'GET',
+        'uri'         => '/',
+        'headers'     => ['host' => ['httpbin.org']]
+    ]);
+
+    // You can explicitly call block to wait on a result.
+    $realizedResponse = $response->wait();
+
+    // Future responses can be used like a regular PHP array.
+    echo $response['status'];
+
+In addition to explicitly calling the ``wait()`` function, using a future like
+a normal value will implicitly trigger the ``wait()`` function.
+
+Future Responses
+----------------
+
+RingPHP uses futures to return asynchronous responses immediately. Client
+handlers always return future responses that implement
+``GuzzleHttp\Ring\Future\ArrayFutureInterface``. These future responses act
+just like normal PHP associative arrays for blocking access and provide a
+promise interface for non-blocking access.
+
+.. code-block:: php
+
+    use GuzzleHttp\Ring\Client\CurlMultiHandler;
+
+    $handler = new CurlMultiHandler();
+
+    $request = [
+        'http_method'  => 'GET',
+        'uri'          => '/',
+        'headers'      => ['Host' => ['www.google.com']]
+    ];
+
+    $response = $handler($request);
+
+    // Use the promise API for non-blocking access to the response. The actual
+    // response value will be delivered to the promise.
+    $response->then(function ($response) {
+        echo $response['status'];
+    });
+
+    // You can wait (block) until the future is completed.
+    $response->wait();
+
+    // This will implicitly call wait(), and will block too!
+    $response['status'];
+
+.. important::
+
+    Futures that are not completed by the time the underlying handler is
+    destructed will be completed when the handler is shutting down.
+
+Cancelling
+----------
+
+Futures can be cancelled if they have not already been dereferenced.
+
+RingPHP futures are typically implemented with the
+``GuzzleHttp\Ring\Future\BaseFutureTrait``. This trait provides the cancellation
+functionality that should be common to most implementations. Cancelling a
+future response will try to prevent the request from sending over the wire.
+
+When a future is cancelled, the cancellation function is invoked and performs
+the actual work needed to cancel the request from sending if possible
+(e.g., telling an event loop to stop sending a request or to close a socket).
+If no cancellation function is provided, then a request cannot be cancelled. If
+a cancel function is provided, then it should accept the future as an argument
+and return true if the future was successfully cancelled or false if it could
+not be cancelled.
+
+Wrapping an existing Promise
+----------------------------
+
+You can easily create a future from any existing promise using the
+``GuzzleHttp\Ring\Future\FutureValue`` class. This class's constructor
+accepts a promise as the first argument, a wait function as the second
+argument, and a cancellation function as the third argument. The dereference
+function is used to force the promise to resolve (for example, manually ticking
+an event loop). The cancel function is optional and is used to tell the thing
+that created the promise that it can stop computing the result (for example,
+telling an event loop to stop transferring a request).
+
+.. code-block:: php
+
+    use GuzzleHttp\Ring\Future\FutureValue;
+    use React\Promise\Deferred;
+
+    $deferred = new Deferred();
+    $promise = $deferred->promise();
+
+    $f = new FutureValue(
+        $promise,
+        function () use ($deferred) {
+            // This function is responsible for blocking and resolving the
+            // promise. Here we pass in a reference to the deferred so that
+            // it can be resolved or rejected.
+            $deferred->resolve('foo');
+        }
+    );