diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2020-03-21 10:28:17 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2021-02-07 11:16:53 +0000 |
commit | 06cba6ccd165ca8b224797e37fccb9e63f026d77 (patch) | |
tree | e82f1bc439997ae296f2e74f8a64d84c5d95f140 /iredis/data/commands/client-unblock.md | |
parent | Initial commit. (diff) | |
download | iredis-06cba6ccd165ca8b224797e37fccb9e63f026d77.tar.xz iredis-06cba6ccd165ca8b224797e37fccb9e63f026d77.zip |
Adding upstream version 1.9.1.upstream/1.9.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'iredis/data/commands/client-unblock.md')
-rw-r--r-- | iredis/data/commands/client-unblock.md | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/iredis/data/commands/client-unblock.md b/iredis/data/commands/client-unblock.md new file mode 100644 index 0000000..dae5fb3 --- /dev/null +++ b/iredis/data/commands/client-unblock.md @@ -0,0 +1,63 @@ +This command can unblock, from a different connection, a client blocked in a +blocking operation, such as for instance `BRPOP` or `XREAD` or `WAIT`. + +By default the client is unblocked as if the timeout of the command was reached, +however if an additional (and optional) argument is passed, it is possible to +specify the unblocking behavior, that can be **TIMEOUT** (the default) or +**ERROR**. If **ERROR** is specified, the behavior is to unblock the client +returning as error the fact that the client was force-unblocked. Specifically +the client will receive the following error: + + -UNBLOCKED client unblocked via CLIENT UNBLOCK + +Note: of course as usually it is not guaranteed that the error text remains the +same, however the error code will remain `-UNBLOCKED`. + +This command is useful especially when we are monitoring many keys with a +limited number of connections. For instance we may want to monitor multiple +streams with `XREAD` without using more than N connections. However at some +point the consumer process is informed that there is one more stream key to +monitor. In order to avoid using more connections, the best behavior would be to +stop the blocking command from one of the connections in the pool, add the new +key, and issue the blocking command again. + +To obtain this behavior the following pattern is used. The process uses an +additional _control connection_ in order to send the `CLIENT UNBLOCK` command if +needed. In the meantime, before running the blocking operation on the other +connections, the process runs `CLIENT ID` in order to get the ID associated with +that connection. When a new key should be added, or when a key should no longer +be monitored, the relevant connection blocking command is aborted by sending +`CLIENT UNBLOCK` in the control connection. The blocking command will return and +can be finally reissued. + +This example shows the application in the context of Redis streams, however the +pattern is a general one and can be applied to other cases. + +@example + +``` +Connection A (blocking connection): +> CLIENT ID +2934 +> BRPOP key1 key2 key3 0 +(client is blocked) + +... Now we want to add a new key ... + +Connection B (control connection): +> CLIENT UNBLOCK 2934 +1 + +Connection A (blocking connection): +... BRPOP reply with timeout ... +NULL +> BRPOP key1 key2 key3 key4 0 +(client is blocked again) +``` + +@return + +@integer-reply, specifically: + +- `1` if the client was unblocked successfully. +- `0` if the client wasn't unblocked. |