Skip to content

Commit 373139c

Browse files
committed
documentation: add description of the session identification
Follows up #85
1 parent 062dae1 commit 373139c

File tree

1 file changed

+32
-0
lines changed

1 file changed

+32
-0
lines changed

README.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ align="right">
2626
* [Initialization](#initialization)
2727
* [Creating a new queue](#creating-a-new-queue)
2828
* [Set queue settings](#set-queue-settings)
29+
* [Session identification](#session-identification)
2930
* [Putting a task in a queue](#putting-a-task-in-a-queue)
3031
* [Taking a task from the queue ("consuming")](#taking-a-task-from-the-queue-consuming)
3132
* [Acknowledging the completion of a task](#acknowledging-the-completion-of-a-task)
@@ -372,6 +373,37 @@ Available `options`:
372373
* `ttr` - time to release in seconds. The time after which, if there is no active
373374
connection in the session, it will be released with all its tasks.
374375

376+
## Session identify
377+
378+
```lua
379+
queue.identify(session_uuid)
380+
```
381+
382+
In the queue the session has a unique UUID and many connections may share one
383+
logical session. Also, the consumer can reconnect to the existing session during
384+
the`ttr` time.
385+
To get the UUID of the current session, call the `queue.identify()`
386+
without parameters.
387+
To connect to the existing session, call the `queue.identify(session_uuid)`
388+
with the UUID of the session.
389+
In case of attempt to use an invalid format UUID or expired UUID, an error will
390+
be thrown.
391+
392+
Usage example:
393+
Sometimes we need an ability to acknowledge a task after reconnect (because
394+
retrying it is undesirable) or even acknowlegde using another connection.
395+
396+
Example of code for connecting to the old session in case of reconnection:
397+
```
398+
local netbox = require('net.box')
399+
400+
local conn = netbox.connect('localhost:1918', { reconnect_after = 5 })
401+
local session_uuid = conn:call('queue.identify')
402+
conn:on_connect(function()
403+
conn:call('queue.identify', {session_uuid})
404+
end)
405+
```
406+
375407
## Putting a task in a queue
376408

377409
To insert a new task into a queue, use:

0 commit comments

Comments
 (0)