minor #14435 [RateLimiter] Document reserve() method and rename to RateLimiter (wouterj)

This PR was merged into the 5.x branch.

Discussion
----------

[RateLimiter] Document reserve() method and rename to RateLimiter

Fixes #14426

After the first round of documentation, the component has had some tweaks to improve usage. This PR updates the docs to be in sync with the current state of the component.

Commits
-------

72ff903 Document reserve() method and rename to RateLimiter

Author: javiereguiluz

rate_limiter.rst

@@ -124,12 +124,13 @@ the number of requests to the API::
 
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
-    use Symfony\Component\RateLimiter\Limiter;
+    use Symfony\Component\RateLimiter\RateLimiter;
 
     class ApiController extends AbstractController
     {
         // the variable name must be: "rate limiter name" + "limiter" suffix
-        public function index(Limiter $anonymousApiLimiter)
+        // if you're using autowiring for your services
+        public function index(RateLimiter $anonymousApiLimiter)
         {
             // create a limiter based on a unique identifier of the client
             // (e.g. the client's IP address, a username/email, an API key, etc.)
@@ -158,35 +159,59 @@ the number of requests to the API::
     for the :ref:`kernel.request event <component-http-kernel-kernel-request>`
     and check the rate limiter once for all requests.
 
-In other scenarios you may want instead to wait as long as needed until a new
-token is available. In those cases, use the ``wait()`` method::
+Wait until a Token is Available
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of dropping a request or process when the limit has been reached,
+you might want to wait until a new token is available. This can be achieved
+using the ``reserve()`` method::
 
     // src/Controller/ApiController.php
     namespace App\Controller;
 
     use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\HttpFoundation\Request;
-    use Symfony\Component\RateLimiter\Limiter;
+    use Symfony\Component\RateLimiter\RateLimiter;
 
     class ApiController extends AbstractController
     {
-        public function registerUser(Request $request, Limiter $authenticatedApiLimiter)
+        public function registerUser(Request $request, RateLimiter $authenticatedApiLimiter)
         {
             $apiKey = $request->headers->get('apikey');
             $limiter = $authenticatedApiLimiter->create($apiKey);
 
             // this blocks the application until the given number of tokens can be consumed
-            do {
-                $limit = $limiter->consume(1);
-                $limit->wait();
-            } while (!$limit->isAccepted());
+            $limiter->reserve(1)->wait();
+
+            // optional, pass a maximum wait time (in seconds), a MaxWaitDurationExceededException
+            // is thrown if the process has to wait longer. E.g. to wait at most 20 seconds:
+            //$limiter->reserve(1, 20)->wait();
 
             // ...
         }
 
         // ...
     }
 
+The ``reserve()`` method is able to reserve a token in the future. Only use
+this method if you're planning to wait, otherwise you will block other
+processes by reserving unused tokens.
+
+.. note::
+
+    Not all strategies allow reservering tokens in the future. These
+    strategies may throw an ``ReserveNotSupportedException`` when calling
+    ``reserve()``.
+
+    In these cases, you can use ``consume()`` together with ``wait()``, but
+    there is no guarantee that a token is available after the wait::
+
+        // ...
+        do {
+            $limit = $limiter->consume(1);
+            $limit->wait();
+        } while (!$limit->isAccepted());
+
 Rate Limiter Storage and Locking
 --------------------------------