minor doc changes

TODO

@@ -1,28 +1,28 @@
 BEFORE REDIS 1.0.0-rc1
 
-- SDIFF, SDIFFSTORE
-- Add number of keys for every DB in INFO
-- maxmemory support
-- maxclients support
-- Resize the expires and Sets hash tables if needed as well? For Sets the right moment to check for this is probably in SREM
-- TTL command that returns -1 if a key is not volatile otherwise the time to live of a volatile key in seconds.
-- What happens if the saving child gets killed or segfaults instead of ending normally? Handle this.
-- Make sinterstore / unionstore / sdiffstore returning the cardinality of the resulting set.
-- check 'server.dirty' everywere
-- Shutdown must kill other background savings before to start saving. Otherwise the DB can get replaced by the child that rename(2) after the parent for some reason. Child should trap the signal and remove the temp file name.
-- Objects sharing configuration, add the directive "objectsharingpool <size>"
-- Make sure to convert all the fstat() calls to 64bit versions.
-- SINTERCOUNT, SUNIONCOUNT, SDIFFCOUNT
+ * SDIFF, SDIFFSTORE
+ * Add number of keys for every DB in INFO
+ * maxmemory support
+ * maxclients support
+ * Resize the expires and Sets hash tables if needed as well? For Sets the right moment to check for this is probably in SREM
+ * TTL command that returns -1 if a key is not volatile otherwise the time to live of a volatile key in seconds.
+ * What happens if the saving child gets killed or segfaults instead of ending normally? Handle this.
+ * Make sinterstore / unionstore / sdiffstore returning the cardinality of the resulting set.
+ * check 'server.dirty' everywere
+ * Shutdown must kill other background savings before to start saving. Otherwise the DB can get replaced by the child that rename(2) after the parent for some reason. Child should trap the signal and remove the temp file name.
+ * Objects sharing configuration, add the directive `objectsharingpool <size>`
+ * Make sure to convert all the fstat() calls to 64bit versions.
+ * Cover most of the source code with test-redis.tcl
 
 AFTER 1.0 stable release
 
-- Use partial qsort for SORT + LIMIT. Don't copy the list into a vector when BY argument is constant.
-- Locking primitives
-- MDEL (or vararg DEL)
-- Write the hash table size of every db in the dump, so that Redis can resize the hash table just one time when loading a big DB.
-- Elapsed time in logs for SAVE when saving is going to take more than 2 seconds
-- replication automated tests
-- LOCK / TRYLOCK / UNLOCK as described many times in the google group
+ * Consistent hashing implemented in all the client libraries having an user base
+ * Use partial qsort for SORT + LIMIT. Don't copy the list into a vector when BY argument is constant.
+ * Profiling and optimization in order to limit the CPU usage at minimum
+ * Write the hash table size of every db in the dump, so that Redis can resize the hash table just one time when loading a big DB.
+ * Elapsed time in logs for SAVE when saving is going to take more than 2 seconds
+ * LOCK / TRYLOCK / UNLOCK as described many times in the google group
+ * Replication automated tests
 
 FUTURE HINTS
 

doc/README.html

@@ -28,23 +28,23 @@
                 <div class="narrow">
                     <h1><a name="Introduction">Introduction</a></h1>Redis is a database. To be more specific redis is a very simple database
 implementing a dictionary where keys are associated with values. For example
-I can set the key &quot;surname_1992&quot; to the string &quot;Smith&quot;.<br/><br/>Redis takes the whole dataset in memory, but the dataset is persistent
-since from time to time Redis writes a dump of the dataset on disk asynchronously. The dump is loaded every time the server is restarted. This means that if a system crash occurs the last few queries can get lost (that is acceptable in many applications). Redis supports master-slave replication from the early days in order to improve performances and reliability.<h1><a name="Beyond key-value databases">Beyond key-value databases</a></h1>In most key-value databases keys and values are simple strings. In Redis keys are just strings too, but the associated values can be Strings, Lists and Sets, and there are commands to perform complex atomic operations against this data types, so you can think at Redis as a data structures server.<br/><br/>For example you can append elements to a list stored at the key &quot;mylist&quot; using the LPUSH or RPUSH operation in O(1). Later you'll be able to get a range of elements with LRANGE or trim the list with LTRIM. Sets are very flexible too, it is possible to add and remove elements from Sets (unsorted collections of strings), and then ask for server-side intersection, union, difference of Sets.<br/><br/>All this features, the support for sorting Lists and Sets, 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="What are the differences between Redis and Memcached?">What are the differences between Redis and Memcached?</a></h1>In the following ways:<br/><br/><ul><li> Memcached is not persistent, it just holds everything in memory without saving since its main goal is to be used as a cache. Redis instead can be used as the main DB for the application. We <a href="TwitterAlikeExample.html">wrote a simple Twitter clone</a> using only Redis as database.</li></ul>
+I can set the key &quot;surname_1992&quot; to the string &quot;Smith&quot;. The interesting thing about Redis is that values associated to keys are not limited to simple strings, they can also be lists and sets, with a <a href="CommandReference.html">number of server-side atomic operations</a> associated to this data types.<br/><br/>Redis takes the whole dataset in memory, but the dataset is persistent
+since from time to time Redis writes a dump of the dataset on disk asynchronously. The dump is loaded every time the server is restarted.<br/><br/>Redis can be configured to save the dataset after a given number of seconds elapzed and changes to the data set. For example you can tell Redis to save after 1000 changes and at least 60 seconds sinde the same save. You can specify a number of this combinatins.<br/><br/>Because data is written asynchronously, If a system crash occurs the last few queries can get lost (that is acceptable in many applications). Redis supports master-slave replication from the early days in order to make this a non issue if your application is of the kind where even few lost records are not acceptable.<h1><a name="Beyond key-value databases">Beyond key-value databases</a></h1>In most key-value databases keys and values are simple strings. In Redis keys are just strings too, but the associated values can be Strings, Lists and Sets, and there are commands to perform complex atomic operations against this data types, so you can think at Redis as a data structures server.<br/><br/>For example you can append elements to a list stored at the key &quot;mylist&quot; using the LPUSH or RPUSH operation in O(1). Later you'll be able to get a range of elements with LRANGE or trim the list with LTRIM. Sets are very flexible too, it is possible to add and remove elements from Sets (unsorted collections of strings), and then ask for server-side intersection, union, difference of Sets.<br/><br/>All this features, the support for sorting Lists and Sets, 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="What are the differences between Redis and Memcached?">What are the differences between Redis and Memcached?</a></h1>In the following ways:<br/><br/><ul><li> Memcached is not persistent, it just holds everything in memory without saving since its main goal is to be used as a cache. Redis instead can be used as the main DB for the application. We <a href="TwitterAlikeExample.html">wrote a simple Twitter clone</a> using only Redis as database.</li></ul>
 <ul><li> Like memcached Redis uses a key-value model, but while keys can just be strings, values in Redis can be lists and sets, and complex operations like intersections, set/get n-th element of lists, pop/push of elements, can be performed against sets and lists. It is possible to use lists as message queues.</li></ul>
-<h1><a name="What are the differences between Redis and Tokyo Cabinet / Tyrant?">What are the differences between Redis and Tokyo Cabinet / Tyrant?</a></h1>Redis and Tokyo Cabinet can be used for the same applications, but actually they are <b>very</b> different beasts:<br/><br/><ul><li> Tokyo Cabinet writes synchronously on disk, Redis takes the whole dataset on memory and writes on disk asynchronously. Tokyo Cabinet is safer, Redis faster (but note that Redis supports master-slave replication that is trivial to setup, so you are safe anyway if you want a setup where data can't be lost even after a disaster).</li></ul>
-<ul><li> Redis supports higher level operations and data structures. While Tokyo Cabinet supports a kind of database that is able to organize data into rows with named fields (in a way very similar to Berkeley DB) can't do things like server side List and Set operations Redis is able to do: pushing or popping from Lists in an atomic way, in O(1) time complexity, server side Set intersections, <a href="SORT.html">SortCommand</a> ing of schema free data in complex ways (Btw TC supports sorting in the table-based database format).</li></ul>
+<h1><a name="What are the differences between Redis and Tokyo Cabinet / Tyrant?">What are the differences between Redis and Tokyo Cabinet / Tyrant?</a></h1>Redis and Tokyo Cabinet can be used for the same applications, but actually they are <b>very</b> different beasts. If you read twitter messages of people involved in scalable things both products are reported to work well, but surely there are times where one or the other can be the best choice. Some differences are the followings (I may be biased, make sure to check yourself both the products).<br/><br/><ul><li> Tokyo Cabinet writes synchronously on disk, Redis takes the whole dataset on memory and writes on disk asynchronously. Tokyo Cabinet is safer and probably a better idea if your dataset is going to be bigger than RAM, but Redis is faster (note that Redis supports master-slave replication that is trivial to setup, so you are safe anyway if you want a setup where data can't be lost even after a disaster).</li></ul>
+<ul><li> Redis supports higher level operations and data structures. Tokyo Cabinet supports a kind of database that is able to organize data into rows with named fields (in a way very similar to Berkeley DB) but can't do things like server side List and Set operations Redis is able to do: pushing or popping from Lists in an atomic way, in O(1) time complexity, server side Set intersections, <a href="SORT.html">SortCommand</a> ing of schema free data in complex ways (Btw TC supports sorting in the table-based database format). Redis on the other hand does not support the abstraction of tables with fields, the idea is that you can build this stuff in software easily if you really need a table-alike approach.</li></ul>
 <ul><li> Tokyo Cabinet does not implement a networking layer. You have to use a networking layer called Tokyo Tyrant that interfaces to Tokyo Cabinet so you can talk to Tokyo Cabinet in a client-server fashion. In Redis the networking support is built-in inside the server, and is basically the only interface between the external world and the dataset.</li></ul>
-<ul><li> Redis is reported to be much faster, especially if you plan to access Tokyo Cabinet via Tokyo Tyrant. From the informal numbers I saw around on the net you can expect Redis to be 10 times faster than Tokyo Cabinet + Tyrant.</li></ul>
-<ul><li> Redis is generally an higher level beast in the operations supported, and it is much simpler to get started. <a href="Check.html">the command reference CommandReference</a> to get a feeling. You can even start playing with Redis by telnet after reading the five minutes tutorial at the end of this README file. To implement new client libraries is trivial. <a href="Check.html">the protocol specification ProtocolSpecification</a> for more information.</li></ul><blockquote></blockquote><ul><li> Redis is not an on-disk DB engine like Tokyo: the latter can be used as a fast DB engine in your C project without the networking overhead just linking to the library. Still remember that in many scalable applications you need multiple servers talking with multiple clients, so the client-server model is almost always needed.</li></ul>
+<ul><li> Redis is reported to be much faster, especially if you plan to access Tokyo Cabinet via Tokyo Tyrant. Here I can only say that with Redis you can expect 100,000 operations/seconds with a normal Linux box and 50 concurrent clients. You should test Redis, Tokyo, and the other alternatives with your specific work load to get a feeling about performances for your application.</li></ul>
+<ul><li> Redis is (IMHO) generally an higher level and simpler to use beast in the operations supported, and to get started. <a href="Check.html">the command reference CommandReference</a> to get a feeling. You can even start playing with Redis by telnet after reading the five minutes tutorial at the end of this README file. To implement new client libraries is trivial. <a href="Check.html">the protocol specification ProtocolSpecification</a> for more information.</li></ul><blockquote></blockquote><ul><li> Redis is not an on-disk DB engine like Tokyo: the latter can be used as a fast DB engine in your C project without the networking overhead just linking to the library. Still in many scalable applications you need multiple servers talking with multiple clients, so the client-server model is almost always needed, this is why in Redis this is built-in.</li></ul>
 <h1><a name="Does Redis support locking?">Does Redis support locking?</a></h1>No, the idea is to provide atomic primitives in order to make the programmer
 able to use redis with locking free algorithms. For example imagine you have
-10 computers and 1 redis server. You want to count words in a very large text.
+10 computers and one Redis server. You want to count words in a very large text.
 This large text is split among the 10 computers, every computer will process
 its part and use Redis's INCR command to atomically increment a counter
 for every occurrence of the word found.<br/><br/>INCR/DECR are not the only atomic primitives, there are others like PUSH/POP
 on lists, POP RANDOM KEY operations, UPDATE and so on. For example you can
 use Redis like a Tuple Space (<a href="http://en.wikipedia.org/wiki/Tuple_space" target="_blank">http://en.wikipedia.org/wiki/Tuple_space</a>) in
-order to implement distributed algorithms.<br/><br/>(News: locking with key-granularity is now planned)<h1><a name="Multiple databases support">Multiple databases support</a></h1>Another synchronization primitive is the support for multiple DBs. 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' or 'POPRANDOMKEY' commands.<h1><a name="Redis Data Types">Redis Data Types</a></h1>Redis supports the following three data types as values:<br/><br/><ul><li> Strings: just any sequence of bytes. Redis strings are binary safe so they can not just hold text, but images, compressed data and everything else.</li><li> Lists: lists of strings, with support for operations like append a new string on head, on tail, list length, obtain a range of elements, truncate the list to a given length, sort the list, and so on.</li><li> Sets: an unsorted set of strings. It is possible to add or delete elements from a set, to perform set intersection, union, subtraction, and so on.</li></ul>
+order to implement distributed algorithms.<br/><br/>(News: locking with key-granularity is now planned)<h1><a name="Multiple databases support">Multiple databases support</a></h1>Another synchronization primitive is the support for multiple DBs. 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="Redis Data Types">Redis Data Types</a></h1>Redis supports the following three data types as values:<br/><br/><ul><li> Strings: just any sequence of bytes. Redis strings are binary safe so they can not just hold text, but images, compressed data and everything else.</li><li> Lists: lists of strings, with support for operations like append a new string on head, on tail, list length, obtain a range of elements, truncate the list to a given length, sort the list, and so on.</li><li> Sets: an unsorted set of strings. It is possible to add or delete elements from a set, to perform set intersection, union, subtraction, and so on.</li></ul>
 Values can be Strings, Lists or Sets. Keys can be a subset of strings not containing newlines (&quot;\n&quot;) and spaces (&quot; &quot;).<br/><br/>Note that sometimes strings may hold numeric vaules that must be parsed by
 Redis. An example is the INCR command that atomically increments the number
 stored at the specified key. In this case Redis is able to handle integers