Update README.md

Author: Eugene Leonovich

README.md

@@ -4,6 +4,10 @@
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/tarantool-php/queue/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/tarantool-php/queue/?branch=master)
 [![Code Coverage](https://scrutinizer-ci.com/g/tarantool-php/queue/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/tarantool-php/queue/?branch=master)
 
+[Tarantool](http://tarantool.org/) is a NoSQL database running in a Lua application server. It integrates
+Lua modules, called [LuaRocks](https://luarocks.org/). This package provides PHP bindings for
+[Tarantool Queue LuaRock](https://github.com/tarantool/queue/blob/master/).
+
 
 ## Installation
 
@@ -14,20 +18,198 @@ $ composer require tarantool/queue
 ```
 
 
-## Usage example
+## Before start
+
+In order to use queue, you first need to make sure that your Tarantool instance
+is configured, up and running. The minimal required configuration might look like this:
+
+```lua
+-- queues.lua
+
+box.cfg {}
+
+queue = require('queue')
+queue.start()
+
+local tube_name = 'foobar'
+if null == queue.tube[tube_name] then
+    queue.create_tube(tube_name, 'fifottl')
+end
+```
+
+> You can read more about the box configuration in the official [Tarantool documentation](http://tarantool.org/doc/book/configuration/index.html#initialization-file).
+> For more information about the queue configuration check out [queue's README](https://github.com/tarantool/queue/blob/master/README.md).
+
+To start the instance you need to copy (or symlink) `queues.lua` file into the `/etc/tarantool/instances.enabled`
+directory and run the following command:
+
+```sh
+$ sudo tarantoolctl start queues
+```
+
+
+## Working with queue
+
+Once you have your instance running, you can start by creating a queue object with the queue (tube) name you defined
+in the Lua script:
 
 ```php
 use Tarantool\Queue\Queue;
 
 $tarantool = new Tarantool();
-$queue = new Queue($tarantool, 'my_queue');
+$queue = new Queue($tarantool, 'foobar');
+```
+
+
+### Data types
+
+Under the hood Tarantool uses [MessagePack](http://msgpack.org/) binary format to serialize/deserialize
+data being stored in a queue. This means that it's safe to use such data types as `null`, `bool`, `int`,
+`float`, `string`, `binary string` and `array` without any manual pre- or post-processing:
+
+```php
+$queue->put('foo');
+$queue->put(true);
+$queue->put(42);
+$queue->put(4.2);
+$queue->put(['foo' => ['bar' => ['baz' => null]]]);
+```
 
-$task = $queue->put('foo');
+
+### Tasks
+
+Almost every method of the [Queue API](src/Queue.php) (except for `kick()` and `statistics()`) returns back
+a lightweight [Task](src/Task.php) object containing the following getters:
+
+```php
+Task::getId()    // The task id
+Task::getState() // The task state (States::READY, States::TAKEN, States::DONE, States::BURY or States::DELAYED)
+Task::getData()  // The task payload
+```
+
+And some sugar methods:
+
+```php
+Task::isReady()
+Task::isTaken()
+Task::isDone()
+Task::isBuried()
+Task::isDelayed()
+```
+
+
+#### Producer API
+
+As you've already seen, to insert a task into a queue you need to call `put()` method, which accepts two arguments:
+the data you want to process and optional array of task options, which this particular queue supports.
+For example, `fifottl` queue (which we defined earlier in our Lua config file), supports `delay`,
+`ttl`, `ttr`, `pri` and `temporary` options:
+
+```php
+$queue->put('foo', ['delay' => 30]);
+$queue->put('bar', ['ttl' => 5]);
+$queue->put('baz', ['ttr' => 10, 'pri' => 42]);
+```
+
+> See the full list of available options [here](https://github.com/tarantool/queue#producer-api).
+
+
+#### Consumer API
+
+To reserve a task for execution, call `take()` method. It accepts an optional `timeout` parameter.
+If a timeout value is supplied the call will wait `timeout` seconds until a `READY` task appears in the queue.
+The method returns either a [Task](#tasks) object or `null`:
+
+```php
+$task = $queue->take();
+
+// wait 2 seconds
+$task = $queue->take(2);
+
+// wait 100 milliseconds
 $task = $queue->take(.1);
+```
 
+After successful execution, a task can be marked as acknowledged (that will also delete the task from a queue):
+
+```php
 $data = $task->getData();
 
-$task = $queue->ack($task->getId());
+// process $data
+
+$this->queue->ack($task->getId());
+```
+
+Or put back into the queue in case it cannot be executed:
+
+```php
+$this->queue->release($task->getId());
+// or
+$this->queue->release($task->getId(), ['delay' => 30]);
+```
+
+To look at a task without changing its state, use:
+
+```php
+$task = $this->queue->peek($task->getId());
+```
+
+To bury (disable) a task:
+
+```php
+$queue->bury($task->getId());
+```
+
+To reset buried task(s) back to `READY` state:
+
+```php
+$count = $queue->kick(3); // kick 3 buried tasks
+```
+
+A task (in any state) can be deleted permanently with `delete()`:
+
+```php
+$this->queue->delete($task->getId());
+```
+
+> For a detailed API documentation, please read [API](https://github.com/tarantool/queue#api)
+section of the [queue's README](https://github.com/tarantool/queue/blob/master/README.md).
+
+
+### Statistics
+
+The `statistics()` method provides access to the statistical information since the creation of a queue:
+
+```php
+$stat = $queue->statistics();
+```
+
+The result of this call might look like this:
+
+```php
+[
+    'tasks' => [
+        'taken'   => 1,
+        'buried'  => 1,
+        'ready'   => 1,
+        'done'    => 0,
+        'delayed' => 0,
+        'total'   => 3,
+    ],
+    'calls' => [
+        'bury' => 1,
+        'put'  => 3,
+        'take' => 1,
+        ...
+    ],
+]
+```
+
+In addition, you can specify a key (or keys) to select only a subset of the resulting array:
+
+```php
+$calls = $queue->statistics('calls');
+$total = $queue->statistics('tasks', 'total');
 ```
 
 
@@ -45,6 +227,8 @@ To run integration tests:
 $ phpunit --testsuite Integration
 ```
 
+> Make sure that the [instance.lua](tests/Integration/instance.lua) instance is up and running.
+
 To run all tests:
 
 ```sh