README.redis

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 socket 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. For 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
~~~~~~~~~~~~~

Responses from redis contain type information. 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)
* nil - returns the empty string
* status - returns the status as a string
* error - returns an error with the message as the value

Accessing type information
~~~~~~~~~~~~~~~~~~~~~~~~~~

Normally the type of the return value doesn't matter as Jim treats everything as a string,
however it can be useful to differentiate between the empty string and nil, or between a status
return and an error return. In order to support this, the '-type' option is allowed as the
first word of the subcommand. In this case, whenever a value is returned, a list of {value type}
is returned instead. This is true recursively, so an array will return both the type for the array
and each element will include a type. The types are identified as follows:

* integer - "int"
* string - "str"
* array - "array"
* nil - "nil"
* status - "status"
* error - "error"

The following example illustrates the use of types:

    . $r -type KEYS a*
    {{abc str}} array
    . $r -type SET def 3
    OK status
    . $r INCR def
    4 int
    . $r -type GET missing
    {} nil
	. $r -type KEYS
	{ERR wrong number of arguments for 'keys' command} error

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 'read' subcommand is also used in non-blocking mode. See the section below for more details.

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 ""

Async/Non-blocking support
~~~~~~~~~~~~~~~~~~~~~~~~~~

It is possible to connect to redis in non-blocking mode by using the '-async' flag. e.g.

  set r [redis -async [socket stream localhost:6379]]

Now commands will return immediately with an empty result and 'read' in a 'readable' should
be used to retrieve the result. As a simple example:

  $r readable {
      set result [$r read]
      if {$result ne ""} {
          puts $result
          incr next
      }
  }
  $r SET x 5
  vwait next
  $r INCR x
  vwait next

Note that if a large result is returned, 'read' may return an empty string, in
which case further calls to 'readable' are required to return the result.

In general the underlying socket should be put into non-blocking mode ($sock ndelay 1)
and a while loop should be used to read reponses until and empty result is returned.