From 913d0fd6e1ef66e82e0dab7baa1b79630f21f22f Mon Sep 17 00:00:00 2001
From: Johannes Wachter <johannes.wachter@massiveart.com>
Date: Mon, 15 May 2017 13:37:35 +0200
Subject: [PATCH 1/2] added locking section

---
 index.rst   |  1 +
 locking.rst | 37 +++++++++++++++++++++++++++++++++++++
 symfony.rst | 29 ++++++++++++++++++++---------
 3 files changed, 58 insertions(+), 9 deletions(-)
 create mode 100644 locking.rst

diff --git a/index.rst b/index.rst
index d18db4c..e3a989c 100644
--- a/index.rst
+++ b/index.rst
@@ -30,6 +30,7 @@ Contents
     :maxdepth: 2
 
     components
+    locking
     quick-example
     symfony
 
diff --git a/locking.rst b/locking.rst
new file mode 100644
index 0000000..4b1f71a
--- /dev/null
+++ b/locking.rst
@@ -0,0 +1,37 @@
+Locking
+=======
+To avoid concurrency issue the library is able to lock other executions which
+would run at the same time. This could happen if multiple worker (e.g. cronjobs)
+run at the same time.
+
+Each ``TaskHandler`` decides if and how many other Tasks will be blocked while a
+task with this handler is running. If the ``TaskHandler`` implements the
+``LockingTaskHandlerInterface`` the Lock-Component is enabled for this handler.
+The interface consists of a single method ``getLockKey($workload)`` which
+returns a locking-key. Tasks with the same locking-key will not be executed at
+the same time.
+
+Example
+*******
+
+.. code-block:: php
+
+    <?php
+
+    include __DIR__ . '/vendor/autoload.php';
+
+    class ImageResizeHandler implements Task\Lock\LockingTaskHandlerInterface
+    {
+        public function handle($workload)
+        {
+            ...
+        }
+
+        public function getLockKey($workload)
+        {
+            return self::class;
+
+            // or append workload data
+            return self::class . '-' . $workload['id'];
+        }
+    }
diff --git a/symfony.rst b/symfony.rst
index 54b0491..3f2b310 100644
--- a/symfony.rst
+++ b/symfony.rst
@@ -12,6 +12,7 @@ Additional features which are implemented in this bundle.
 * Persist tasks and executions in database
 * Run statistics foreach execution of tasks
 * Predefined system-tasks
+* Locking mechanism to avoid concurrency problems
 
 Installation
 ------------
@@ -54,7 +55,6 @@ tasks.
 
 System-Tasks
 ------------
-
 System-tasks can be used to predefine tasks for deployment. The developer
 can define which handler will be called (with an ``cron_expression`` and
 a ``workload``). This tasks can be scheduled with the following command.
@@ -79,23 +79,34 @@ supported.
 After addition or changing in the config you have to run the command again
 to be sure that the task-table will be updated.
 
+Locking
+-------
+Locking is used to avoid concurrency problems when multiple task-runner runs at
+the same time (see :doc:`locking`). This feature has to be enabled and will have
+multiple different storages in the future.
+
+Currently only file storage is implemented and usable.
+
 Configuration Reference
 -----------------------
 
 .. code-block:: yaml
-
     task:
-        storage:              doctrine # One of "array"; "doctrine"
+        storage:                  doctrine # One of "array"; "doctrine"
         adapters:
             doctrine:
-                clear:                true
+                clear:            true
         run:
             mode:                 'off' # One of "off"; "listener"
-        system_tasks:
-            enabled:              true
-            handler_class:        ~
-            workload:             null
-            cron_expression:      ~
+        locking:
+            enabled:              false
+            storage:              file # One of "file"
+            ttl:                  600
+            storages:
+                file:
+                    directory:    '%kernel.cache_dir%/tasks'
+        mode:                     'off' # One of "off"; "listener"
+
 
 .. _fastcgi_finish_request: http://php.net/manual/en/function.fastcgi-finish-request.php
 .. _PHP FPM: http://php.net/manual/en/install.fpm.php

From f00cedfce9d8e0865d079154c328cb2c5c074927 Mon Sep 17 00:00:00 2001
From: Johannes Wachter <johannes.wachter@massiveart.com>
Date: Tue, 16 May 2017 13:01:28 +0200
Subject: [PATCH 2/2] fixed comments

---
 locking.rst |  4 ++--
 symfony.rst | 11 +++++++++--
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/locking.rst b/locking.rst
index 4b1f71a..68f0974 100644
--- a/locking.rst
+++ b/locking.rst
@@ -1,7 +1,7 @@
 Locking
 =======
-To avoid concurrency issue the library is able to lock other executions which
-would run at the same time. This could happen if multiple worker (e.g. cronjobs)
+To avoid concurrency issues, the library is able to lock other executions which
+would run at the same time. This could happen if multiple workers (e.g. cronjobs)
 run at the same time.
 
 Each ``TaskHandler`` decides if and how many other Tasks will be blocked while a
diff --git a/symfony.rst b/symfony.rst
index 3f2b310..976c7ca 100644
--- a/symfony.rst
+++ b/symfony.rst
@@ -81,7 +81,7 @@ to be sure that the task-table will be updated.
 
 Locking
 -------
-Locking is used to avoid concurrency problems when multiple task-runner runs at
+Locking is used to avoid concurrency problems when multiple task-runners run at
 the same time (see :doc:`locking`). This feature has to be enabled and will have
 multiple different storages in the future.
 
@@ -105,7 +105,14 @@ Configuration Reference
             storages:
                 file:
                     directory:    '%kernel.cache_dir%/tasks'
-        mode:                     'off' # One of "off"; "listener"
+        system_tasks:
+
+            # Prototype
+            -
+                enabled:          true
+                handler_class:    ~
+                workload:         null
+                cron_expression:  ~
 
 
 .. _fastcgi_finish_request: http://php.net/manual/en/function.fastcgi-finish-request.php