retcl - Tcl client library for Redis
The retcl module is an event-driven, object-oriented, Redis client library for the Tcl programming language. The library exposes a single retcl class. Instances of this class represent connections to a Redis server and are used to send requests in the form of native Redis commands and retrieve responses.
Other than a few book-keeping methods, retcl instances transparently handle Redis commands as first-class methods. As an example,
r SET K Hello
can be used to set the value of the key K to the string Hello. This is achieved by proxying all unknown methods to the Redis server by concatenating all arguments, effectively making retcl instances completely decoupled from any version of Redis. This has several advantages:
A retcl instance does not need to know about the semantics of a particular Redis command. This includes syntax checks, context verification and arguments validation, which are offloaded to the Redis server. As a consequence, the code base remains clean and small.
New commands introduced by a server upgrade are immediately available to a live application.
Create a new retcl object and automatically connects to the Redis server at hostname:port. The hostname argument defaults to 127.0.0.1. The port argument defaults to 6379.
Example: create a Redis client object named r and connect to the Redis server on 192.168.1.3, default port 6379:
% retcl create r 192.168.1.3
::r
Create a new retcl object in disconnected mode. The object can be connected further on using the connect or reconnect.
Check whether the socket with the Redis server is open. Return 1 if it is, 0 otherwise. Example: check the connection status, disconnect, check again:
% r connected
1
% r disconnect
% r connected
0
Connect to the Redis server at hostname:port, which defaults to 127.0.0.1:6379. It is an error to attempt a connection using an already connected object.
Disconnect from the Redis server.
Return immediately, then try to reconnect to the server that was specified upon construction for up to 10 seconds. If no connection can be established after this time, an error is reported using the error handler.
Methods not explicitely defined by the retcl class are forwarded to Redis by concatenating the REDIS_CMD and any optional arguments. The mode of operation depends on the object-wide asynchronous mode set using the +async and -async commands. Synchronous operation can be forced by specifying the -sync argument. In asynchronous mode, Redis commands immediately return a cmdId identifier that can be later used to retrieve the result. In synchronous mode, Redis commands are blocking, and eventually return the body of the result, when it becomes available. A third variant of operation is accessible using the -cb cmdPrefix option. If specified, the command is sent asynchronously and return a cmdId immediately. When the response is available, a command is constructed and executed by appending the cmdId, the type, and the body of the result to cmdPrefix.
Return the result of the command identified by cmdId. If the response is not yet available and -async is specified, the command returns the empty string, otherwise it will wait.
Return a boolean indicating whether the response for the command identified by cmdId is ready for retrieval.
Return the type of the result of the command identified by cmdId. If the response is not ready for retrieval, this command returns the empty string.
Return a dictionary of all available results. Results are kept in a results cache for later retrieval. The dictionary containes two types of entries that provide information about the result values and their types. Values are associated with keys in the form cmdId, while types are associated with keys in the form cmdId:type.
% r incr foo
rds:1
% r incr foo
rds:2
% r allResults
rds:1 1 rds:1:type Integer rds:2 2 rds:2:type Integer
Turn on the use of the results cache. This is the default.
Turn off the use of the results cache. Results are removed from the cache as soon as they are retrieved.
Return a boolean value indicating whether cache keeping is currently on or off.
Remove the result for ?cmdId? from the results cache or clear it entirely.
Turn on asynchronous operation. In this mode, commands return immediately with a command identifier.
Turn off asynchronous operation. In this mode, commands wait until a response is received and return the body.
Return a boolean value indicating whether asynchronous operation is currenty on of off.
Set up an error handler to be called whenever an asynchronous error occurs inside the retcl class. The cmdPrefix is appended an error message. If cmdPrefix is the empty string, the error handler is restored to the default error command. This command returns the old cmdPrefix.
Pipelining allows to queue several commands and send them out in a single batch to the Redis server. This is more efficient than sending each command independently. The script is evaluated at caller's scope and it might contain any valid Tcl commands. Any Redis commands sent during the evaluation of the script are queued and sent to the Redis server at the end of the script. This command returns the empty string. Results can be obtained using the allResults method.
Callbacks are part of the Redis Pub/Sub mechanism. A client registers a callback on a subscription item, and then subscribes to that channel using the PSUBSCRIBE Redis command. When a message arrives on the subscription item, cmdPrefix is called appending the following to the arguments list:a
type The type of the message (subscribe, unsubscribe, or message).
pattern The subscription item as specified in the PSUBSCRIBE command.
channel The actual channel the message was sent to.
message The message received.
Copyright © 2014-2018 Pietro Cerutti <gahr@gahr.ch>