diff --git a/README.md b/README.md
index e73d7bf..5faf7c1 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ into your traditional, synchronous (blocking) application stack.
 ### Quickstart example
 
 The following example code demonstrates how this library can be used along with
-an [async HTTP client](https://github.com/clue/reactphp-buzz) to process two
+an [async HTTP client](https://github.com/reactphp/http#client-usage) to process two
 non-blocking HTTP requests and block until the first (faster) one resolves.
 
 ```php
@@ -44,7 +44,7 @@ function blockingExample()
     
     // this example uses an HTTP client
     // this could be pretty much everything that binds to an event loop
-    $browser = new Clue\React\Buzz\Browser($loop);
+    $browser = new React\Http\Browser($loop);
     
     // set up two parallel requests
     $request1 = $browser->get('http://www.google.com/');
@@ -128,7 +128,7 @@ will throw an `UnexpectedValueException` instead.
 ```php
 try {
     $result = Block\await($promise, $loop);
-    // promise successfully fulfilled with $value
+    // promise successfully fulfilled with $result
     echo 'Result: ' . $result;
 } catch (Exception $exception) {
     // promise rejected with $exception
@@ -136,6 +136,8 @@ try {
 }
 ```
 
+See also the [examples](examples/).
+
 If no `$timeout` argument is given and the promise stays pending, then this
 will potentially wait/block forever until the promise is settled.
 
@@ -160,6 +162,8 @@ $firstResult = Block\awaitAny($promises, $loop, $timeout);
 echo 'First result: ' . $firstResult;
 ```
 
+See also the [examples](examples/).
+
 This function will only return after ANY of the given `$promises` has been
 fulfilled or will throw when ALL of them have been rejected. In the meantime,
 the event loop will run any events attached to the same loop.
@@ -195,6 +199,8 @@ $allResults = Block\awaitAll($promises, $loop, $timeout);
 echo 'First promise resolved with: ' . $allResults[0];
 ```
 
+See also the [examples](examples/).
+
 This function will only return after ALL of the given `$promises` have been
 fulfilled or will throw when ANY of them have been rejected. In the meantime,
 the event loop will run any events attached to the same loop.
diff --git a/composer.json b/composer.json
index a24bb89..3daaa48 100644
--- a/composer.json
+++ b/composer.json
@@ -23,6 +23,7 @@
         "react/promise-timer": "^1.5"
     },
     "require-dev": {
-        "phpunit/phpunit": "^9.3 || ^5.7 || ^4.8.35"
+        "phpunit/phpunit": "^9.3 || ^5.7 || ^4.8.35",
+        "react/http": "^1.0"
     }
 }
diff --git a/examples/01-await.php b/examples/01-await.php
new file mode 100644
index 0000000..6cd035e
--- /dev/null
+++ b/examples/01-await.php
@@ -0,0 +1,36 @@
+<?php
+
+use Clue\React\Block;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * @param string $url
+ * @return Psr\Http\Message\ResponseInterface
+ * @throws Exception when HTTP request fails
+ */
+function requestHttp($url)
+{
+    // use a unique event loop instance for this operation
+    $loop = React\EventLoop\Factory::create();
+
+    // This example uses an HTTP client
+    $browser = new React\Http\Browser($loop);
+
+    // set up one request
+    $promise = $browser->get($url);
+
+    try {
+        // keep the loop running (i.e. block) until the response arrives
+        $result = Block\await($promise, $loop);
+
+        // promise successfully fulfilled with $result
+        return $result;
+    } catch (Exception $exception) {
+        // promise rejected with $exception
+        throw $exception;
+    }
+}
+
+$response = requestHttp('http://www.google.com/');
+echo $response->getBody();
diff --git a/examples/02-await-any.php b/examples/02-await-any.php
new file mode 100644
index 0000000..2b5d83a
--- /dev/null
+++ b/examples/02-await-any.php
@@ -0,0 +1,40 @@
+<?php
+
+use Clue\React\Block;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * @param string $url1
+ * @param string $url2
+ * @return Psr\Http\Message\ResponseInterface
+ * @throws Exception when HTTP request fails
+ */
+function requestHttpFastestOfMultiple($url1, $url2)
+{
+    // use a unique event loop instance for all parallel operations
+    $loop = React\EventLoop\Factory::create();
+
+    // This example uses an HTTP client
+    $browser = new React\Http\Browser($loop);
+
+    // set up two parallel requests
+    $promises = array(
+        $browser->get($url1),
+        $browser->get($url2)
+    );
+
+    try {
+        // keep the loop running (i.e. block) until the first response arrives
+        $fasterResponse = Block\awaitAny($promises, $loop);
+
+        // promise successfully fulfilled with $fasterResponse
+        return $fasterResponse;
+    } catch (Exception $exception) {
+        // promise rejected with $exception
+        throw $exception;
+    }
+}
+
+$first = requestHttpFastestOfMultiple('http://www.google.com/', 'http://www.google.co.uk/');
+echo $first->getBody();
diff --git a/examples/03-await-all.php b/examples/03-await-all.php
new file mode 100644
index 0000000..b2c470f
--- /dev/null
+++ b/examples/03-await-all.php
@@ -0,0 +1,41 @@
+<?php
+
+use Clue\React\Block;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * @param string $url1
+ * @param string $url2
+ * @return Psr\Http\Message\ResponseInterface[]
+ * @throws Exception when HTTP request fails
+ */
+function requestHttpMultiple($url1, $url2)
+{
+    // use a unique event loop instance for all parallel operations
+    $loop = React\EventLoop\Factory::create();
+
+    // This example uses an HTTP client
+    $browser = new React\Http\Browser($loop);
+
+    // set up two parallel requests
+    $promises = array(
+        $browser->get($url1),
+        $browser->get($url2)
+    );
+
+    try {
+        // keep the loop running (i.e. block) until all responses arrive
+        $allResults = Block\awaitAll($promises, $loop);
+
+        // promise successfully fulfilled with $allResults
+        return $allResults;
+    } catch (Exception $exception) {
+        // promise rejected with $exception
+        throw $exception;
+    }
+}
+
+$all = requestHttpMultiple('http://www.google.com/', 'http://www.google.co.uk/');
+echo 'First promise resolved with: ' . $all[0]->getBody() . PHP_EOL;
+echo 'Second promise resolved with: ' . $all[1]->getBody() . PHP_EOL;
diff --git a/src/functions.php b/src/functions.php
index c871c9c..0fda798 100644
--- a/src/functions.php
+++ b/src/functions.php
@@ -58,7 +58,7 @@ function sleep($time, LoopInterface $loop)
  * ```php
  * try {
  *     $result = Block\await($promise, $loop);
- *     // promise successfully fulfilled with $value
+ *     // promise successfully fulfilled with $result
  *     echo 'Result: ' . $result;
  * } catch (Exception $exception) {
  *     // promise rejected with $exception
@@ -66,6 +66,8 @@ function sleep($time, LoopInterface $loop)
  * }
  * ```
  *
+ * See also the [examples](../examples/).
+ *
  * If no `$timeout` argument is given and the promise stays pending, then this
  * will potentially wait/block forever until the promise is settled.
  *
@@ -143,6 +145,8 @@ function ($error) use (&$exception, &$rejected, &$wait, $loop) {
  * echo 'First result: ' . $firstResult;
  * ```
  *
+ * See also the [examples](../examples/).
+ *
  * This function will only return after ANY of the given `$promises` has been
  * fulfilled or will throw when ALL of them have been rejected. In the meantime,
  * the event loop will run any events attached to the same loop.
@@ -221,6 +225,8 @@ function awaitAny(array $promises, LoopInterface $loop, $timeout = null)
  * echo 'First promise resolved with: ' . $allResults[0];
  * ```
  *
+ * See also the [examples](../examples/).
+ *
  * This function will only return after ALL of the given `$promises` have been
  * fulfilled or will throw when ANY of them have been rejected. In the meantime,
  * the event loop will run any events attached to the same loop.