From 563206fc4ee10ece5b3808de156dbc37dd26c3c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Pineau?= <lyrixx@lyrixx.info>
Date: Fri, 28 Aug 2020 16:08:30 +0200
Subject: [PATCH] [Sempahore] Added first round of documentation

---
 components/semaphore.rst | 79 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 components/semaphore.rst

diff --git a/components/semaphore.rst b/components/semaphore.rst
new file mode 100644
index 00000000000..4677b0627ba
--- /dev/null
+++ b/components/semaphore.rst
@@ -0,0 +1,79 @@
+.. index::
+   single: Semaphore
+   single: Components; Semaphore
+
+The Semaphore Component
+=======================
+
+    The Semaphore Component manages `semaphores`_, a mechanism to provide
+    exclusive access to a shared resource.
+
+.. versionadded:: 5.2
+
+    The Semaphore Component was introduced in Symfony 5.2.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/semaphore
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+Semaphore are used to guarantee exclusive access to some shared resource.
+
+Semaphore are created using a :class:`Symfony\\Component\\Semaphore\\SemaphoreFactory` class,
+which in turn requires another class to manage the storage of Semaphore::
+
+    use Symfony\Component\Semaphore\SemaphoreFactory;
+    use Symfony\Component\Semaphore\Store\RedisStore;
+
+    $redis = new Redis();
+    $redis->connect('172.17.0.2');
+
+    $store = new RedisStore($redis);
+    $factory = new SemaphoreFactory($store);
+
+
+The semaphore is created by calling the
+:method:`Symfony\\Component\\Semaphore\\SemaphoreFactory::createSemaphore`
+method. Its first argument is an arbitrary string that represents the locked
+resource. Its second argument is the number of process allowed. Then, a call to
+the :method:`Symfony\\Component\\Semaphore\\SemaphoreInterface::acquire` method
+will try to acquire the semaphore::
+
+    // ...
+    $semaphore = $factory->createSemaphore('pdf-invoice-generation', 2);
+
+    if ($semaphore->acquire()) {
+        // The resource "pdf-invoice-generation" is locked.
+        // You can compute and generate invoice safely here.
+
+        $semaphore->release();
+    }
+
+If the semaphore can not be acquired, the method returns ``false``. The
+``acquire()`` method can be safely called repeatedly, even if the semaphore is
+already acquired.
+
+.. note::
+
+    Unlike other implementations, the Semaphore Component distinguishes
+    semaphores instances even when they are created for the same resource. If a
+    semaphore has to be used by several services, they should share the same
+    ``Semaphore`` instance returned by the ``SemaphoreFactory::createSemaphore``
+    method.
+
+.. tip::
+
+    If you don't release the semaphore explicitly, it will be released
+    automatically on instance destruction. In some cases, it can be useful to
+    lock a resource across several requests. To disable the automatic release
+    behavior, set the last argument of the ``createLock()`` method to
+    ``false``.
+
+.. _`semaphores`: https://en.wikipedia.org/wiki/Semaphore_(programming)