Redis BRPOP Command Explained

In Redis, the BRPOP command is the blocking variant of the RPOP command. It blocks the connection when there are no elements to pop from any of the given lists.

The way the command works is that an element is popped from the tail of the first list that is non-empty, with the given keys being checked in the order that they are given. When there are no elements to pop from any of the lists, it blocks the connection.

Although BRPOP is considered the blocking variant of RPOP, the two commands actually accept different arguments and function slightly differently. As of this writing, BRPOP accepts multiple keys, whereas RPOP doesn’t. Also, RPOP allows us to specify how many list elements to pop whereas PRPOP doesn’t.

Syntax

The syntax for BRPOP goes like this:

BRPOP key [key ...] timeout

When a non-zero timeout is specified, the client will unblock returning a nil multi-bulk value when the specified timeout has expired without a push operation against at least one of the specified keys.

Prior to Redis 6.0.0 timeout was interpreted as an integer. However, from 6.0.0 timeout is interpreted as a double.

Example

Suppose we create a list like this:

RPUSH scores 1 2 3 4 5 6 7 8 9 10

Result:

(integer) 10

Let’s look at its contents:

LRANGE scores 0 -1

Result:

 1) "1"
 2) "2"
 3) "3"
 4) "4"
 5) "5"
 6) "6"
 7) "7"
 8) "8"
 9) "9"
10) "10"

We can use BRPOP to pop the last element like this:

BRPOP scores 0

Result:

1) "scores"
2) "10"

The first value returned is the key, and the second is the value of the element that was popped. In this case I specified a timeout of zero, which is used to block indefinitely. A value was popped however, and so the connection wasn’t blocked.

Now when we return all elements in the list, we see that the last element is no longer there:

LRANGE scores 0 -1

Result:

1) "1"
2) "2"
3) "3"
4) "4"
5) "5"
6) "6"
7) "7"
8) "8"
9) "9"

Multiple Lists

We can specify multiple lists. As mentioned, BRPOP pops the element from the head of the first list that is non-empty list:

BRPOP emptylist scores 0

Result:

1) "scores"
2) "9"

In this case, the emptylist key is an empty list, and so the operation was performed on the scores key.

Wrong Type

If the key is the wrong type, an error is returned:

BRPOP customer 0

Result:

(error) WRONGTYPE Operation against a key holding the wrong kind of value

We can use the TYPE command to check the key’s type:

TYPE customer

Result:

hash

In this case it’s a hash.

Non-Existent Key

If the key doesn’t exist, nil is returned after the timeout period has elapsed:

BRPOP nonexistentkey 7

Result:

(nil)
(7.07s)

When I ran that example in my Redis client, there was a seven second pause before the result was returned.

More Information

For more information, see the Redis documentation for the BRPOP command. Also see the Redis documentation for the BLPOP command (that page contains more detail that’s applicable to both commands).