106 lines
2.8 KiB
Plaintext
106 lines
2.8 KiB
Plaintext
Jim redis extension documentation.
|
|
|
|
Overview
|
|
~~~~~~~~
|
|
|
|
The redis extension is a very simple extension to provide fast
|
|
client access to redis (https://redis.io/) via the hiredis library
|
|
(which must be available when building).
|
|
|
|
Usage
|
|
~~~~~
|
|
|
|
The redis extension exports an Object Based interface. In order
|
|
to open a connection, a stream sock must be open to the redis server.
|
|
e.g.
|
|
|
|
set r [redis [socket stream localhost:6379]]
|
|
|
|
Or to connect via the unix domain socket:
|
|
|
|
set r [redis [socket unix /tmp/redis.sock]]
|
|
|
|
The [redis] command returns a handle, that is a command name that
|
|
can be used to perform operations on the redis instance. A real example:
|
|
|
|
. package require redis
|
|
1.0
|
|
. set r [redis [socket stream localhost:6379]]
|
|
::redis.handle4
|
|
. $r KEYS a*
|
|
abc
|
|
. $r SET def 3
|
|
OK
|
|
. $r INCR def
|
|
4
|
|
. $r HMSET hash a 1 b 2 c 3
|
|
OK
|
|
. $r HGETALL hash
|
|
a 1 b 2 c 3
|
|
|
|
Note that redis commands are shown here in uppercase, but they are accepted in
|
|
a case insensitive manner.
|
|
|
|
The redis connection is very thin wrapper around the redis protocol.
|
|
It simply formats the command according the redis protocol and converts
|
|
the response into the appropriate Tcl format.
|
|
|
|
Note that all values are binary strings, so keys and values in utf-8
|
|
format will be stored and returned exactly.
|
|
|
|
Return values
|
|
~~~~~~~~~~~~~
|
|
|
|
The response from redis contains a type, and these types are handled as follows:
|
|
|
|
* integer - returns the integer result
|
|
* string - returns the string result
|
|
* array - returns a list of elements (where each element is a redis type)
|
|
* null - returns the empty string
|
|
* status - returns the status as a string
|
|
* error - returns an error with the message as the value
|
|
|
|
The read subcommand
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
While most redis commands return an immediate response, SUBSRIBE and PSUBSCRIBE
|
|
return multiple results over time. These responses can be (synchronously)
|
|
read with the 'read' subcommand, typically in conjunction with readable.
|
|
|
|
For example
|
|
|
|
. $r SUBSCRIBE chan
|
|
subscribe chan 1
|
|
. $r read
|
|
message chan PONG
|
|
|
|
If no message is received, the read command will wait forever.
|
|
|
|
The message is returned as: message <channel> <text>
|
|
|
|
The readable subcommand
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Like normal aio sockets, the readable subcommand is supported to invoke
|
|
the given script when the underlying socket is readable.
|
|
|
|
$r SUBSCRIBE channel
|
|
$r readable {
|
|
puts [$r read]
|
|
}
|
|
# wait forever, reading messages from the channel
|
|
vwait forever
|
|
|
|
To remove the callback, invoke with no arguments (this is different from aio readable).
|
|
|
|
# Remove the callback
|
|
$r readable
|
|
|
|
The close subcommand
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The 'close' command is supported to close the connection.
|
|
This command is equivalent to deleting the command with:
|
|
|
|
rename $r ""
|