Merge pull request #5 from php-task/feature/lock

Added locking section

Author: danrot

index.rst

@@ -30,6 +30,7 @@ Contents
     :maxdepth: 2
 
     components
+    locking
     quick-example
     symfony
 

locking.rst

@@ -0,0 +1,37 @@
+Locking
+=======
+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
+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'];
+        }
+    }

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,41 @@ 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-runners run 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"
+        locking:
+            enabled:              false
+            storage:              file # One of "file"
+            ttl:                  600
+            storages:
+                file:
+                    directory:    '%kernel.cache_dir%/tasks'
         system_tasks:
-            enabled:              true
-            handler_class:        ~
-            workload:             null
-            cron_expression:      ~
+
+            # Prototype
+            -
+                enabled:          true
+                handler_class:    ~
+                workload:         null
+                cron_expression:  ~
+
 
 .. _fastcgi_finish_request: http://php.net/manual/en/function.fastcgi-finish-request.php
 .. _PHP FPM: http://php.net/manual/en/install.fpm.php