summaryrefslogtreecommitdiff
path: root/vendor/guzzle/guzzle/docs/batching/batching.rst
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/guzzle/guzzle/docs/batching/batching.rst')
-rw-r--r--vendor/guzzle/guzzle/docs/batching/batching.rst183
1 files changed, 183 insertions, 0 deletions
diff --git a/vendor/guzzle/guzzle/docs/batching/batching.rst b/vendor/guzzle/guzzle/docs/batching/batching.rst
new file mode 100644
index 0000000..57f04d8
--- /dev/null
+++ b/vendor/guzzle/guzzle/docs/batching/batching.rst
@@ -0,0 +1,183 @@
+========
+Batching
+========
+
+Guzzle provides a fairly generic and very customizable batching framework that allows developers to efficiently
+transfer requests in parallel.
+
+Sending requests and commands in parallel
+-----------------------------------------
+
+You can send HTTP requests in parallel by passing an array of ``Guzzle\Http\Message\RequestInterface`` objects to
+``Guzzle\Http\Client::send()``:
+
+.. code-block:: php
+
+ $responses = $client->send(array(
+ $client->get('http://www.example.com/foo'),
+ $client->get('http://www.example.com/baz')
+ $client->get('http://www.example.com/bar')
+ ));
+
+You can send commands in parallel by passing an array of ``Guzzle\Service\Command\CommandInterface`` objects
+``Guzzle\Service\Client::execute()``:
+
+.. code-block:: php
+
+ $commands = $client->execute(array(
+ $client->getCommand('foo'),
+ $client->getCommand('baz'),
+ $client->getCommand('bar')
+ ));
+
+These approaches work well for most use-cases. When you need more control over the requests that are sent in
+parallel or you need to send a large number of requests, you need to use the functionality provided in the
+``Guzzle\Batch`` namespace.
+
+Batching overview
+-----------------
+
+The batch object, ``Guzzle\Batch\Batch``, is a queue. You add requests to the queue until you are ready to transfer
+all of the requests. In order to efficiently transfer the items in the queue, the batch object delegates the
+responsibility of dividing the queue into manageable parts to a divisor (``Guzzle\Batch\BatchDivisorInterface``).
+The batch object then iterates over each array of items created by the divisor and sends them to the batch object's
+``Guzzle\Batch\BatchTransferInterface``.
+
+.. code-block:: php
+
+ use Guzzle\Batch\Batch;
+ use Guzzle\Http\BatchRequestTransfer;
+
+ // BatchRequestTransfer acts as both the divisor and transfer strategy
+ $transferStrategy = new BatchRequestTransfer(10);
+ $divisorStrategy = $transferStrategy;
+
+ $batch = new Batch($transferStrategy, $divisorStrategy);
+
+ // Add some requests to the batch queue
+ $batch->add($request1)
+ ->add($request2)
+ ->add($request3);
+
+ // Flush the queue and retrieve the flushed items
+ $arrayOfTransferredRequests = $batch->flush();
+
+.. note::
+
+ You might find that your transfer strategy will need to act as both the divisor and transfer strategy.
+
+Using the BatchBuilder
+----------------------
+
+The ``Guzzle\Batch\BatchBuilder`` makes it easier to create batch objects. The batch builder also provides an easier
+way to add additional behaviors to your batch object.
+
+Transferring requests
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``Guzzle\Http\BatchRequestTransfer`` class efficiently transfers HTTP requests in parallel by grouping batches of
+requests by the curl_multi handle that is used to transfer the requests.
+
+.. code-block:: php
+
+ use Guzzle\Batch\BatchBuilder;
+
+ $batch = BatchBuilder::factory()
+ ->transferRequests(10)
+ ->build();
+
+Transferring commands
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``Guzzle\Service\Command\BatchCommandTransfer`` class efficiently transfers service commands by grouping commands
+by the client that is used to transfer them. You can add commands to a batch object that are transferred by different
+clients, and the batch will handle the rest.
+
+.. code-block:: php
+
+ use Guzzle\Batch\BatchBuilder;
+
+ $batch = BatchBuilder::factory()
+ ->transferCommands(10)
+ ->build();
+
+ $batch->add($client->getCommand('foo'))
+ ->add($client->getCommand('baz'))
+ ->add($client->getCommand('bar'));
+
+ $commands = $batch->flush();
+
+Batch behaviors
+---------------
+
+You can add various behaviors to your batch that allow for more customizable transfers.
+
+Automatically flushing a queue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the ``Guzzle\Batch\FlushingBatch`` decorator when you want to pump a large number of items into a batch queue and
+have the queue automatically flush when the size of the queue reaches a certain threshold.
+
+.. code-block:: php
+
+ use Guzzle\Batch\BatchBuilder;
+
+ $batch = BatchBuilder::factory()
+ ->transferRequests(10)
+ ->autoFlushAt(10)
+ ->build();
+
+Batch builder method: ``autoFlushAt($threshold)``
+
+Notifying on flush
+~~~~~~~~~~~~~~~~~~
+
+Use the ``Guzzle\Batch\NotifyingBatch`` decorator if you want a function to be notified each time the batch queue is
+flushed. This is useful when paired with the flushing batch decorator. Pass a callable to the ``notify()`` method of
+a batch builder to use this decorator with the builder.
+
+.. code-block:: php
+
+ use Guzzle\Batch\BatchBuilder;
+
+ $batch = BatchBuilder::factory()
+ ->transferRequests(10)
+ ->autoFlushAt(10)
+ ->notify(function (array $transferredItems) {
+ echo 'Transferred ' . count($transferredItems) . "items\n";
+ })
+ ->build();
+
+Batch builder method:: ``notify(callable $callback)``
+
+Keeping a history
+~~~~~~~~~~~~~~~~~
+
+Use the ``Guzzle\Batch\HistoryBatch`` decorator if you want to maintain a history of all the items transferred with
+the batch queue.
+
+.. code-block:: php
+
+ use Guzzle\Batch\BatchBuilder;
+
+ $batch = BatchBuilder::factory()
+ ->transferRequests(10)
+ ->keepHistory()
+ ->build();
+
+After transferring items, you can use the ``getHistory()`` of a batch to retrieve an array of transferred items. Be
+sure to periodically clear the history using ``clearHistory()``.
+
+Batch builder method: ``keepHistory()``
+
+Exception buffering
+~~~~~~~~~~~~~~~~~~~
+
+Use the ``Guzzle\Batch\ExceptionBufferingBatch`` decorator to buffer exceptions during a transfer so that you can
+transfer as many items as possible then deal with the errored batches after the transfer completes. After transfer,
+use the ``getExceptions()`` method of a batch to retrieve an array of
+``Guzzle\Batch\Exception\BatchTransferException`` objects. You can use these exceptions to attempt to retry the
+failed batches. Be sure to clear the buffered exceptions when you are done with them by using the
+``clearExceptions()`` method.
+
+Batch builder method: ``bufferExceptions()``