From d0161b468386be35db3947fba83961300ca75161 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Berislav=20Balogovi=C4=87?=
 <berislav.balogovic@trikoder.net>
Date: Mon, 22 Apr 2019 22:20:01 +0200
Subject: [PATCH] Extend framework lock configuration reference

---
 components/lock.rst                   |   2 +
 reference/configuration/framework.rst | 132 +++++++++++++++++++++++++-
 2 files changed, 132 insertions(+), 2 deletions(-)

diff --git a/components/lock.rst b/components/lock.rst
index 529696e082c..08c5177dfa0 100644
--- a/components/lock.rst
+++ b/components/lock.rst
@@ -69,6 +69,8 @@ method can be safely called repeatedly, even if the lock is already acquired.
     across several requests. To disable the automatic release behavior, set the
     third argument of the ``createLock()`` method to ``false``.
 
+.. _lock-blocking-locks:
+
 Blocking Locks
 --------------
 
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
index de74aedfc8c..60fadc0b0d8 100644
--- a/reference/configuration/framework.rst
+++ b/reference/configuration/framework.rst
@@ -87,6 +87,12 @@ Configuration
 * `http_method_override`_
 * `ide`_
 * :ref:`lock <reference-lock>`
+
+  * :ref:`enabled <reference-lock-enabled>`
+  * :ref:`resources <reference-lock-resources>`
+
+    * :ref:`name <reference-lock-resources-name>`
+
 * `php_errors`_
 
   * `log`_
@@ -164,7 +170,7 @@ Configuration
   * `engines`_
   * :ref:`form <reference-templating-form>`
 
-    * `resources`_
+    * :ref:`resources <reference-templating-form-resources>`
 
   * `hinclude_default_template`_
   * `loaders`_
@@ -1518,6 +1524,8 @@ is disabled. This can be either a template name or the content itself.
 form
 ....
 
+.. _reference-templating-form-resources:
+
 resources
 """""""""
 
@@ -2175,11 +2183,131 @@ example, when warming caches offline).
 lock
 ~~~~
 
-**type**: ``string``
+**type**: ``string`` | ``array``
 
 The default lock adapter. If not defined, the value is set to ``semaphore`` when
 available, or to ``flock`` otherwise. Store's DSN are also allowed.
 
+.. _reference-lock-enabled:
+
+enabled
+.......
+
+**type**: ``boolean`` **default**: ``true``
+
+Whether to enable the support for lock or not. This setting is
+automatically set to ``true`` when one of the child settings is configured.
+
+.. _reference-lock-resources:
+
+resources
+.........
+
+**type**: ``array``
+
+A list of lock stores to be created by the framework extension.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            # these are all the supported lock stores
+            lock: ~
+            lock: 'flock'
+            lock: 'semaphore'
+            lock: 'memcached://m1.docker'
+            lock: ['memcached://m1.docker', 'memcached://m2.docker']
+            lock: 'redis://r1.docker'
+            lock: ['redis://r1.docker', 'redis://r2.docker']
+            lock: '%env(MEMCACHED_OR_REDIS_URL)%'
+
+            # named locks
+            lock:
+                invoice: ['redis://r1.docker', 'redis://r2.docker']
+                report: 'semaphore'
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:lock>
+                    <!-- these are all the supported lock stores -->
+                    <framework:resource>flock</framework:resource>
+
+                    <framework:resource>semaphore</framework:resource>
+
+                    <framework:resource>memcached://m1.docker</framework:resource>
+
+                    <framework:resource>memcached://m1.docker</framework:resource>
+                    <framework:resource>memcached://m2.docker</framework:resource>
+
+                    <framework:resource>redis://r1.docker</framework:resource>
+
+                    <framework:resource>redis://r1.docker</framework:resource>
+                    <framework:resource>redis://r2.docker</framework:resource>
+
+                    <framework:resource>%env(REDIS_URL)%</framework:resource>
+
+                    <!-- named locks -->
+                    <framework:resource name="invoice">redis://r1.docker</framework:resource>
+                    <framework:resource name="invoice">redis://r2.docker</framework:resource>
+                    <framework:resource name="report">semaphore</framework:resource>
+                </framework:lock>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', [
+            // these are all the supported lock stores
+            'lock' => null,
+            'lock' => 'flock',
+            'lock' => 'semaphore',
+            'lock' => 'memcached://m1.docker',
+            'lock' => ['memcached://m1.docker', 'memcached://m2.docker'],
+            'lock' => 'redis://r1.docker',
+            'lock' => ['redis://r1.docker', 'redis://r2.docker'],
+            'lock' => '%env(MEMCACHED_OR_REDIS_URL)%',
+
+            // named locks
+            'lock' => [
+                'invoice' => ['redis://r1.docker', 'redis://r2.docker'],
+                'report' => 'semaphore',
+            ],
+        ]);
+
+.. _reference-lock-resources-name:
+
+name
+""""
+
+**type**: ``prototype``
+
+Name of the lock you want to create.
+
+.. tip::
+
+    If you want to use the `RetryTillSaveStore` for :ref:`non-blocking locks <lock-blocking-locks>`,
+    you can do it by :doc:`decorating the store </service_container/service_decoration>` service:
+
+    .. code-block:: yaml
+
+        lock.invoice.retry_till_save.store:
+            class: Symfony\Component\Lock\Store\RetryTillSaveStore
+            decorates: lock.invoice.store
+            arguments: ['@lock.invoice.retry.till.save.store.inner', 100, 50]
+
 workflows
 ~~~~~~~~~