Garçons na versão 3 AWS SDK for PHP

Os waiters ajudam a facilitar o trabalho com sistemas eventualmente consistentes fornecendo uma maneira abstraída de esperar até que um recurso entre em um estado específico sondando o recurso. Você pode encontrar uma lista dos garçons atendidos por um cliente visualizando a APIdocumentação de uma única versão de um cliente de serviço. Para navegar até lá, acesse a página do cliente na API documentação e navegue até o número da versão específica (representado por uma data) e role para baixo até a seção “Garçons”. Este link levará você à seção de waiters do S3.

No exemplo a seguir, o cliente do Amazon S3 é usado para criar um bucket. Em seguida, o waiter é usado para aguardar até que o bucket exista.

// Create a bucket
$s3Client->createBucket(['Bucket' => 'amzn-s3-demo-bucket']);

// Wait until the created bucket is available
$s3Client->waitUntil('BucketExists', ['Bucket' => 'amzn-s3-demo-bucket']);

Se o waiter precisar sondar o bucket por um número excessivo de vezes, ele gerará uma exceção \RuntimeException.

Configuração do waiter

Os waiters são acionados por uma matriz associativa de opções de configuração. Todas as opções usadas por um determinado waiter têm valores padrão, mas eles podem ser substituídos para oferecer suporte a diferentes estratégias de espera.

Você pode modificar as opções de configuração do waiter passando uma matriz associativa de opções do @waiter para o argumento $args dos métodos waitUntil() e getWaiter() de um cliente.

// Providing custom waiter configuration options to a waiter
$s3Client->waitUntil('BucketExists', [
    'Bucket'  => 'amzn-s3-demo-bucket',
    '@waiter' => [
        'delay'       => 3,
        'maxAttempts' => 10
    ]
]);

Espera assíncrona

Além da espera de forma síncrona, você pode invocar um waiter para esperar de forma assíncrona enquanto envia outras solicitações ou espera por vários recursos de uma vez.

Você pode acessar uma promessa de waiter recuperando um waiter de um cliente usando o método getWaiter($name, array $args = []) do cliente. Use o método promise() de um waiter para iniciar o waiter. Um promessa de waiter é cumprida com a última Aws\CommandInterface que foi executada no waiter e rejeitada com uma RuntimeException em caso de erro.

use Aws\CommandInterface;

$waiterName = 'BucketExists';
$waiterOptions = ['Bucket' => 'amzn-s3-demo-bucket'];

// Create a waiter promise
$waiter = $s3Client->getWaiter($waiterName, $waiterOptions);

// Initiate the waiter and retrieve a promise
$promise = $waiter->promise();

// Call methods when the promise is resolved.
$promise
    ->then(function () {
        echo "Waiter completed\n";
    })
    ->otherwise(function (\Exception $e) {
        echo "Waiter failed: " . $e . "\n";
    });

// Block until the waiter completes or fails. Note that this might throw
// a \RuntimeException if the waiter fails.
$promise->wait();

Expor garçons baseados em promessas API permite alguns casos de uso poderosos e relativamente baixos. Por exemplo, e se você quisesse esperar por vários recursos, e fazer algo com o primeiro waiter que foi resolvido com êxito?

use Aws\CommandInterface;

// Create an array of waiter promises
$promises = [
    $s3Client->getWaiter('BucketExists', ['Bucket' => 'a'])->promise(),
    $s3Client->getWaiter('BucketExists', ['Bucket' => 'b'])->promise(),
    $s3Client->getWaiter('BucketExists', ['Bucket' => 'c'])->promise()
];

// Initiate a race between the waiters, fulfilling the promise with the
// first waiter to complete (or the first bucket to become available)
$any = Promise\any($promises)
    ->then(function (CommandInterface $command) {
        // This is invoked with the command that succeeded in polling the
        // resource. Here we can know which bucket won the race.
        echo "The {$command['Bucket']} waiter completed first!\n";
    });

// Force the promise to complete
$any->wait();