Refine docs for retryable, TTR and attempts (yiisoft#229)

Author: mikehaertl

docs/guide/retryable.md

@@ -3,15 +3,19 @@ Errors and retryable jobs
 
 The execution of a job can fail. This can be due to internal errors which result from
 poorly written code which should be fixed first. But they can also fail due to external
-problems like a service or a resource being unavailable. This can lead to Exceptions or
+problems like a service or a resource being unavailable. This can lead to exceptions or
 timeouts.
 
 In the latter cases, it's good to be able to retry a job after some time. There are several ways to do this.
 
+> **Note:** The `ttr` feature described below requires the
+> [PHP Process Control (pcntl) extension](http://php.net/manual/en/book.pcntl.php) to be installed
+> and the worker command has to use the `--isolate` option (which is enabled by default).
+
 Retry options
 -------------
 
-The first method is to use component options:
+The first method is to use queue component options:
 
 ```php
 'components' => [
@@ -23,9 +27,19 @@ The first method is to use component options:
 ],
 ```
 
-The `ttr` option sets the time to reserve for job execution. If the execution of a job takes longer than
-this time, execution will be stopped and it will be returned to the queue for later retry. The same happens
-if the job throws an Exception. The `attempts` option sets the max. number of attempts. If this number is
+The `ttr` (Time to reserve, TTR) option defines the number of seconds during which a job must
+be successfully completed. So two things can happen to make a job fail:
+
+ 1. The job throws an exception before `ttr` is over
+ 2. It would take longer than `ttr` to complete the job (timeout) and thus the
+ job execution is stopped by the worker.
+
+In both cases, the job will be sent back to the queue for a retry. Note though,
+that in the first case the `ttr` is still "used up" even if the job stops right
+after it has stared. I.e. the remaining seconds of `ttr` have to pass before the
+job is sent back to the queue.
+
+The `attempts` option sets the max. number of attempts. If this number is
 reached, and the job still isn't done, it will be removed from the queue as completed.
 
 These options apply to all jobs in the queue. If you need to change this behavior for specific
@@ -85,7 +99,7 @@ Yii::$app->queue->on(Queue::EVENT_AFTER_ERROR, function (ErrorEvent $event) {
 });
 ```
 
-Event handlers are executed after `RetryableJobInterface` methods, and therefore have the highest
+Event handlers are executed after the `RetryableJobInterface` methods, and therefore have the highest
 priority.
 
 Restrictions