Add documentation about serializing lock

Author: jderusse

components/lock.rst

@@ -68,6 +68,33 @@ 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``.
 
+Serializing Locks
+------------------
+
+The ``Key`` contains the state of the ``Lock`` and can be serialized. This
+allows the user to begin a long job in a process by acquiring the lock, and
+to continue the job in an other process within the same lock.::
+
+    use Symfony\Component\Lock\Key;
+    use Symfony\Component\Lock\Lock;
+
+    $key = new Key('article.'.$article->getId());
+    $lock = new Lock($key, $this->store, 300, false);
+    $lock->acquire(true);
+
+    $this->bus->dispatch(new RefreshTaxonomy($article, $key));
+
+.. note::
+
+    Don't forget to disable the autoRelease to avoid releasing the lock when
+    the destructor will be called.
+
+All stores are not compatible with serialization and cross-process locking:
+For instance the kernel will automatically releases Semaphores acquires by the
+:ref:`SemaphoreStore <lock-store-semaphore>` store.
+Wen a lock is acquired with such store, and hte application try to serialize
+the key, and exception will be thrown
+
 .. _lock-blocking-locks:
 
 Blocking Locks
@@ -286,17 +313,17 @@ Locks are created and managed in ``Stores``, which are classes that implement
 
 The component includes the following built-in store types:
 
-============================================  ======  ========  ======== =======
-Store                                         Scope   Blocking  Expiring Sharing
-============================================  ======  ========  ======== =======
-:ref:`FlockStore <lock-store-flock>`          local   yes       no       yes
-:ref:`MemcachedStore <lock-store-memcached>`  remote  no        yes      no
-:ref:`MongoDbStore <lock-store-mongodb>`      remote  no        yes      no
-:ref:`PdoStore <lock-store-pdo>`              remote  no        yes      no
-:ref:`RedisStore <lock-store-redis>`          remote  no        yes      yes
-:ref:`SemaphoreStore <lock-store-semaphore>`  local   yes       no       no
-:ref:`ZookeeperStore <lock-store-zookeeper>`  remote  no        no       no
-============================================  ======  ========  ======== =======
+============================================  ======  =========  ========  ======== =======
+Store                                         Scope   Serialize  Blocking  Expiring Sharing
+============================================  ======  =========  ========  ======== =======
+:ref:`FlockStore <lock-store-flock>`          local   no         yes       no       yes
+:ref:`MemcachedStore <lock-store-memcached>`  remote  yes        no        yes      no
+:ref:`MongoDbStore <lock-store-mongodb>`      remote  yes        no        yes      no
+:ref:`PdoStore <lock-store-pdo>`              remote  yes        no        yes      no
+:ref:`RedisStore <lock-store-redis>`          remote  yes        no        yes      yes
+:ref:`SemaphoreStore <lock-store-semaphore>`  local   no         yes       no       no
+:ref:`ZookeeperStore <lock-store-zookeeper>`  remote  no         no        no       no
+============================================  ======  =========  ========  ======== =======
 
 .. _lock-store-flock: