Commit fc879abe authored by antirez's avatar antirez
Browse files

Merge branch 'unstable'

parents e4f6b8c3 cf1eefa4
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>MoveCommand: Contents</b><br>&nbsp;&nbsp;<a href="#MOVE _key_ _dbindex_">MOVE _key_ _dbindex_</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Return value">Return value</a>
</div>
<h1 class="wikiname">MoveCommand</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;#sidebar <a href="GenericCommandsSidebar.html">GenericCommandsSidebar</a><h1><a name="MOVE _key_ _dbindex_">MOVE _key_ _dbindex_</a></h1>
<blockquote>Move the specified key from the currently selected DB to the specifieddestination DB. Note that this command returns 1 only if the key wassuccessfully moved, and 0 if the target key was already there or if thesource key was not found at all, so it is possible to use MOVE as a lockingprimitive.</blockquote>
<h2><a name="Return value">Return value</a></h2><a href="ReplyTypes.html">Integer reply</a>, specifically:<br/><br/><pre class="codeblock python" name="code">
1 if the key was moved
0 if the key was not moved because already present on the target DB or was not found in the current DB.
</pre>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>MsetCommand: Contents</b><br>&nbsp;&nbsp;<a href="#MSET _key1_ _value1_ _key2_ _value2_ ... _keyN_ _valueN_ (Redis &gt;">MSET _key1_ _value1_ _key2_ _value2_ ... _keyN_ _valueN_ (Redis &gt;</a><br>&nbsp;&nbsp;<a href="#MSETNX _key1_ _value1_ _key2_ _value2_ ... _keyN_ _valueN_ (Redis &gt;">MSETNX _key1_ _value1_ _key2_ _value2_ ... _keyN_ _valueN_ (Redis &gt;</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MSET Return value">MSET Return value</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#MSETNX Return value">MSETNX Return value</a>
</div>
<h1 class="wikiname">MsetCommand</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;#sidebar <a href="StringCommandsSidebar.html">StringCommandsSidebar</a><h1><a name="MSET _key1_ _value1_ _key2_ _value2_ ... _keyN_ _valueN_ (Redis &gt;">MSET _key1_ _value1_ _key2_ _value2_ ... _keyN_ _valueN_ (Redis &gt;</a></h1> 1.1) =
<h1><a name="MSETNX _key1_ _value1_ _key2_ _value2_ ... _keyN_ _valueN_ (Redis &gt;">MSETNX _key1_ _value1_ _key2_ _value2_ ... _keyN_ _valueN_ (Redis &gt;</a></h1> 1.1) =
<i>Time complexity: O(1) to set every key</i><blockquote>Set the the respective keys to the respective values. MSET will replace oldvalues with new values, while MSETNX will not perform any operation at alleven if just a single key already exists.</blockquote>
<blockquote>Because of this semantic MSETNX can be used in order to set different keysrepresenting different fields of an unique logic object in a way thatensures that either all the fields or none at all are set.</blockquote>
<blockquote>Both MSET and MSETNX are atomic operations. This means that for instanceif the keys A and B are modified, another client talking to Redis can eithersee the changes to both A and B at once, or no modification at all.</blockquote>
<h2><a name="MSET Return value">MSET Return value</a></h2><a href="ReplyTypes.html">Status code reply</a> Basically +OK as MSET can't fail<h2><a name="MSETNX Return value">MSETNX Return value</a></h2><a href="ReplyTypes.html">Integer reply</a>, specifically:<br/><br/><pre class="codeblock python" name="code">
1 if the all the keys were set
0 if no key was set (at least one key already existed)
</pre>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>MultiExecCommand: Contents</b><br>&nbsp;&nbsp;<a href="#WATCH key1 key2 ... keyN (Redis &gt;">WATCH key1 key2 ... keyN (Redis &gt;</a><br>&nbsp;&nbsp;<a href="#UNWATCH">UNWATCH</a><br>&nbsp;&nbsp;<a href="#MULTI">MULTI</a><br>&nbsp;&nbsp;<a href="#COMMAND_1 ...">COMMAND_1 ...</a><br>&nbsp;&nbsp;<a href="#COMMAND_2 ...">COMMAND_2 ...</a><br>&nbsp;&nbsp;<a href="#COMMAND_N ...">COMMAND_N ...</a><br>&nbsp;&nbsp;<a href="#EXEC or DISCARD">EXEC or DISCARD</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Usage">Usage</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#The DISCARD command">The DISCARD command</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Check and Set (CAS) transactions using WATCH">Check and Set (CAS) transactions using WATCH</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#WATCH explained">WATCH explained</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#WATCH used to implement ZPOP">WATCH used to implement ZPOP</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Return value">Return value</a>
</div>
<h1 class="wikiname">MultiExecCommand</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;#sidebar <a href="GenericCommandsSidebar.html">GenericCommandsSidebar</a><h1><a name="WATCH key1 key2 ... keyN (Redis &gt;">WATCH key1 key2 ... keyN (Redis &gt;</a></h1> 2.1.0)=
<h1><a name="UNWATCH">UNWATCH</a></h1>
<h1><a name="MULTI">MULTI</a></h1>
<h1><a name="COMMAND_1 ...">COMMAND_1 ...</a></h1>
<h1><a name="COMMAND_2 ...">COMMAND_2 ...</a></h1>
<h1><a name="COMMAND_N ...">COMMAND_N ...</a></h1>
<h1><a name="EXEC or DISCARD">EXEC or DISCARD</a></h1>MULTI, EXEC, DISCARD and WATCH commands are the foundation of Redis Transactions.
A Redis Transaction allows the execution of a group of Redis commands in a single
step, with two important guarantees:<br/><br/><ul><li> All the commands in a transaction are serialized and executed sequentially. It can never happen that a request issued by another client is served <b>in the middle</b> of the execution of a Redis transaction. This guarantees that the commands are executed as a single atomic operation.</li><li> Either all of the commands or none are processed. The EXEC command triggers the execution of all the commands in the transaction, so if a client loses the connection to the server in the context of a transaction before calling the MULTI command none of the operations are performed, instead if the EXEC command is called, all the operations are performed. An exception to this rule is when the Append Only File is enabled: every command that is part of a Redis transaction will log in the AOF as long as the operation is completed, so if the Redis server crashes or is killed by the system administrator in some hard way it is possible that only a partial number of operations are registered.</li></ul>
Since Redis 2.1.0, it's also possible to add a further guarantee to the above two, in the form of optimistic locking of a set of keys in a way very similar to a CAS (check and set) operation. This is documented later in this manual page.<h2><a name="Usage">Usage</a></h2>A Redis transaction is entered using the MULTI command. The command always
replies with OK. At this point the user can issue multiple commands. Instead
of executing these commands, Redis will &quot;queue&quot; them. All the commands are
executed once EXEC is called.<br/><br/>Calling DISCARD instead will flush the transaction queue and will exit
the transaction.<br/><br/>The following is an example using the Ruby client:
<pre class="codeblock python" name="code">
?&gt; r.multi
=&gt; &quot;OK&quot;
&gt;&gt; r.incr &quot;foo&quot;
=&gt; &quot;QUEUED&quot;
&gt;&gt; r.incr &quot;bar&quot;
=&gt; &quot;QUEUED&quot;
&gt;&gt; r.incr &quot;bar&quot;
=&gt; &quot;QUEUED&quot;
&gt;&gt; r.exec
=&gt; [1, 1, 2]
</pre>
As it is possible to see from the session above, MULTI returns an &quot;array&quot; of
replies, where every element is the reply of a single command in the
transaction, in the same order the commands were queued.<br/><br/>When a Redis connection is in the context of a MULTI request, all the commands
will reply with a simple string &quot;QUEUED&quot; if they are correct from the
point of view of the syntax and arity (number of arguments) of the commaand.
Some commands are still allowed to fail during execution time.<br/><br/>This is more clear on the protocol level; In the following example one command
will fail when executed even if the syntax is right:
<pre class="codeblock python python" name="code">
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
MULTI
+OK
SET a 3
abc
+QUEUED
LPOP a
+QUEUED
EXEC
*2
+OK
-ERR Operation against a key holding the wrong kind of value
</pre>
MULTI returned a two elements bulk reply where one is an +OK
code and one is a -ERR reply. It's up to the client lib to find a sensible
way to provide the error to the user.<br/><br/><blockquote>IMPORTANT: even when a command will raise an error, all the other commandsin the queue will be processed. Redis will NOT stop the processing ofcommands once an error is found.</blockquote>
Another example, again using the write protocol with telnet, shows how
syntax errors are reported ASAP instead:
<pre class="codeblock python python python" name="code">
MULTI
+OK
INCR a b c
-ERR wrong number of arguments for 'incr' command
</pre>
This time due to the syntax error the &quot;bad&quot; INCR command is not queued
at all.<h2><a name="The DISCARD command">The DISCARD command</a></h2>DISCARD can be used in order to abort a transaction. No command will be executed, and the state of the client is again the normal one, outside of a transaction. Example using the Ruby client:
<pre class="codeblock python python python python" name="code">
?&gt; r.set(&quot;foo&quot;,1)
=&gt; true
&gt;&gt; r.multi
=&gt; &quot;OK&quot;
&gt;&gt; r.incr(&quot;foo&quot;)
=&gt; &quot;QUEUED&quot;
&gt;&gt; r.discard
=&gt; &quot;OK&quot;
&gt;&gt; r.get(&quot;foo&quot;)
=&gt; &quot;1&quot;
</pre><h2><a name="Check and Set (CAS) transactions using WATCH">Check and Set (CAS) transactions using WATCH</a></h2>WATCH is used in order to provide a CAS (Check and Set) behavior to
Redis Transactions.<br/><br/>WATCHed keys are monitored in order to detect changes against this keys.
If at least a watched key will be modified before the EXEC call, the
whole transaction will abort, and EXEC will return a nil object
(A Null Multi Bulk reply) to notify that the transaction failed.<br/><br/>For example imagine we have the need to atomically increment the value
of a key by 1 (I know we have INCR, let's suppose we don't have it).<br/><br/>The first try may be the following:
<pre class="codeblock python python python python python" name="code">
val = GET mykey
val = val + 1
SET mykey $val
</pre>
This will work reliably only if we have a single client performing the operation in a given time.
If multiple clients will try to increment the key about at the same time
there will be a race condition. For instance client A and B will read the
old value, for instance, 10. The value will be incremented to 11 by both
the clients, and finally SET as the value of the key. So the final value
will be &quot;11&quot; instead of &quot;12&quot;.<br/><br/>Thanks to WATCH we are able to model the problem very well:
<pre class="codeblock python python python python python python" name="code">
WATCH mykey
val = GET mykey
val = val + 1
MULTI
SET mykey $val
EXEC
</pre>
Using the above code, if there are race conditions and another client
modified the result of <i>val</i> in the time between our call to WATCH and
our call to EXEC, the transaction will fail.<br/><br/>We'll have just to re-iterate the operation hoping this time we'll not get
a new race. This form of locking is called <b>optimistic locking</b> and is
a very powerful form of locking as in many problems there are multiple
clients accessing a much bigger number of keys, so it's very unlikely that
there are collisions: usually operations don't need to be performed
multiple times.<h2><a name="WATCH explained">WATCH explained</a></h2>So what is WATCH really about? It is a command that will make the EXEC
conditional: we are asking Redis to perform the transaction only if no
other client modified any of the WATCHed keys. Otherwise the transaction is not
entered at all. (Note that if you WATCH a volatile key and Redis expires the key after you WATCHed it, EXEC will still work. <a href="http://code.google.com/p/redis/issues/detail?id=270" target="_blank">More</a>.)<br/><br/>WATCH can be called multiple times. Simply all the WATCH calls will
have the effects to watch for changes starting from the call, up to the
moment EXEC is called.<br/><br/>When EXEC is called, either if it will fail or succeed, all keys are
UNWATCHed. Also when a client connection is closed, everything gets
UNWATCHed.<br/><br/>It is also possible to use the UNWATCH command (without arguments) in order
to flush all the watched keys. Sometimes this is useful as we
optimistically lock a few keys, since possibly we need to perform a transaction
to alter those keys, but after reading the current content of the keys
we don't want to proceed. When this happens we just call UNWATCH so that
the connection can already be used freely for new transactions.<h2><a name="WATCH used to implement ZPOP">WATCH used to implement ZPOP</a></h2>A good example to illustrate how WATCH can be used to create new atomic
operations otherwise not supported by Redis is to implement ZPOP, that is
a command that pops the element with the lower score from a sorted set
in an atomic way. This is the simplest implementation:
<pre class="codeblock python python python python python python python" name="code">
WATCH zset
ele = ZRANGE zset 0 0
MULTI
ZREM zset ele
EXEC
</pre>
If EXEC fails (returns a nil value) we just re-iterate the operation.<h2><a name="Return value">Return value</a></h2><a href="ReplyTypes.html">Multi bulk reply</a>, specifically:<br/><br/><pre class="codeblock python python python python python python python python" name="code">
The result of a MULTI/EXEC command is a multi bulk reply where every element is the return value of every command in the atomic transaction.
</pre>If a MULTI/EXEC transaction is aborted because of WATCH detected modified keys, a <a href="ReplyTypes.html">Null Multi Bulk reply</a> is returned.
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>NonexistentCommands: Contents</b><br>&nbsp;&nbsp;<a href="#HGETSET">HGETSET</a><br>&nbsp;&nbsp;<a href="#SET with expire">SET with expire</a><br>&nbsp;&nbsp;<a href="#ZADDNX">ZADDNX</a>
</div>
<h1 class="wikiname">NonexistentCommands</h1>
<div class="summary">
A list of commands that don't exist in Redis, but can be accomplished in a different way.
</div>
<div class="narrow">
This is a list of commands that don't exist in Redis, but can be accomplished in a different way, usually by means of <a href="MultiExecCommand.html">WATCH/MULTI/EXEC</a>.<br/><br/>For better performance, you can pipeline multiple commands.<h1><a name="HGETSET">HGETSET</a></h1><a href="GetsetCommand.html">GETSET</a> for Hashes.<br/><br/><pre class="codeblock python" name="code">
WATCH foo
old_value = HGET foo field
MULTI
HSET foo field new_value
EXEC
</pre><h1><a name="SET with expire">SET with expire</a></h1>See <a href="SetexCommand.html">SETEX</a>.<h1><a name="ZADDNX">ZADDNX</a></h1>Add an element to a sorted set, only if the element doesn't already exist (by default, <a href="ZaddCommand.html">ZADD</a> would update the element's score if it already exists). <a href="http://groups.google.com/group/redis-db/browse_thread/thread/fc4c79d72e5bd346/6cdc07ecc36b81e7" target="_blank">See thread</a>.<br/><br/><pre class="codeblock python python" name="code">
WATCH foo
score = ZSCORE foo bar
IF score != NIL
MULTI
ZADD foo 1 bar
EXEC
ENDIF
</pre>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>ObjectHashMappers: Contents</b><br>&nbsp;&nbsp;<a href="#Object Hash Mappers">Object Hash Mappers</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Ruby">Ruby</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Ohm">Ohm</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#dm-redis-adapter">dm-redis-adapter</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#redis-models">redis-models</a>
</div>
<h1 class="wikiname">ObjectHashMappers</h1>
<div class="summary">
</div>
<div class="narrow">
<h1><a name="Object Hash Mappers">Object Hash Mappers</a></h1>Looking for a higher level if abstraction for your Objects, their Properties and Relationships?<br/><br/>There is not need to stick to the <a href="SupportedLanguages.html">client libraries</a> exposing the raw features of Redis, here you will find a list of <b>Object Hash Mappers</b>, working in the same fashion a ORM does.<h2><a name="Ruby">Ruby</a></h2><h3><a name="Ohm">Ohm</a></h3><ul><li> Object-hash mapping library for Redis. It includes an extensible list of validations and has very good performance.</li><li> Authors: <a href="http://soveran.com/" target="_blank">Michel Martens</a>, <a href="http://twitter.com/soveran" target="_blank">@soveran</a>; and Damian Janowski <a href="http://twitter.com/djanowski" target="_blank">@djanowski</a>.</li><li> Repository: <a href="http://github.com/soveran/ohm" target="_blank">http://github.com/soveran/ohm</a></li><li> Group: <a href="http://groups.google.com/group/ohm-ruby" target="_blank">http://groups.google.com/group/ohm-ruby</a></li></ul>
<h3><a name="dm-redis-adapter">dm-redis-adapter</a></h3><ul><li> This is a DataMapper (ORM that is based on the IdentityMap pattern) adapter for the Redis key-value database.</li><li> Author: <a href="http://whoahbot.com/" target="_blank">Whoahbot</a>, <a href="http://twitter.com/whoahbot" target="_blank">@whoahbot</a>.</li><li> Repository: <a href="http://github.com/whoahbot/dm-redis-adapter/" target="_blank">http://github.com/whoahbot/dm-redis-adapter/</a></li></ul>
<h3><a name="redis-models">redis-models</a></h3><ul><li> Minimal model support for Redis. Directly maps Ruby properties to model_name:id:field_name keys in redis. Scalar, List and Set properties are supported. Values can be marshaled to/from Integer, Float, DateTime, JSON. </li><li> Repository: <a href="http://github.com/voloko/redis-model" target="_blank">http://github.com/voloko/redis-model</a></li></ul>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>Pipelining: Contents</b><br>&nbsp;&nbsp;<a href="#Pipelining (DRAFT)">Pipelining (DRAFT)</a>
</div>
<h1 class="wikiname">Pipelining</h1>
<div class="summary">
</div>
<div class="narrow">
<h1><a name="Pipelining (DRAFT)">Pipelining (DRAFT)</a></h1>A client library can use the same connection in order to issue multiple commands. But Redis supports <b>pipelining</b>, so multiple commands can be sent to the server with a single write operation by the client, without need to read the server reply in order to issue the next command. All the replies can be read at the end.<br/><br/>Usually Redis server and client will have a very fast link so this is not very important to support this feature in a client implementation, still if an application needs to issue a very large number of commands in s short time, using pipelining can be much faster.<br/><br/>Please read the <a href="ProtocolSpecification.html">ProtocolSpecification</a> if you want to learn more about the way Redis <a href="SupportedLanguages.html">clients</a> and the server communicate.<br/><br/>Pipelining is one of the <a href="Speed.html">Speed</a> <a href="Features.html">Features</a> of Redis, you can also check the support for <a href="MultiBulkCommands.html">send and receive multiple values in a single command</a>.
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>ProgrammingExamples: Contents</b><br>&nbsp;&nbsp;<a href="#Programming Examples (DRAFT)">Programming Examples (DRAFT)</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#TODO">TODO</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Java">Java</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Twayis">Twayis</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#PHP">PHP</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Retwis">Retwis</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Ruby">Ruby</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#twatcher-lite">twatcher-lite</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Resque">Resque</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Retwis-rb">Retwis-rb</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#scanty-redis">scanty-redis</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Note Taking">Note Taking</a>
</div>
<h1 class="wikiname">ProgrammingExamples</h1>
<div class="summary">
</div>
<div class="narrow">
<h1><a name="Programming Examples (DRAFT)">Programming Examples (DRAFT)</a></h1><h2><a name="TODO">TODO</a></h2><ul><li> Add <a href="http://github.com/jodosha/redis-store" target="_blank">http://github.com/jodosha/redis-store</a></li></ul>
Nothing speaks better than code examples, here you are:<h2><a name="Java">Java</a></h2><h3><a name="Twayis">Twayis</a></h3> <br/><br/>A Java clone of <b>Retwis</b> showcase integration between the <a href="http://www.playframework.org/" target="_blank">Play! framework</a> and Redis <a href="http://code.google.com/p/twayis/" target="_blank">Google Code Project Page</a><h2><a name="PHP">PHP</a></h2><h3><a name="Retwis">Retwis</a></h3>A PHP Twitter clone, the original example of Redis capabilities. With a <a href="http://retwis.antirez.com/" target="_blank">live demo</a>, and an <a href="http://code.google.com/p/redis/wiki/TwitterAlikeExample" target="_blank">article explaining it design</a>. You can find the code in the Downloads tab.<h2><a name="Ruby">Ruby</a></h2><h3><a name="twatcher-lite">twatcher-lite</a></h3>A simplied version of the application running <a href="http://twatcher.com/" target="_blank">http://twatcher.com/</a> from Mirko Froehlich (<a href="http://twitter.com/digitalhobbit" target="_blank">@digitalhobbit</a>) with a full blog post explaining its development at <a href="http://www.digitalhobbit.com/2009/11/08/building-a-twitter-filter-with-sinatra-redis-and-tweetstream/" target="_blank"> Building a Twitter Filter With Sinatra, Redis, and TweetStream</a><h3><a name="Resque">Resque</a></h3>The &quot;simple&quot; Redis-based queue behind Github background jobs, that replaced SQS, Starling, ActiveMessaging, BackgroundJob, DelayedJob, and Beanstalkd. Developed by Chris Wanstrath (<a href="http://twitter.com/defunkt" target="_blank">@defunkt</a>) the code is at <a href="http://github.com/defunkt/resque" target="_blank">http://github.com/defunkt/resque</a>, be sure to read <a href="http://github.com/blog/542-introducing-resque" target="_blank">the introduction</a><h3><a name="Retwis-rb">Retwis-rb</a></h3>A port of <b>Retwis</b> to Ruby and <a href="http://www.sinatrarb.com/" target="_blank">Sinatra</a> written by Daniel Lucraft (<a href="http://twitter.com/DanLucraft" target="_blank">@DanLucraft</a>) Full source code is available at <a href="http://github.com/danlucraft/retwis-rb" target="_blank">http://github.com/danlucraft/retwis-rb</a><h3><a name="scanty-redis">scanty-redis</a></h3>Scanty is <i>minimal</i> blogging software developed by Adam Wiggins (<a href="http://twitter.com/hirodusk" target="_blank">@hirodusk</a>) It is not a blogging engine, but it&acirc;s small and easy to modify, so it could be the starting point for your blog. <a href="http://github.com/adamwiggins/scanty-redis" target="_blank">This fork</a> is modified to use Redis, a full featured key-value database, instead of SQL. <h3><a name="Note Taking">Note Taking</a></h3>A <i>very simple</i> note taking example of Ruby and Redis application using <a href="http://www.sinatrarb.com/" target="_blank">Sinatra</a>. Developed by Pieter Noordhuis <a href="http://twitter.com/pnoordhuis" target="_blank">@pnoordhuis</a>, you can check the code at <a href="http://gist.github.com/86714" target="_blank">http://gist.github.com/86714</a>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>ProtocolSpecification: Contents</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Networking layer">Networking layer</a><br>&nbsp;&nbsp;<a href="#Requests">Requests</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#The new unified request protocol">The new unified request protocol</a><br>&nbsp;&nbsp;<a href="#Replies">Replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Single line reply">Single line reply</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Error reply">Error reply</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Integer reply">Integer reply</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Bulk replies">Bulk replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Multi-Bulk replies">Multi-Bulk replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Multiple commands and pipelining">Multiple commands and pipelining</a><br>&nbsp;&nbsp;<a href="#The old protocol for sending commands">The old protocol for sending commands</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Inline Commands">Inline Commands</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Bulk commands">Bulk commands</a>
</div>
<h1 class="wikiname">ProtocolSpecification</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;= Protocol Specification =<br/><br/>The Redis protocol is a compromise between the following things:<br/><br/><ul><li> Simple to implement.</li><li> Fast to parse by a computer.</li><li> Easy enough to parse by a human.</li></ul>
<h2><a name="Networking layer">Networking layer</a></h2>A client connects to a Redis server creating a TCP connection to the port 6379.
Every Redis command or data transmitted by the client and the server is
terminated by &quot;\r\n&quot; (CRLF).<h1><a name="Requests">Requests</a></h1>Redis accepts commands composed of different arguments.
Once a command is received, it is processed and a reply is sent back to the client.<h2><a name="The new unified request protocol">The new unified request protocol</a></h2>The new unified protocol was introduced in Redis 1.2, but it became the standard way for talking with the Redis server in Redis 2.0.<br/><br/>In the unified protocol all the arguments sent to the Redis server are binary safe. This is the general form:<br/><br/><pre class="codeblock python" name="code">
*&lt;number of arguments&gt; CR LF
$&lt;number of bytes of argument 1&gt; CR LF
&lt;argument data&gt; CR LF
...
$&lt;number of bytes of argument N&gt; CR LF
&lt;argument data&gt; CR LF
</pre>See the following example:<br/><br/><pre class="codeblock python python" name="code">
*3
$3
SET
$5
mykey
$7
myvalue
</pre>This is how the above command looks as a quoted string, so that it is possible to see the exact value of every byte in the query:<br/><br/><pre class="codeblock python python python" name="code">
&quot;*3\r\n$3\r\nSET\r\n$5\r\nmykey\r\n$8\r\nmyvalue\r\n&quot;
</pre>As you will see in a moment this format is also used in Redis replies.
The format used for every argument &quot;$6\r\nmydata\r\n&quot; is called a Bulk Reply.
While the actual unified request protocol is what Redis uses to return list of items, and is called a Multi Bulk Reply. It is just the sum of N different
Bulk Replies prefixed by a <code name="code" class="python">*&lt;argc&gt;\r\n</code> string where <code name="code" class="python">&lt;argc&gt;</code> is the number of arguments (Bulk Replies) that will follow.<h1><a name="Replies">Replies</a></h1>Redis will reply to commands with different kinds of replies. It is possible to check the kind of reply from the first byte sent by the server:<br/><br/><ul><li> With a single line reply the first byte of the reply will be &quot;+&quot;</li><li> With an error message the first byte of the reply will be &quot;-&quot;</li><li> With an integer number the first byte of the reply will be &quot;:&quot;</li><li> With bulk reply the first byte of the reply will be &quot;$&quot;</li><li> With multi-bulk reply the first byte of the reply will be &quot;<code name="code" class="python">*</code>&quot;</li></ul>
<h2><a name="Single line reply">Single line reply</a></h2>A single line reply is in the form of a single line string
starting with &quot;+&quot; terminated by &quot;\r\n&quot;. For example:<br/><br/><pre class="codeblock python python python python" name="code">
+OK
</pre>The client library should return everything after the &quot;+&quot;, that is, the string &quot;OK&quot; in the example.<br/><br/>The following commands reply with a single line reply:
PING, SET, SELECT, SAVE, BGSAVE, SHUTDOWN, RENAME, LPUSH, RPUSH, LSET, LTRIM<h2><a name="Error reply">Error reply</a></h2>Errors are sent exactly like Single Line Replies. The only difference is that the first byte is &quot;-&quot; instead of &quot;+&quot;.<br/><br/>Error replies are only sent when something strange happened, for instance if you try to perform an operation against the wrong data type, or if the command does not exist and so forth. So an exception should be raised by the library client when an Error Reply is received.<h2><a name="Integer reply">Integer reply</a></h2>This type of reply is just a CRLF terminated string representing an integer, prefixed by a &quot;:&quot; byte. For example &quot;:0\r\n&quot;, or &quot;:1000\r\n&quot; are integer replies.<br/><br/>With commands like INCR or LASTSAVE using the integer reply to actually return a value there is no special meaning for the returned integer. It is just an incremental number for INCR, a UNIX time for LASTSAVE and so on.<br/><br/>Some commands like EXISTS will return 1 for true and 0 for false.<br/><br/>Other commands like SADD, SREM and SETNX will return 1 if the operation was actually done, 0 otherwise.<br/><br/>The following commands will reply with an integer reply: SETNX, DEL, EXISTS, INCR, INCRBY, DECR, DECRBY, DBSIZE, LASTSAVE, RENAMENX, MOVE, LLEN, SADD, SREM, SISMEMBER, SCARD<h2><a name="Bulk replies">Bulk replies</a></h2>Bulk replies are used by the server in order to return a single binary safe string.<br/><br/><pre class="codeblock python python python python python" name="code">
C: GET mykey
S: $6
S: foobar
</pre>The server sends as the first line a &quot;$&quot; byte followed by the number of bytes
of the actual reply, followed by CRLF, then the actual data bytes are sent,
followed by additional two bytes for the final CRLF.
The exact sequence sent by the server is:<br/><br/><pre class="codeblock python python python python python python" name="code">
&quot;$6\r\nfoobar\r\n&quot;
</pre>If the requested value does not exist the bulk reply will use the special
value -1 as data length, example:<br/><br/><pre class="codeblock python python python python python python python" name="code">
C: GET nonexistingkey
S: $-1
</pre>The client library API should not return an empty string, but a nil object, when the requested object does not exist.
For example a Ruby library should return 'nil' while a C library should return
NULL (or set a special flag in the reply object), and so forth.<h2><a name="Multi-Bulk replies">Multi-Bulk replies</a></h2>Commands like LRANGE need to return multiple values (every element
of the list is a value, and LRANGE needs to return more than a single element). This is accomplished using multiple bulk writes,
prefixed by an initial line indicating how many bulk writes will follow.
The first byte of a multi bulk reply is always <code name="code" class="python">*</code>. Example:<br/><br/><pre class="codeblock python python python python python python python python" name="code">
C: LRANGE mylist 0 3
S: *4
S: $3
S: foo
S: $3
S: bar
S: $5
S: Hello
S: $5
S: World
</pre>As you can see the multi bulk reply is exactly the same format used in order
to send commands to the Redis server unsing the unified protocol.<br/><br/>The first line the server sent is &quot;<b>4\r\n&quot; in order to specify that four bulk
replies will follow. Then every bulk write is transmitted.<br/><br/>If the specified key does not exist, instead of the number of elements in the
list the special value -1 is sent as count. Example:<br/><br/><pre class="codeblock python python python python python python python python python" name="code">
C: LRANGE nokey 0 1
S: *-1
</pre>A client library API SHOULD return a nil object and not an empty list when this
happens. This makes possible to distinguish between empty list and other error conditions (for instance a timeout condition in the BLPOP command).<h2><a name="Nil elements in Multi-Bulk replies">Nil elements in Multi-Bulk replies</a></h2>Single elements of a multi bulk reply may have -1 length, in order to signal that this elements are missing and not empty strings. This can happen with the SORT command when used with the GET <i>pattern</i> option when the specified key is missing. Example of a multi bulk reply containing an empty element:<br/><br/><pre class="codeblock python python python python python python python python python python" name="code">
S: *3
S: $3
S: foo
S: $-1
S: $3
S: bar
</pre>The second element is nul. The client library should return something like this:<br/><br/><pre class="codeblock python python python python python python python python python python python" name="code">
[&quot;foo&quot;,nil,&quot;bar&quot;]
</pre><h2><a name="Multiple commands and pipelining">Multiple commands and pipelining</a></h2>A client can use the same connection in order to issue multiple commands.
Pipelining is supported so multiple commands can be sent with a single
write operation by the client, it is not needed to read the server reply
in order to issue the next command. All the replies can be read at the end.<br/><br/>Usually Redis server and client will have a very fast link so this is not
very important to support this feature in a client implementation, still
if an application needs to issue a very large number of commands in short
time to use pipelining can be much faster.<h1><a name="The old protocol for sending commands">The old protocol for sending commands</a></h1>Before of the Unified Request Protocol Redis used a different protocol to send
commands, that is still supported since it is simpler to type by hand via telnet. In this protocol there are two kind of commands:<br/><br/><blockquote>* Inline commands: simple commands where argumnets are just space separated strings. No binary safeness is possible.* Bulk commands: bulk commands are exactly like inline commands, but the last argument is handled in a special way in order to allow for a binary-safe last argument.</blockquote>
<h2><a name="Inline Commands">Inline Commands</a></h2>The simplest way to send Redis a command is via </b>Inline Commands.
The following is an example of a server/client chat using an inline command (the server chat starts with S:, the client chat with C:)<br/><br/><pre class="codeblock python python python python python python python python python python python python" name="code">
C: PING
S: +PONG
</pre>The following is another example of an INLINE command returning an integer:<br/><br/><pre class="codeblock python python python python python python python python python python python python python" name="code">
C: EXISTS somekey
S: :0
</pre>Since 'somekey' does not exist the server returned ':0'.<br/><br/>Note that the EXISTS command takes one argument. Arguments are separated
by spaces.<h2><a name="Bulk commands">Bulk commands</a></h2>Some commands when sent as inline commands require a special form in order
to support a binary safe last argument. This commands will use the last argument
for a &quot;byte count&quot;, then the bulk data is sent (that can be binary safe since
the server knows how many bytes to read).<br/><br/>See for instance the following example:<br/><br/><pre class="codeblock python python python python python python python python python python python python python python" name="code">
C: SET mykey 6
C: foobar
S: +OK
</pre>The last argument of the commnad is '6'. This specify the number of DATA
bytes that will follow, that is, the string &quot;foobar&quot;. Note that even this bytes are terminated by two additional bytes of CRLF.<br/><br/>All the bulk commands are in this exact form: instead of the last argument
the number of bytes that will follow is specified, followed by the bytes
composing the argument itself, and CRLF. In order to be more clear for the programmer this is the string sent by the client in the above sample:<br/><br/><blockquote>&quot;SET mykey 6\r\nfoobar\r\n&quot;</blockquote>
Redis has an internal list of what command is inline and what command is bulk, so you have to send this commands accordingly. It is strongly suggested to use the new Unified Request Protocol instead.
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>PublishSubscribe: Contents</b><br>&nbsp;&nbsp;<a href="#UNSUBSCRIBE channel_1 channel_2 ... channel_N">UNSUBSCRIBE channel_1 channel_2 ... channel_N</a><br>&nbsp;&nbsp;<a href="#UNSUBSCRIBE (unsubscribe from all channels)">UNSUBSCRIBE (unsubscribe from all channels)</a><br>&nbsp;&nbsp;<a href="#PSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a><br>&nbsp;&nbsp;<a href="#PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a><br>&nbsp;&nbsp;<a href="#PUNSUBSCRIBE (unsubscribe from all patterns)">PUNSUBSCRIBE (unsubscribe from all patterns)</a><br>&nbsp;&nbsp;<a href="#PUBLISH channel message">PUBLISH channel message</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Format of pushed messages">Format of pushed messages</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Unsubscribing from all the channels at once">Unsubscribing from all the channels at once</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Wire protocol example">Wire protocol example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions">PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Messages matching both a pattern and a channel subscription">Messages matching both a pattern and a channel subscription</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#The meaning of the count of subscriptions with pattern matching">The meaning of the count of subscriptions with pattern matching</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#More details on the PUBLISH command">More details on the PUBLISH command</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Programming Example">Programming Example</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Client library implementations hints">Client library implementations hints</a>
</div>
<h1 class="wikiname">PublishSubscribe</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;=SUBSCRIBE channel_1 channel_2 ... channel_N=
<h1><a name="UNSUBSCRIBE channel_1 channel_2 ... channel_N">UNSUBSCRIBE channel_1 channel_2 ... channel_N</a></h1>
<h1><a name="UNSUBSCRIBE (unsubscribe from all channels)">UNSUBSCRIBE (unsubscribe from all channels)</a></h1>
<h1><a name="PSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a></h1>
<h1><a name="PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N">PUNSUBSCRIBE pattern_1 pattern_2 ... pattern_N</a></h1>
<h1><a name="PUNSUBSCRIBE (unsubscribe from all patterns)">PUNSUBSCRIBE (unsubscribe from all patterns)</a></h1>
<h1><a name="PUBLISH channel message">PUBLISH channel message</a></h1>Time complexity: subscribe is O(1), unsubscribe is O(N) where N is the number of clients already subscribed to a channel, publish is O(N+M) where N is the number of clients subscribed to the receiving channel, and M is the total number of subscribed patterns (by any client). Psubscribe is O(N) where N is the number of patterns the Psubscribing client is already subscribed to. Punsubscribe is O(N+M) where N is the number of patterns the Punsubscribing client is already subscribed and M is the number of total patterns subscribed in the system (by any client).<br/><br/><b>Note</b>: this commands are available starting form Redis 2.0.0<br/><br/><blockquote>SUBSCRIBE, UNSUBSCRIBE and PUBLISH commands implement the<a href="http://en.wikipedia.org/wiki/Publish/subscribe" target="_blank">Publish/Subscribe messaging paradigm</a> where (citing Wikipedia) senders (publishers) are not programmed to send their messages to specific receivers (subscribers). Rather, published messages are characterized into channels, without knowledge of what (if any) subscribers there may be. Subscribers express interest in one or more channels, and only receive messages that are of interest, without knowledge of what (if any) publishers there are. This decoupling of publishers and subscribers can allow for greater scalability and a more dynamic network topology.</blockquote>
<blockquote>For instance in order to subscribe to the channels foo and bar the clientwill issue the SUBSCRIBE command followed by the names of the channels.</blockquote><pre class="codeblock python" name="code">
SUBSCRIBE foo bar
</pre>
<blockquote>All the messages sent by other clients to this channels will be pushed bythe Redis server to all the subscribed clients, in the form of a threeelements bulk reply, where the first element is the message type, thesecond the originating channel, and the third argument the message payload.</blockquote>
<blockquote>A client subscribed to 1 or more channels should NOT issue other commandsother than SUBSCRIBE and UNSUBSCRIBE, but can subscribe or unsubscribeto other channels dynamically.</blockquote>
<blockquote>The reply of the SUBSCRIBE and UNSUBSCRIBE operations are sent in the formof messages, so that the client can just read a coherent stream of messageswhere the first element indicates the kind of message.</blockquote><h2><a name="Format of pushed messages">Format of pushed messages</a></h2>
<blockquote>Messages are in the form of multi bulk replies with three elements.The first element is the kind of message:</blockquote><ul><li> &quot;subscribe&quot;: means that we successfully subscribed to the channel given as second element of the multi bulk reply. The third argument represents the number of channels we are currently subscribed to.</li><li> &quot;unsubscribe&quot;: means that we successfully unsubscribed from the channel given as second element of the multi bulk reply. The third argument represents the number of channels we are currently subscribed to. If this latest argument is zero, we are no longer subscribed to any channel, and the client can issue any kind of Redis command as we are outside the Pub/sub state.</li><li> &quot;message&quot;: it is a message received as result of a PUBLISH command issued by another client. The second element is the name of the originating channel, and the third the actual message payload.</li></ul><h2><a name="Unsubscribing from all the channels at once">Unsubscribing from all the channels at once</a></h2>
If the UNSUBSCRIBE command is issued without additional arguments, it is equivalent to unsubscribing to all the channels we are currently subscribed. A message for every unsubscribed channel will be received.
<h2><a name="Wire protocol example">Wire protocol example</a></h2>
<pre class="codeblock python python" name="code">
SUBSCRIBE first second
*3
$9
subscribe
$5
first
:1
*3
$9
subscribe
$6
second
:2
</pre>
at this point from another client we issue a PUBLISH operation against the channel named &quot;second&quot;. This is what the first client receives:
<pre class="codeblock python python python" name="code">
*3
$7
message
$6
second
$5
Hello
</pre>
Now the client unsubscribes itself from all the channels using the UNSUBSCRIBE command without additional arguments:
<pre class="codeblock python python python python" name="code">
UNSUBSCRIBE
*3
$11
unsubscribe
$6
second
:1
*3
$11
unsubscribe
$5
first
:0
</pre>
<h2><a name="PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions">PSUBSCRIBE and PUNSUBSCRIBE: pattern matching subscriptions</a></h2>
Redis Pub/Sub implementation supports pattern matching. Clients may subscribe to glob style patterns in order to receive all the messages sent to channel names matching a given pattern.<br/><br/>For instance the command:
<pre class="codeblock python python python python python" name="code">
PSUBSCRIBE news.*
</pre>
Will receive all the messages sent to the channel news.art.figurative and news.music.jazz and so forth. All the glob style patterns as valid, so multiple wild cards are supported.<br/><br/>Messages received as a result of pattern matching are sent in a different format:
<ul><li> The type of the message is &quot;pmessage&quot;: it is a message received as result of a PUBLISH command issued by another client, matching a pattern matching subscription. The second element is the original pattern matched, the third element is the name of the originating channel, and the last element the actual message payload.</li></ul>
Similarly to SUBSCRIBE and UNSUBSCRIBE, PSUBSCRIBE and PUNSUBSCRIBE commands are acknowledged by the system sending a message of type &quot;psubscribe&quot; and &quot;punsubscribe&quot; using the same format as the &quot;subscribe&quot; and &quot;unsubscribe&quot; message format.
<h2><a name="Messages matching both a pattern and a channel subscription">Messages matching both a pattern and a channel subscription</a></h2>
A client may receive a single message multiple time if it's subscribed to multiple patterns matching a published message, or it is subscribed to both patterns and channels matching the message. Like in the following example:
<pre class="codeblock python python python python python python" name="code">
SUBSCRIBE foo
PSUBSCRIBE f*
</pre>
In the above example, if a message is sent to the <b>foo</b> channel, the client will receive two messages, one of type &quot;message&quot; and one of type &quot;pmessage&quot;.
<h2><a name="The meaning of the count of subscriptions with pattern matching">The meaning of the count of subscriptions with pattern matching</a></h2>
In <b>subscribe</b>, <b>unsubscribe</b>, <b>psubscribe</b> and <b>punsubscribe</b> message types, the last argument is the count of subscriptions still active. This number is actually the total number of channels and patterns the client is still subscribed to. So the client will exit the Pub/Sub state only when this count will drop to zero as a result of unsubscription from all the channels and patterns.
<h2><a name="More details on the PUBLISH command">More details on the PUBLISH command</a></h2>
The Publish command is a bulk command where the first argument is the target class, and the second argument the data to send. It returns an Integer Reply representing the number of clients that received the message (that is, the number of clients that were listening for this class).
<h2><a name="Programming Example">Programming Example</a></h2>
Pieter Noordhuis provided a great example using Event-machine and Redis to create <a href="http://chat.redis-db.com" target="_blank">a multi user high performance web chat</a>, with source code included of course!
<h2><a name="Client library implementations hints">Client library implementations hints</a></h2>
Because all the messages received contain the original subscription causing the message delivery (the channel in the case of &quot;message&quot; type, and the original pattern in the case of &quot;pmessage&quot; type) clinet libraries may bind the original subscription to callbacks (that can be anonymous functions, blocks, function pointers, and so forth), using an hash table.<br/><br/>When a message is received an O(1) lookup can be done in order to deliver the message to the registered callback.
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>QuickStart: Contents</b><br>&nbsp;&nbsp;<a href="#Quick Start">Quick Start</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Obtain the latest version">Obtain the latest version</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Compile">Compile</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Run the server">Run the server</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Play with the built in client">Play with the built in client</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Further reading">Further reading</a>
</div>
<h1 class="wikiname">QuickStart</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;#sidebar <a href="RedisGuides.html">RedisGuides</a>
<h1><a name="Quick Start">Quick Start</a></h1>This quickstart is a five minutes howto on how to get started with Redis. For more information on Redis check <a href="http://code.google.com/p/redis/wiki/index" target="_blank">Redis Documentation Index</a>.<h2><a name="Obtain the latest version">Obtain the latest version</a></h2>The latest stable source distribution of Redis can be obtained <a href="http://code.google.com/p/redis/downloads/list" target="_blank">at this location as a tarball</a>.<br/><br/><pre class="codeblock python" name="code">
$ wget http://redis.googlecode.com/files/redis-1.02.tar.gz
</pre>The unstable source code, with more features but not ready for production, can be downloaded using git:<br/><br/><pre class="codeblock python python" name="code">
$ git clone git://github.com/antirez/redis.git
</pre><h2><a name="Compile">Compile</a></h2>Redis can be compiled in most <a href="SupportedPlatforms.html">POSIX systems</a>. To compile Redis just untar the tar.gz, enter the directly and type 'make'.<br/><br/><pre class="codeblock python python python" name="code">
$ tar xvzf redis-1.02.tar.gz
$ cd redis-1.02
$ make
</pre>In order to test if the Redis server is working well in your computer make sure to run <code name="code" class="python">make test</code> and check that all the tests are passed.<h2><a name="Run the server">Run the server</a></h2>Redis can run just fine without a configuration file (when executed without a config file a standard configuration is used). To run Redis just type the following command:<br/><br/><pre class="codeblock python python python python" name="code">
$ ./redis-server
</pre>With the <a href="Configuration.html">default configuration</a> Redis will log to the standard output so you can check what happens. Later, you can <a href="Configuration.html">change the default settings</a>.<h2><a name="Play with the built in client">Play with the built in client</a></h2>Redis ships with a command line client that is automatically compiled when you ran <code name="code" class="python">make</code> and it is called <code name="code" class="python">redis-cli</code>For instance to set a key and read back the value use the following:<br/><br/><pre class="codeblock python python python python python" name="code">
$ ./redis-cli set mykey somevalue
OK
$ ./redis-cli get mykey
somevalue
</pre>What about adding elements to a <a href="Lists.html">list</a>:<br/><br/><pre class="codeblock python python python python python python" name="code">
$ ./redis-cli lpush mylist firstvalue
OK
$ ./redis-cli lpush mylist secondvalue
OK
$ ./redis-cli lpush mylist thirdvalue
OK
$ ./redis-cli lrange mylist 0 -1
1. thirdvalue
2. secondvalue
3. firstvalue
$ ./redis-cli rpop mylist
firstvalue
$ ./redis-cli lrange mylist 0 -1
1. thirdvalue
2. secondvalue
</pre><h2><a name="Further reading">Further reading</a></h2><ul><li> What to play more with Redis? Read <a href="IntroductionToRedisDataTypes.html">Fifteen minutes introduction to Redis data types</a>.</li><li> Check all the <a href="Features.html">Features</a></li><li> Read the full list of available commands in the <a href="CommandReference.html">Command Reference</a>.</li><li> Start using Redis from your <a href="SupportedLanguages.html">favorite language</a>.</li><li> Take a look at some <a href="ProgrammingExamples.html">Programming Examples</a>. </li></ul>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>QuitCommand: Contents</b><br>&nbsp;&nbsp;<a href="#Quit">Quit</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Return value">Return value</a>
</div>
<h1 class="wikiname">QuitCommand</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;#sidebar <a href="ConnectionHandlingSidebar.html">ConnectionHandlingSidebar</a><h1><a name="Quit">Quit</a></h1><blockquote>Ask the server to silently close the connection.</blockquote>
<h2><a name="Return value">Return value</a></h2>None. The connection is closed as soon as the QUIT command is received.
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>README: Contents</b><br>&nbsp;&nbsp;<a href="#All data in memory, but saved on disk">All data in memory, but saved on disk</a><br>&nbsp;&nbsp;<a href="#Master-Slave replication made trivial">Master-Slave replication made trivial</a><br>&nbsp;&nbsp;<a href="#It's persistent but supports expires">It's persistent but supports expires</a><br>&nbsp;&nbsp;<a href="#Beyond key-value databases">Beyond key-value databases</a><br>&nbsp;&nbsp;<a href="#Multiple databases support">Multiple databases support</a><br>&nbsp;&nbsp;<a href="#Know more about Redis!">Know more about Redis!</a><br>&nbsp;&nbsp;<a href="#Redis Tutorial">Redis Tutorial</a><br>&nbsp;&nbsp;<a href="#License">License</a><br>&nbsp;&nbsp;<a href="#Credits">Credits</a>
</div>
<h1 class="wikiname">README</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;= Introduction =<br/><br/>Redis is an extremely fast and powerful key-value store database and server implemented in ANSI C. Redis offers many different ways to do one straightforward thing: store a value (&quot;antirez&quot;) to a key (&quot;redis&quot;). While the format of keys must always be simple strings, the power is with the values, which support the following data types:<br/><br/><ul><li> <a href="Strings.html">Strings</a></li><li> <a href="Lists.html">Lists</a></li><li> <a href="Sets.html">Sets</a></li><li> <a href="SortedSets.html">Sorted Sets (zsets)</a></li><li> <a href="Hashes.html">Hashes</a></li></ul>
Each value type has an associated list of commands which can operate on them, and the <a href="CommandReference.html">The Redis Command Reference</a> contains an up to date list of these commands, organized primarily by data type. The Redis source also includes a <a href="RedisCLI.html">Redis command line interface</a> which allows you to interact directly with the server, and is the means by which this introduction will provide examples. Once you walk through the <a href="QuickStart.html">Redis Quick Start Guide</a> to get your instance of Redis running, you can follow along. <br/><br/>One of the most powerful aspects of Redis is the wide range of commands which are optimized to work with specific data value types and executed as atomic server-side operations. The <a href="Lists.html">List</a> type is a great example - Redis implements O(1) operations such as <a href="RpushCommand.html">LPUSH</a> or <a href="RpushCommand.html">RPUSH</a>, which have accompanying <a href="LpopCommand.html">LPOP</a> and <a href="LpopCommand.html">RPOP</a> methods:<br/><br/><pre class="codeblock python" name="code">
redis&gt; lpush programming_languages C
OK
redis&gt; lpush programming_languages Ruby
OK
redis&gt; rpush programming_languages Python
OK
redis&gt; rpop programming_languages
Python
redis&gt; lpop programming_languages
Ruby
</pre>More complex operations are available for each data type as well. Continuing with lists, you can get a range of elements with <a href="LrangeCommand.html">LRANGE</a> (O(start+n)) or trim the list with <a href="LtrimCommand.html">LTRIM</a> (O(n)):<br/><br/><pre class="codeblock python python" name="code">
redis&gt; lpush cities NYC
OK
redis&gt; lpush cities SF
OK
redis&gt; lpush cities Tokyo
OK
redis&gt; lpush cities London
OK
redis&gt; lpush cities Paris
OK
redis&gt; lrange cities 0 2
1. Paris
2. London
3. Tokyo
redis&gt; ltrim cities 0 1
OK
redis&gt; lpop cities
Paris
redis&gt; lpop cities
London
redis&gt; lpop cities
(nil)
</pre>You can also add and remove elements from a set, and perform intersections, unions, and differences. <br/><br/>Redis can also be looked at as a data structures server. A Redis user is virtually provided with an interface to <a href="http://en.wikipedia.org/wiki/Abstract_data_type" target="_blank">Abstract Data Types</a>, saving them from the responsibility of implementing concrete data structures and algorithms -- indeed both algorithms and data structures in Redis are properly chosen in order to obtain the best performance.<h1><a name="All data in memory, but saved on disk">All data in memory, but saved on disk</a></h1>Redis loads and mantains the whole dataset into memory, but the dataset is persistent, since at the same time it is saved on disk, so that when the server is restarted data can be loaded back in memory.<br/><br/>There are two kinds of persistence supported: the first one is called snapshotting. In this mode Redis periodically writes to disk asynchronously. The dataset is loaded from the dump every time the server is (re)started.<br/><br/>Redis can be configured to save the dataset when a certain number of changes is reached and after a given number of seconds elapses. For example, you can configure Redis to save after 1000 changes and at most 60 seconds since the last save. You can specify any combination for these numbers.<br/><br/>Because data is written asynchronously, when a system crash occurs, the last few queries can get lost (that is acceptable in many applications but not in all). In order to make this a non issue Redis supports another, safer persistence mode, called <a href="AppendOnlyFileHowto.html">Append Only File</a>, where every command received altering the dataset (so not a read-only command, but a write command) is written on an append only file ASAP. This commands are <i>replayed</i> when the server is restarted in order to rebuild the dataset in memory.<br/><br/>Redis Append Only File supports a very handy feature: the server is able to safely rebuild the append only file in background in a non-blocking fashion when it gets too long. You can find <a href="AppendOnlyFileHowto.html">more details in the Append Only File HOWTO</a>.<h1><a name="Master-Slave replication made trivial">Master-Slave replication made trivial</a></h1>Whatever will be the persistence mode you'll use Redis supports master-slave replications if you want to stay really safe or if you need to scale to huge amounts of reads.<br/><br/><b>Redis Replication is trivial to setup</b>. So trivial that all you need to do in order to configure a Redis server to be a slave of another one, with automatic synchronization if the link will go down and so forth, is the following config line: <code name="code" class="python">slaveof 192.168.1.100 6379</code>. <a href="ReplicationHowto.html">We provide a Replication Howto</a> if you want to know more about this feature.<h1><a name="It's persistent but supports expires">It's persistent but supports expires</a></h1>Redis can be used as a <b>memcached on steroids</b> because is as fast as memcached but with a number of features more. Like memcached, Redis also supports setting timeouts to keys so that this key will be automatically removed when a given amount of time passes.<h1><a name="Beyond key-value databases">Beyond key-value databases</a></h1>All these features allow to use Redis as the sole DB for your scalable application without the need of any relational database. <a href="TwitterAlikeExample.html">We wrote a simple Twitter clone in PHP + Redis</a> to show a real world example, the link points to an article explaining the design and internals in very simple words.<h1><a name="Multiple databases support">Multiple databases support</a></h1>Redis supports multiple databases with commands to atomically move keys from one database to the other. By default DB 0 is selected for every new connection, but using the SELECT command it is possible to select a different database. The MOVE operation can move an item from one DB to another atomically. This can be used as a base for locking free algorithms together with the 'RANDOMKEY' commands.<h1><a name="Know more about Redis!">Know more about Redis!</a></h1>To really get a feeling about what Redis is and how it works please try reading <a href="IntroductionToRedisDataTypes.html">A fifteen minutes introduction to Redis data types</a>.<br/><br/>To know a bit more about how Redis works <i>internally</i> continue reading.<h1><a name="Redis Tutorial">Redis Tutorial</a></h1>(note, you can skip this section if you are only interested in &quot;formal&quot; doc.)<br/><br/>Later in this document you can find detailed information about Redis commands,
the protocol specification, and so on. This kind of documentation is useful
but... if you are new to Redis it is also BORING! The Redis protocol is designed
so that is both pretty efficient to be parsed by computers, but simple enough
to be used by humans just poking around with the 'telnet' command, so this
section will show to the reader how to play a bit with Redis to get an initial
feeling about it, and how it works.<br/><br/>To start just compile redis with 'make' and start it with './redis-server'.
The server will start and log stuff on the standard output, if you want
it to log more edit redis.conf, set the loglevel to debug, and restart it.<br/><br/>You can specify a configuration file as unique parameter:<br/><br/><blockquote>./redis-server /etc/redis.conf</blockquote>
This is NOT required. The server will start even without a configuration file
using a default built-in configuration.<br/><br/>Now let's try to set a key to a given value:<br/><br/><pre class="codeblock python python python" name="code">
$ telnet localhost 6379
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
SET foo 3
bar
+OK
</pre>The first line we sent to the server is &quot;set foo 3&quot;. This means &quot;set the key
foo with the following three bytes I'll send you&quot;. The following line is
the &quot;bar&quot; string, that is, the three bytes. So the effect is to set the
key &quot;foo&quot; to the value &quot;bar&quot;. Very simple!<br/><br/>(note that you can send commands in lowercase and it will work anyway,
commands are not case sensitive)<br/><br/>Note that after the first and the second line we sent to the server there
is a newline at the end. The server expects commands terminated by &quot;\r\n&quot;
and sequence of bytes terminated by &quot;\r\n&quot;. This is a minimal overhead from
the point of view of both the server and client but allows us to play with
Redis with the telnet command easily.<br/><br/>The last line of the chat between server and client is &quot;+OK&quot;. This means
our key was added without problems. Actually SET can never fail but
the &quot;+OK&quot; sent lets us know that the server received everything and
the command was actually executed.<br/><br/>Let's try to get the key content now:<br/><br/><pre class="codeblock python python python python" name="code">
GET foo
$3
bar
</pre>Ok that's very similar to 'set', just the other way around. We sent &quot;get foo&quot;,
the server replied with a first line that is just the $ character follwed by
the number of bytes the value stored at key contained, followed by the actual
bytes. Again &quot;\r\n&quot; are appended both to the bytes count and the actual data. In Redis slang this is called a bulk reply.<br/><br/>What about requesting a non existing key?<br/><br/><pre class="codeblock python python python python python" name="code">
GET blabla
$-1
</pre>When the key does not exist instead of the length, just the &quot;$-1&quot; string is sent. Since a -1 length of a bulk reply has no meaning it is used in order to specifiy a 'nil' value and distinguish it from a zero length value. Another way to check if a given key exists or not is indeed the EXISTS command:<br/><br/><pre class="codeblock python python python python python python" name="code">
EXISTS nokey
:0
EXISTS foo
:1
</pre>As you can see the server replied ':0' the first time since 'nokey' does not
exist, and ':1' for 'foo', a key that actually exists. Replies starting with the colon character are integer reply.<br/><br/>Ok... now you know the basics, read the <a href="CommandReference.html">REDIS COMMAND REFERENCE</a> section to
learn all the commands supported by Redis and the <a href="ProtocolSpecification.html">PROTOCOL SPECIFICATION</a>
section for more details about the protocol used if you plan to implement one
for a language missing a decent client implementation.<h1><a name="License">License</a></h1>Redis is released under the BSD license. See the COPYING file for more information.<h1><a name="Credits">Credits</a></h1>Redis is written and maintained by Salvatore Sanfilippo, Aka 'antirez'.
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>RandomkeyCommand: Contents</b><br>&nbsp;&nbsp;<a href="#RANDOMKEY">RANDOMKEY</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Return value">Return value</a>
</div>
<h1 class="wikiname">RandomkeyCommand</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;#sidebar <a href="GenericCommandsSidebar.html">GenericCommandsSidebar</a><h1><a name="RANDOMKEY">RANDOMKEY</a></h1>
<i>Time complexity: O(1)</i><blockquote>Return a randomly selected key from the currently selected DB.</blockquote>
<h2><a name="Return value">Return value</a></h2><a href="ReplyTypes.html">Singe line reply</a>, specifically the randomly selected key or an empty string is the database is empty.
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>Redis0100ChangeLog: Contents</b><br>&nbsp;&nbsp;<a href="#Redis 0.100 Changelog">Redis 0.100 Changelog</a>
</div>
<h1 class="wikiname">Redis0100ChangeLog</h1>
<div class="summary">
</div>
<div class="narrow">
<h1><a name="Redis 0.100 Changelog">Redis 0.100 Changelog</a></h1>
<pre class="codeblock python" name="code">
- SUNION, SDIFF, SUNIONSTORE, SDIFFSTORE commands implemented. (Aman Gupta, antirez)
- Non blocking replication. Now while N slaves are synchronizing, the master will continue to ask to client queries. (antirez)
- PHP client ported to PHP5 (antirez)
- FLUSHALL/FLUSHDB no longer sync on disk. Just increment the dirty counter by the number of elements removed, that will probably trigger a background saving operation (antirez)
- INCRBY/DECRBY now support 64bit increments, with tests (antirez)
- New fields in INFO command, bgsave_in_progress and replication related (antirez)
- Ability to specify a different file name for the DB (... can't remember ...)
- GETSET command, atomic GET + SET (antirez)
- SMOVE command implemented, atomic move-element across sets operation (antirez)
- Ability to work with huge data sets, tested up to 350 million keys (antirez)
- Warns if /proc/sys/vm/overcommit_memory is set to 0 on Linux. Also make sure to don't resize the hash tables while the child process is saving in order to avoid copy-on-write of memory pages (antirez)
- Infinite number of arguments for MGET and all the other commands (antirez)
- CPP client (Brian Hammond)
- DEL is now a vararg, IMPORTANT: memory leak fixed in loading DB code (antirez)
- Benchmark utility now supports random keys (antirez)
- Timestamp in log lines (antirez)
- Fix SINTER/UNIONSTORE to allow for &amp;=/|= style operations (i.e. SINTERSTORE set1 set1 set2) (Aman Gupta)
- Partial qsort implemented in SORT command, only when both BY and LIMIT is used (antirez)
- Allow timeout=0 config to disable client timeouts (Aman Gupta)
- Alternative (faster/simpler) ruby client API compatible with Redis-rb (antirez)
- S*STORE now return the cardinality of the resulting set (antirez)
- TTL command implemented (antirez)
- Critical bug about glueoutputbuffers=yes fixed. Under load and with pipelining and clients disconnecting on the middle of the chat with the server, Redis could block. (antirez)
- Different replication fixes (antirez)
- SLAVEOF command implemented for remote replication management (antirez)
- Issue with redis-client used in scripts solved, now to check if the latest argument must come from standard input we do not check that stdin is or not a tty but the command arity (antirez)
- Warns if using the default config (antirez)
- maxclients implemented, see redis.conf for details (antirez)
- max bytes of a received command enlarged from 1k to 32k (antirez)
</pre>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>Redis0900ChangeLog: Contents</b><br>&nbsp;&nbsp;<a href="#CHANGELOG for Redis 0.900">CHANGELOG for Redis 0.900</a>
</div>
<h1 class="wikiname">Redis0900ChangeLog</h1>
<div class="summary">
</div>
<div class="narrow">
<h1><a name="CHANGELOG for Redis 0.900">CHANGELOG for Redis 0.900</a></h1><pre class="codeblock python" name="code">
2009-06-16 client libraries updated (antirez)
2009-06-16 Better handling of background saving process killed or crashed (antirez)
2009-06-14 number of keys info in INFO command (Diego Rosario Brogna)
2009-06-14 SPOP documented (antirez)
2009-06-14 Clojure library (Ragnar Dahl&Atilde;&copy;n)
2009-06-10 It is now possible to specify - as config file name to read it from stdin (antirez)
2009-06-10 max bytes in an inline command raised to 1024*1024 bytes, in order to allow for very large MGETs and still protect from client crashes (antirez)
2009-06-08 SPOP implemented. Hash table resizing for Sets and Expires too. Changed the resize policy to play better with RANDOMKEY and SPOP. (antirez)
2009-06-07 some minor changes to the backtrace code (antirez)
2009-06-07 enable backtrace capabilities only for Linux and MacOSX (antirez)
2009-06-07 Dump a backtrace on sigsegv/sigbus, original coded (Diego Rosario Brogna)
2009-06-05 Avoid a busy loop while sending very large replies against very fast links, this allows to be more responsive with other clients even under a KEY * against the loopback interface (antirez)
2009-06-05 Kill the background saving process before performing SHUTDOWN to avoid races (antirez)
2009-06-05 LREM now returns :0 for non existing keys (antirez)
2009-06-05 added config.h for #ifdef business isolation, added fstat64 for Mac OS X (antirez)
2009-06-04 macosx specific zmalloc.c, uses malloc_size function in order to avoid to waste memory and time to put an additional header (antirez)
2009-06-04 DEBUG OBJECT implemented (antirez)
2009-06-03 shareobjectspoolsize implemented in reds.conf, in order to control the pool size when object sharing is on (antirez)
2009-05-27 maxmemory implemented (antirez)
</pre>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>RedisBigData: Contents</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#BGSAVE and BGREWRITEAOF blocking fork() call">BGSAVE and BGREWRITEAOF blocking fork() call</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Using multiple cores">Using multiple cores</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Splitting data into multiple instances">Splitting data into multiple instances</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#BGSAVE / AOFSAVE memory usage, and copy on write">BGSAVE / AOFSAVE memory usage, and copy on write</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#BGSAVE / AOFSAVE time for big datasets">BGSAVE / AOFSAVE time for big datasets</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Non blocking hash table">Non blocking hash table</a>
</div>
<h1 class="wikiname">RedisBigData</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;=Redis Big Data: facts and guidelines=<h2><a name="BGSAVE and BGREWRITEAOF blocking fork() call">BGSAVE and BGREWRITEAOF blocking fork() call</a></h2>
<pre class="codeblock python" name="code">
fork.c &amp;&amp; ./a.out
allocated: 1 MB, fork() took 0.000
allocated: 10 MB, fork() took 0.001
allocated: 100 MB, fork() took 0.007
allocated: 1000 MB, fork() took 0.059
allocated: 10000 MB, fork() took 0.460
allocated: 20000 MB, fork() took 0.895
allocated: 30000 MB, fork() took 1.327
allocated: 40000 MB, fork() took 1.759
allocated: 50000 MB, fork() took 2.190
allocated: 60000 MB, fork() took 2.621
allocated: 70000 MB, fork() took 3.051
allocated: 80000 MB, fork() took 3.483
allocated: 90000 MB, fork() took 3.911
allocated: 100000 MB, fork() took 4.340
allocated: 110000 MB, fork() took 4.770
allocated: 120000 MB, fork() took 5.202
</pre>
<h2><a name="Using multiple cores">Using multiple cores</a></h2>
<h2><a name="Splitting data into multiple instances">Splitting data into multiple instances</a></h2>
<h2><a name="BGSAVE / AOFSAVE memory usage, and copy on write">BGSAVE / AOFSAVE memory usage, and copy on write</a></h2>
<h2><a name="BGSAVE / AOFSAVE time for big datasets">BGSAVE / AOFSAVE time for big datasets</a></h2>
<h2><a name="Non blocking hash table">Non blocking hash table</a></h2>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>RedisCLI: Contents</b><br>&nbsp;&nbsp;<a href="#Redis CLI">Redis CLI</a>
</div>
<h1 class="wikiname">RedisCLI</h1>
<div class="summary">
Redis Command Line Interface
</div>
<div class="narrow">
<h1><a name="Redis CLI">Redis CLI</a></h1>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>RedisEventLibrary: Contents</b><br>&nbsp;&nbsp;<a href="#Redis Event Library">Redis Event Library</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Event Loop Initialization">Event Loop Initialization</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#aeCreateEventLoop">aeCreateEventLoop</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#aeCreateTimeEvent">aeCreateTimeEvent</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#aeCreateFileEvent">aeCreateFileEvent</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Event Loop Processing">Event Loop Processing</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#aeProcessEvents">aeProcessEvents</a><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#processTimeEvents">processTimeEvents</a>
</div>
<h1 class="wikiname">RedisEventLibrary</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;#sidebar <a href="RedisInternals.html">RedisInternals</a><h1><a name="Redis Event Library">Redis Event Library</a></h1>Redis implements its own event library. The event library is implemented in <b>ae.c</b>.<br/><br/>The best way to understand how the Redis event library works is to understand how Redis uses it.<h2><a name="Event Loop Initialization">Event Loop Initialization</a></h2>
<code name="code" class="python">initServer</code> function defined in <b>redis.c</b> initializes the numerous fields of the <code name="code" class="python">redisServer</code> structure variable. One such field is the Redis event loop <code name="code" class="python">el</code>:<br/><br/><pre class="codeblock python" name="code">
aeEventLoop *el
</pre><code name="code" class="python">initServer</code> initializes <code name="code" class="python">server.el</code> field by calling <code name="code" class="python">aeCreateEventLoop</code> defined in <b>ae.c</b>. The definition of <code name="code" class="python">aeEventLoop</code> is below:
<pre class="codeblock python python" name="code">
typedef struct aeEventLoop
{
int maxfd;
long long timeEventNextId;
aeFileEvent events[AE_SETSIZE]; /* Registered events */
aeFiredEvent fired[AE_SETSIZE]; /* Fired events */
aeTimeEvent *timeEventHead;
int stop;
void *apidata; /* This is used for polling API specific data */
aeBeforeSleepProc *beforesleep;
} aeEventLoop;
</pre><h3><a name="aeCreateEventLoop">aeCreateEventLoop</a></h3><code name="code" class="python">aeCreateEventLoop</code> first mallocs aeEventLoop structure then calls ae_epoll.c:aeApiCreate<code name="code" class="python">.
</code>aeApiCreate<code name="code" class="python"> mallocs </code>aeApiState<code name="code" class="python"> that has two fields - </code>epfd<code name="code" class="python"> that holds the epoll file descriptor returned by a call from [http://man.cx/epoll_create%282%29 epoll_create] and </code>events<code name="code" class="python"> that is of type </code>struct epoll_event<code name="code" class="python"> define by the Linux epoll library. The use of the </code>events<code name="code" class="python"> field will be described later.
Next is 'ae.c:aeCreateTimeEvent</code>. But before that <code name="code" class="python">initServer</code> call <code name="code" class="python">anet.c:anetTcpServer</code> that creates and returns a <i>listening descriptor</i>. The descriptor is listens to <b>port 6379</b> by default. The returned <i>listening descriptor</i> is stored in <code name="code" class="python">server.fd</code> field.<h3><a name="aeCreateTimeEvent">aeCreateTimeEvent</a></h3><code name="code" class="python">aeCreateTimeEvent</code> accepts the following as parameters:<br/><br/><ul><li> eventLoop: This is <code name="code" class="python">server.el</code> in <b>redis.c</b></li><li> milliseconds: The number of milliseconds from the curent time after which the timer expires.</li><li> proc: Function pointer. Stores the address of the function that has to be called after the timer expires.</li><li> clientData: Mostly NULL.</li><li> finalizerProc: Pointer to the function that has to be called before the timed event is removed from the list of timed events.</li></ul>
<code name="code" class="python">initServer</code> calls <code name="code" class="python">aeCreateTimeEvent</code> to add a timed event to <code name="code" class="python">timeEventHead</code> field of <code name="code" class="python">server.el</code>. <code name="code" class="python">timeEventHead</code> is a pointer to a list of such timed events. The call to <code name="code" class="python">aeCreateTimeEvent</code> from <code name="code" class="python">redis.c:initServer</code> function is given below:<br/><br/><pre class="codeblock python python python" name="code">
aeCreateTimeEvent(server.el /*eventLoop*/, 1 /*milliseconds*/, serverCron /*proc*/, NULL /*clientData*/, NULL /*finalizerProc*/);
</pre><code name="code" class="python">redis.c:serverCron</code> performs many operations that helps keep Redis running properly.<h3><a name="aeCreateFileEvent">aeCreateFileEvent</a></h3>The essence of <code name="code" class="python">aeCreateFileEvent</code> function is to execute <a href="http://man.cx/epoll_ctl" target="_blank">epoll_ctl</a> system call which adds a watch for <code name="code" class="python">EPOLLIN</code> event on the <i>listening descriptor</i> create by <code name="code" class="python">anetTcpServer</code> and associate it with the epoll descriptor created by a call to <code name="code" class="python">aeCreateEventLoop</code>. <br/><br/>Following is an explanation of what precisely <code name="code" class="python">aeCreateFileEvent</code> does when called from <code name="code" class="python">redis.c:initServer</code>.<br/><br/><code name="code" class="python">initServer</code> passes the following arguments to <code name="code" class="python">aeCreateFileEvent</code>:
<ul><li> server.el: The event loop created by <code name="code" class="python">aeCreateEventLoop</code>. The epoll descriptor is got from server.el. </li><li> server.fd: The <i>listening descriptor</i> that also serves as an index to access the relevant file event structure from the <code name="code" class="python">eventLoop-&gt;events</code> table and store extra information like the callback function.</li><li> AE_READABLE: Signifies that server.fd has to be watched for EPOLLIN event.</li><li> acceptHandler: The function that has to be executed when the event being watched for is ready. This function pointer is stored in <code name="code" class="python">eventLoop-&gt;events[server.fd]-&gt;rfileProc</code>. </li></ul>
This completes the initialization of Redis event loop.<h2><a name="Event Loop Processing">Event Loop Processing</a></h2><code name="code" class="python">ae.c:aeMain</code> called from <code name="code" class="python">redis.c:main</code> does the job of processing the event loop that is initialized in the previous phase.<br/><br/><code name="code" class="python">ae.c:aeMain</code> calls <code name="code" class="python">ae.c:aeProcessEvents</code> in a while loop that processes pending time and file events.<h3><a name="aeProcessEvents">aeProcessEvents</a></h3><code name="code" class="python">ae.c:aeProcessEvents</code> looks for the time event that will be pending in the smallest amount of time by calling <code name="code" class="python">ae.c:aeSearchNearestTimer</code> on the event loop. In our case there is only one timer event in the event loop that was created by <code name="code" class="python">ae.c:aeCreateTimeEvent</code>. <br/><br/>Remember, that timer event created by <code name="code" class="python">aeCreateTimeEvent</code> has by now probably elapsed because it had a expiry time of one millisecond. Since, the timer has already expired the seconds and microseconds fields of the <code name="code" class="python">tvp</code> timeval structure variable is initialized to zero. <br/><br/>The <code name="code" class="python">tvp</code> structure variable along with the event loop variable is passed to <code name="code" class="python">ae_epoll.c:aeApiPoll</code>.<br/><br/><code name="code" class="python">aeApiPoll</code> functions does a <a href="http://man.cx/epoll_wait" target="_blank">epoll_wait</a> on the epoll descriptor and populates the <code name="code" class="python">eventLoop-&gt;fired</code> table with the details:
<ul><li> fd: The descriptor that is now ready to do a read/write operation depending on the mask value. The </li><li> mask: The read/write event that can now be performed on the corresponding descriptor.</li></ul>
<code name="code" class="python">aeApiPoll</code> returns the number of such file events ready for operation. Now to put things in context, if any client has requested for a connection then aeApiPoll would have noticed it and populated the <code name="code" class="python">eventLoop-&gt;fired</code> table with an entry of the descriptor being the <i>listening descriptor</i> and mask being <code name="code" class="python">AE_READABLE</code>.<br/><br/>Now, <code name="code" class="python">aeProcessEvents</code> calls the <code name="code" class="python">redis.c:acceptHandler</code> registered as the callback. <code name="code" class="python">acceptHandler</code> executes [<a href="http://man.cx/accept(2" target="_blank">http://man.cx/accept(2</a>) accept] on the <i>listening descriptor</i> returning a <i>connected descriptor</i> with the client. <code name="code" class="python">redis.c:createClient</code> adds a file event on the <i>connected descriptor</i> through a call to <code name="code" class="python">ae.c:aeCreateFileEvent</code> like below:<br/><br/><pre class="codeblock python python python python" name="code">
if (aeCreateFileEvent(server.el, c-&gt;fd, AE_READABLE,
readQueryFromClient, c) == AE_ERR) {
freeClient(c);
return NULL;
}
</pre><code name="code" class="python">c</code> is the <code name="code" class="python">redisClient</code> structure variable and <code name="code" class="python">c-&gt;fd</code> is the connected descriptor.<br/><br/>Next the <code name="code" class="python">ae.c:aeProcessEvent</code> calls <code name="code" class="python">ae.c:processTimeEvents</code><h3><a name="processTimeEvents">processTimeEvents</a></h3><code name="code" class="python">ae.processTimeEvents</code> iterates over list of time events starting at <code name="code" class="python">eventLoop-&gt;timeEventHead</code>.<br/><br/>For every timed event that has elapsed <code name="code" class="python">processTimeEvents</code> calls the registered callback. In this case it calls the only timed event callback registered, that is, <code name="code" class="python">redis.c:serverCron</code>. The callback returns the time in milliseconds after which the callback must be called again. This change is recorded via a call to <code name="code" class="python">ae.c:aeAddMilliSeconds</code> and will be handled on the next iteration of <code name="code" class="python">ae.c:aeMain</code> while loop.<br/><br/>That's all.
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>RedisGuides: Contents</b>
</div>
<h1 class="wikiname">RedisGuides</h1>
<div class="summary">
</div>
<div class="narrow">
&iuml;&raquo;&iquest;= Redis Guides and Howtos=
<ul><li> <a href="QuickStart.html">Redis Quick Start</a></li><li> <a href="VirtualMemoryUserGuide.html">Virutal Memory User Guide</a></li><li> <a href="IntroductionToRedisDataTypes.html">A Fifteen Minutes Introduction to the Redis Data Types</a></li><li> <a href="ReplicationHowto.html">The Redis Replication HOWTO</a></li><li> <a href="AppendOnlyFileHowto.html">The Append Only File HOWTO</a></li></ul>
</div>
</div>
</div>
</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html>
<head>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div id="page">
<div id='header'>
<a href="index.html">
<img style="border:none" alt="Redis Documentation" src="redis.png">
</a>
</div>
<div id="pagecontent">
<div class="index">
<!-- This is a (PRE) block. Make sure it's left aligned or your toc title will be off. -->
<b>RedisInternals: Contents</b><br>&nbsp;&nbsp;<a href="#Redis Internals">Redis Internals</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Redis STRINGS">Redis STRINGS</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Redis Virtual Memory">Redis Virtual Memory</a><br>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#Redis Event Library">Redis Event Library</a>
</div>
<h1 class="wikiname">RedisInternals</h1>
<div class="summary">
</div>
<div class="narrow">
<h1><a name="Redis Internals">Redis Internals</a></h1>This is a source code level documentation of Redis.<h2><a name="Redis STRINGS">Redis STRINGS</a></h2>String is the basic building block of Redis types. <br/><br/>Redis is a key-value store.
All Redis keys are strings and its also the simplest value type.<br/><br/><blockquote></blockquote>Lists, sets, sorted sets and hashes are other more complex value types and even
these are composed of strings.<br/><br/><a href="HackingStrings.html">Hacking Strings</a> documents the Redis String implementation details.<h2><a name="Redis Virtual Memory">Redis Virtual Memory</a></h2>A technical specification full of details about the <a href="VirtualMemorySpecification.html">Redis Virtual Memory subsystem</a><h2><a name="Redis Event Library">Redis Event Library</a></h2>Read <a href="EventLibray.html">event library</a> to understand what an event library does and why its needed.<br/><br/><a href="RedisEventLibrary.html">Redis event library</a> documents the implementation details of the event library used by Redis
</div>
</div>
</div>
</body>
</html>
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment