retcl - Tcl client library for Redis
The retcl module is an event-driven, object-oriented, Redis client library, which API exposes a single retcl class. Objects of this class represent connections to a Redis server and are used to send requests as commands and retrieve responses.
Other than a few book-keeping methods, instance objects of the retcl class 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 the retcl package completely decoupled from any version of Redis. This has several advantages:
The retcl package 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
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.
Try to reconnect to the server that was specified upon construction. This method returns immediately and schedules to retry for 30 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. By default, commands are sent in asynchronous mode and immediately return a cmdId identifier that can be later used to retrieve the result. The default mode can be changed with the +async and -async commands. if -sync is specified, the command is sent synchronously and will wait until a response is available. The body of the response is returned. If -cb cmdPrefix is specified, the command is sent asynchronously and return a cmdId immediately. cmdPrefix will eventually be called when the response is available, with the cmdId, type and body of the result as additional parameters. Either -sync or -cb cmdPrefix might be specified, but not both.
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. Each key in the dictionary is a cmdId and each value is its associated response body.
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.
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.
Set up an error handler to be called whenever an asynchronous error occurs inside the retcl package. 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-2017 Pietro Cerutti <gahr@gahr.ch>