Merge pull request #2760 from dsantang/document-retryable-transactional-errors

Add documentation regarding transactional exceptions

docs/en/reference/transactions.rst

@@ -235,3 +235,32 @@ To initialize a ``Doctrine\DBAL\Connection`` with auto-commit disabled,
 you can also use the ``Doctrine\DBAL\Configuration`` container to modify the
 default auto-commit mode via ``Doctrine\DBAL\Configuration::setAutoCommit(false)``
 and pass it to a ``Doctrine\DBAL\Connection`` when instantiating.
+
+
+Error handling
+--------------
+
+In order to handle errors related to deadlocks or lock wait timeouts,
+you can use Doctrine built-in transaction exceptions.
+All transaction exceptions have a marker interface: ``Doctrine/DBAL/Exception/RetryableException``.
+A practical example is as follows:
+
+::
+
+    <?php
+
+    try {
+        // process stuff
+    } catch (\Doctrine/DBAL/Exception/RetryableException $e) {
+        // retry the processing
+    }
+
+
+If you need stricter control, you can catch the concrete exceptions directly:
+
+- ``Doctrine/DBAL/Exception/DeadlockException``: this can happen when each member
+of a group of actions is waiting for some other member to release a shared lock.
+- ``Doctrine/DBAL/Exception/LockWaitTimeoutException``: this exception happens when 
+a transaction have to wait a considerable amount of time to obtain a lock, even if a deadlock
+is not involved. 
+