diff options
author | Steve Bennett <steveb@workware.net.au> | 2020-11-14 14:43:41 +1000 |
---|---|---|
committer | Steve Bennett <steveb@workware.net.au> | 2020-11-15 20:05:52 +1000 |
commit | be4c0e8732445172d52dfb38b56c8aa997762309 (patch) | |
tree | 3af6160b81a898427a0a96b45829176361ec3502 /README.redis | |
parent | c436661c19ac193007af0d2d878f554bad08f905 (diff) | |
download | jimtcl-be4c0e8732445172d52dfb38b56c8aa997762309.zip jimtcl-be4c0e8732445172d52dfb38b56c8aa997762309.tar.gz jimtcl-be4c0e8732445172d52dfb38b56c8aa997762309.tar.bz2 |
redis: Add simple redis client extension
Using the hiredis client library.
Synchronous API only.
Signed-off-by: Steve Bennett <steveb@workware.net.au>
Diffstat (limited to 'README.redis')
-rw-r--r-- | README.redis | 105 |
1 files changed, 105 insertions, 0 deletions
diff --git a/README.redis b/README.redis new file mode 100644 index 0000000..adae3b5 --- /dev/null +++ b/README.redis @@ -0,0 +1,105 @@ +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 "" |