init: import production code mss.nahaichuan.com (exclude Runtime/Uploads/backups/logs)
这个提交包含在:
183
vendor/guzzlehttp/guzzle/docs/batching/batching.rst
vendored
可执行文件
183
vendor/guzzlehttp/guzzle/docs/batching/batching.rst
vendored
可执行文件
@@ -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()``
|
||||
在新工单中引用
屏蔽一个用户