How to work asynchronous

Asynchronous stuff can be confusing and because of that it is normal to try to stay away from it. But hopefully, using this library will straight forward. The goal is to always be "async first" but developers don't have to care about async if they don't want to.

Normal use cases

Let's show some examples to better understand how this library works.

Ignoring results

Consider the following example:

use AsyncAws\Sqs\SqsClient; use AsyncAws\Sqs\Input\SendMessageRequest; $sqs = new SqsClient(); $input = new SendMessageRequest(); $input ->setQueueUrl('https://sqs.us-east-2.amazonaws.com/123456789012/invoice') ->setMessageBody('invoiceId: 1337'); $sqs->sendMessage($input);

The HTTP request is sent and a HTTP response is received. Everything works as expected.

A small bonus is that the full HTTP response is not downloaded. Only the first line with the status code is fetched from the server.

Getting data from result

The example below is slightly different.

use AsyncAws\Sqs\SqsClient; use AsyncAws\Sqs\Input\SendMessageRequest; $sqs = new SqsClient(); $input = new SendMessageRequest(); $input ->setQueueUrl('https://sqs.us-east-2.amazonaws.com/123456789012/invoice') ->setMessageBody('invoiceId: 1337'); $result = $sqs->sendMessage($input); echo $result->getMessageId();

The HTTP request is not actually sent until the properties on $result are accessed. On the first call to a getter, the HTTP response will be downloaded and the body will be parsed.

This behavior can be observed when using a debugger like xDebug.

Not using the result

Consider this rare scenario:

use AsyncAws\Sqs\SqsClient; use AsyncAws\Sqs\Input\SendMessageRequest; function sendSqsMessage($client) { $input = new SendMessageRequest(); $input ->setQueueUrl('https://sqs.us-east-2.amazonaws.com/123456789012/invoice') ->setMessageBody('invoiceId: 1337'); $result = $client->sendMessage($input); // 100 lines of business logic // No line is using $result } $sqs = new SqsClient(); sendSqsMessage($sqs);

In this example $result is never used. The HTTP request will be sent on $result->__destruct(). But that does not happen until the end of the block, after the 100 lines of business logic. This can be a bit confusing, especially when an exception is thrown.

This scenario can be solved in a few ways. Solution A is the best one to use, but the others are listed as examples.

Solution A

-    $result = $sqs->sendMessage($input);
+    $sqs->sendMessage($input);

Solution B

     $result = $sqs->sendMessage($input);
+    $result->getMessageId();

Solution C

     $result = $sqs->sendMessage($input);
+    unset($result);

Solution D

This solution requires some more explanation. See below for more information.

     $result = $sqs->sendMessage($input);
+    $result->resolve();

Advanced use cases

The normal use cases covers 90% of all code. Let's dig in to the advanced stuff.

Using resolve-function

The $result->resolve() function is making sure the request is executed. There is normally no point in using this function, but in some scenarios it may be handy.

Calling this function with no arguments will either return true or throw an exception. If the function is called again, it will give you the same output without contacting the remote server again.

The function has a ?float $timeout = null argument. If the timeout is set to 2.0, the HTTP client will wait for 2 seconds for a response. If a response is received, the function will return true or throw an exception. If the timeout is reached, it will return false.

Note: The call $result->resolve() is a blocking call because we are waiting for the response. Use $result->resolve(0) for a non-blocking call.

Batch requests

Consider the following example. It is creating 10 Lambda InvocationRequests and printing their result. The HTTP response that is downloaded first will be printed first. The order the requests are created do not matter.

The Result::wait() function will iterate over provided results, and yield the the response as soon as it has been resolved.

The function has a ?float $timeout = null argument. If the timeout is set to 2.0, the HTTP client will wait up to 2 seconds for responses. Each time a response is received, the function will yield the response. If the timeout is reached, or all responses are resolved, the loop will stop.

The function has also a $fullResponse argument. When false (default value) the HTTP client will wait only for HTTP status code and headers. When true, the HTTP client will wait until receiving the full response body.

use AsyncAws\Core\Result; use AsyncAws\Lambda\LambdaClient; use AsyncAws\Lambda\Input\InvocationRequest; $lambda = new LambdaClient(); $results = []; for ($i = 0; $i < 10; ++$i) { $results[] = $lambda->invoke(new InvocationRequest([ 'FunctionName' => 'app-dev-hello_world', 'Payload' => "{\"name\": $i}", ])); } foreach (Result::wait($results, null, true) as $result) { echo $result->getPayload(); }

The pseudo code at the lambda function:

return function ($event) { $rand = rand (1, 4); sleep($rand); return 'Name ' . ($event['name']) . ': ' . $rand . 's'; };

The output will look like:

Name 4: 1s
Name 2: 1s
Name 6: 1s
Name 3: 2s
Name 9: 2s
Name 7: 2s
Name 8: 3s
Name 5: 3s
Name 0: 4s
Name 1: 4s