From 6674e3b91035fc9e0c19956119fe918ba115608d Mon Sep 17 00:00:00 2001 From: antirez Date: Wed, 15 Dec 2010 15:59:45 +0100 Subject: [PATCH] added new HTML doc pages --- doc/BrpoplpushCommand.html | 39 ++++++++++++++ doc/GetbitCommand.html | 39 ++++++++++++++ doc/HmgetCommand.html | 40 +++++++++++++++ doc/NonexistentCommands.html | 51 +++++++++++++++++++ doc/RedisCLI.html | 37 ++++++++++++++ doc/RedisPipelining.html | 93 ++++++++++++++++++++++++++++++++++ doc/RedisStatus.html | 56 ++++++++++++++++++++ doc/Redis_2_0_0_Changelog.html | 62 +++++++++++++++++++++++ doc/Redis_2_0_Whats_new.html | 59 +++++++++++++++++++++ doc/SetbitCommand.html | 45 ++++++++++++++++ doc/SetrangeCommand.html | 58 +++++++++++++++++++++ doc/StrlenCommand.html | 39 ++++++++++++++ 12 files changed, 618 insertions(+) create mode 100644 doc/BrpoplpushCommand.html create mode 100644 doc/GetbitCommand.html create mode 100644 doc/HmgetCommand.html create mode 100644 doc/NonexistentCommands.html create mode 100644 doc/RedisCLI.html create mode 100644 doc/RedisPipelining.html create mode 100644 doc/RedisStatus.html create mode 100644 doc/Redis_2_0_0_Changelog.html create mode 100644 doc/Redis_2_0_Whats_new.html create mode 100644 doc/SetbitCommand.html create mode 100644 doc/SetrangeCommand.html create mode 100644 doc/StrlenCommand.html diff --git a/doc/BrpoplpushCommand.html b/doc/BrpoplpushCommand.html new file mode 100644 index 000000000..ba45eab00 --- /dev/null +++ b/doc/BrpoplpushCommand.html @@ -0,0 +1,39 @@ + + + + + + + +
+ + + +
+
+ +BrpoplpushCommand: Contents
  BRPOPLPUSH _srckey_ _dstkey_ _timeout_ (Redis >
    Return value +
+ +

BrpoplpushCommand

+ +
+ +
+ +
+ +

BRPOPLPUSH _srckey_ _dstkey_ _timeout_ (Redis >

2.1.8) = +Time complexity: O(1)
Blocking version of the RPOPLPUSH command. Atomically removes and returnsthe last element (tail) of the source list at srckey, and as a side effect pushes the returned element in the head of the list at dstkey.
+If the source list is empty, the client blocks until another client pushes against the source list. Of course in such a case the push operation against the destination list will be performed after the command unblocks detecting a push against the source list.

Note that the command returns an error if the target key already exists but is not a list. The error is delayed at the time the push operation is attempted, that is, immediately if the source list is not empty, or when the first push against the source list happens in the case the command would block.

The timeout value can be 0 or a positive integer value. When it is zero the command will block forever, until something is pushed against srckey. Otherwise the command will wait the specified number of seconds at max, returning an nil value when the timeout expires.

The source and destination of the list can be the same, having the effect of rotating the list. Please check RPOPLPUSH for more information.

Return value

Bulk reply +
+ +
+
+ + + diff --git a/doc/GetbitCommand.html b/doc/GetbitCommand.html new file mode 100644 index 000000000..1fe81bcf1 --- /dev/null +++ b/doc/GetbitCommand.html @@ -0,0 +1,39 @@ + + + + + + + +
+ + + +
+
+ +GetbitCommand: Contents
  GETBIT _key_ _offset_ (Redis >
    Return value +
+ +

GetbitCommand

+ +
+ +
+ +
+ +

GETBIT _key_ _offset_ (Redis >

2.1.8) = +Time complexity: O(1)
Returns the bit value at offset in the string value stored at key.
+When offset is beyond the string length, the string is assumed to be a contiguous space with 0 bits. When key does not exist it is assumed to be an empty string, so offset is always out of range and the value is also assumed to be a contiguous space with 0 bits.

Return value

Integer reply, specifically: the bit value stored at offset. +
+ +
+
+ + + diff --git a/doc/HmgetCommand.html b/doc/HmgetCommand.html new file mode 100644 index 000000000..fb624445c --- /dev/null +++ b/doc/HmgetCommand.html @@ -0,0 +1,40 @@ + + + + + + + +
+ + + +
+
+ +HmgetCommand: Contents
  HMGET _key_ _field1_ ... _fieldN_ (Redis >
    Return value +
+ +

HmgetCommand

+ +
+ +
+ +
+ #sidebar HashCommandsSidebar

HMGET _key_ _field1_ ... _fieldN_ (Redis >

1.3.10) = +Time complexity: O(N) (with N being the number of fields)
Retrieve the values associated to the specified fields.
+
If some of the specified fields do not exist, nil values are returned.Non existing keys are considered like empty hashes.
+

Return value

Multi Bulk Reply specifically a list of all the values associated with the specified fields, in the same order of the request. + +
+ +
+
+ + + diff --git a/doc/NonexistentCommands.html b/doc/NonexistentCommands.html new file mode 100644 index 000000000..47797a002 --- /dev/null +++ b/doc/NonexistentCommands.html @@ -0,0 +1,51 @@ + + + + + + + +
+ + + +
+
+ +NonexistentCommands: Contents
  HGETSET
  SET with expire
  ZADDNX +
+ +

NonexistentCommands

+ +
+ A list of commands that don't exist in Redis, but can be accomplished in a different way. +
+ +
+ +This is a list of commands that don't exist in Redis, but can be accomplished in a different way, usually by means of WATCH/MULTI/EXEC.

For better performance, you can pipeline multiple commands.

HGETSET

GETSET for Hashes.

+WATCH foo
+old_value = HGET foo field
+MULTI
+HSET foo field new_value
+EXEC
+

SET with expire

See SETEX.

ZADDNX

Add an element to a sorted set, only if the element doesn't already exist (by default, ZADD would update the element's score if it already exists). See thread.

+WATCH foo
+score = ZSCORE foo bar
+IF score != NIL
+  MULTI
+  ZADD foo 1 bar
+  EXEC
+ENDIF
+
+
+ +
+
+ + + diff --git a/doc/RedisCLI.html b/doc/RedisCLI.html new file mode 100644 index 000000000..faac54952 --- /dev/null +++ b/doc/RedisCLI.html @@ -0,0 +1,37 @@ + + + + + + + +
+ + + +
+
+ +RedisCLI: Contents
  Redis CLI +
+ +

RedisCLI

+ +
+ Redis Command Line Interface +
+ +
+ +

Redis CLI

+
+ +
+
+ + + diff --git a/doc/RedisPipelining.html b/doc/RedisPipelining.html new file mode 100644 index 000000000..caaee6c0e --- /dev/null +++ b/doc/RedisPipelining.html @@ -0,0 +1,93 @@ + + + + + + + +
+ + + +
+
+ +RedisPipelining: Contents
  Request/Response protocols and RTT
  Redis Pipelining
  Some benchmark
  Pipelining VS other multi-commands +
+ +

RedisPipelining

+ +
+ +
+ +
+

Request/Response protocols and RTT

+Redis is a TCP server using the client-server model and what is called a Request/Response protocol.

This means that usually a request is accomplished with the following steps: +
  • The client sends a query to the server, and reads from the socket, usually in a blocking way, for the server response.
  • The server processes the command and sends the response back to the server.
So for instance a four commands sequence is something like this: +
  • Client: INCR X
  • Server: 1
  • Client: INCR X
  • Server: 2
  • Client: INCR X
  • Server: 3
  • Client: INCR X
  • Server: 4
Clients and Servers are connected via a networking link. Such a link can be very fast (a loopback interface) or very slow (a connection established over the internet with many hops between the two hosts). Whatever the network latency is, there is a time for the packets to travel from the client to the server, and back from the server to the client to carry the reply.

This time is called RTT (Round Trip Time). It is very easy to see how this can affect the performances when a client needs to perform many requests in a row (for instance adding many elements to the same list, or populating a database with many keys). For instance if the RTT time is 250 milliseconds (in the case of a very slow link over the internet), even if the server is able to process 100k requests per second, we'll be able to process at max four requests per second.

If the interface used is a loopback interface, the RTT is much shorter (for instance my host reports 0,044 milliseconds pinging 127.0.0.1), but it is still a lot if you need to perform many writes in a row.

Fortunately there is a way to improve this use cases. +

Redis Pipelining

+A Request/Response server can be implemented so that it is able to process new requests even if the client didn't already read the old responses. This way it is possible to send multiple commands to the server without waiting for the replies at all, and finally read the replies in a single step.

This is called pipelining, and is a technique widely in use since many decades. For instance many POP3 protocol implementations already supported this feature, dramatically speeding up the process of downloading new emails from the server.

Redis supports pipelining since the very early days, so whatever version you are running, you can use pipelining with Redis. This is an example using the raw netcat utility: +
+$ (echo -en "PING\r\nPING\r\nPING\r\n"; sleep 1) | nc localhost 6379
++PONG
++PONG
++PONG
+
+This time we are not paying the cost of RTT for every call, but just one time for the three commands.

To be very explicit, with pipelining the order of operations of our very first example will be the following: +
  • Client: INCR X
  • Client: INCR X
  • Client: INCR X
  • Client: INCR X
  • Server: 1
  • Server: 2
  • Server: 3
  • Server: 4
IMPORTANT NOTE: while the client sends commands using pipelining, the server will be forced to queue the replies, using memory. So if you need to send many many commands with pipelining it's better to send this commands up to a given reasonable number, for instance 10k commands, read the replies, and send again other 10k commands and so forth. The speed will be nearly the same, but the additional memory used will be at max the amount needed to queue the replies for this 10k commands. +

Some benchmark

+In the following benchmark we'll use the Redis Ruby client, supporting pipelining, to test the speed improvement due to pipelining: +
+require 'rubygems'
+require 'redis'
+
+def bench(descr)
+    start = Time.now
+    yield
+    puts "#{descr} #{Time.now-start} seconds"
+end
+
+def without_pipelining
+    r = Redis.new
+    10000.times {
+        r.ping
+    }
+end
+
+def with_pipelining
+    r = Redis.new
+    r.pipelined {
+        10000.times {
+            r.ping
+        }
+    }
+end
+
+bench("without pipelining") {
+    without_pipelining
+}
+bench("with pipelining") {
+    with_pipelining
+}
+
+Running the above simple script will provide this figures in my Mac OS X system, running over the loopback interface, where pipelining will provide the smallest improvement as the RTT is already pretty low: +
+without pipelining 1.185238 seconds
+with pipelining 0.250783 seconds
+
+As you can see using pipelining we improved the transfer by a factor of five. +

Pipelining VS other multi-commands

+Often we get requests about adding new commands performing multiple operations in a single pass. +For instance there is no command to add multiple elements in a set. You need calling many times SADD.

With pipelining you can have performances near to an MSADD command, but at the same time we'll avoid bloating the Redis command set with too many commands. An additional advantage is that the version written using just SADD will be ready for a distributed environment (for instance Redis Cluster, that is in the process of being developed) just dropping the pipelining code. +
+ +
+
+ + + diff --git a/doc/RedisStatus.html b/doc/RedisStatus.html new file mode 100644 index 000000000..9131cea10 --- /dev/null +++ b/doc/RedisStatus.html @@ -0,0 +1,56 @@ + + + + + + + +
+ + + +
+
+ +RedisStatus: Contents
  Redis Status Page
  How stable are the alpha previews?
  How to obtain a 2.2-alpha preview
  ETA for Redis 2.2?
  When will we be able to see a working version of Redis Cluster? +
+ +

RedisStatus

+ +
+ +
+ +
+

Redis Status Page

Hello! Redis uses versions composed of three numbers separated by a dot: major.minor.patchlevel.

When the minor is an odd number, it is used for an unstable release, so stable releases are for instance 1.2, 2.0, and so forth.

This is the status of the different Redis versions currently available:

  • 1.2 is the legacy redis stable release, now it is completely obsoleted by Redis 2.0. Redis 2.0 is almost completely back compatible with 1.2 so upgrading is usually not a problem. Still 1.2 is believed to be a very stable release that works well, so if you are using it in production with code that probably will not modified to use more advanced Redis features available in 2.0, it makes sense to take 1.2 running. For everything new, it's better to start with 2.0.
+
  • 2.0 is the current stable release. It is better than 1.2 in more or less everything: more features, more mature code, better replication, better persistence, and so forth. It is currently what most users should use, unless they really need features that are only available into an unstable release.
+
  • 2.1 is the current unstable release, and there are no tar.gz for this release, you need to download it from git. Warning: the master branch in git may work most of the time but is NOT what you should use. What's better instead is to use the 2.2-alpha tags: every time Redis 2.1.x is stable enough and the new features merged passed all the tests for a couple of weeks, and we didn't received severe bug reports from users, we tag master as 2.2-alpha number, where number is simply a progressive number. Just pick this number.
+

How stable are the alpha previews?

+Well it is surely ok for development, but it is not recommended for production. Still there are many users that trust Redis development process so much to use alpha releases in production, but this is up to you, we don't give any guarantee ;)

How to obtain a 2.2-alpha preview

Simply using git: +
+$ git clone git://github.com/antirez/redis.git
+Initialized empty Git repository in /tmp/redis/.git/
+...
+
+Then you can list all the branches matching 2.1-alpha with: +
+cd redis
+$ git tag | grep 2.2-alpha
+2.2-alpha0
+2.2-alpha1
+2.2-alpha2
+
+At this point you can just use git checkout tagname, substituting tagname with 2.2-alphaX where X is the greater progressive number you see in the listing.

ETA for Redis 2.2?

+Redis 2.2 is planned to enter the release candidate stage before the end of the 2010.

When will we be able to see a working version of Redis Cluster?

+I'm already working at it, I mean not just designing, but writing code. In three months we should have some kind of experimental version, while in six months we should have the first release candidate.

Probably the first stable release of Redis with working cluster will be called 3.0, but I'll try to merge it into 2.2 as an experimental support if we'll be sure there is no impact in the stability of the system when clustering is not used. +
+ +
+
+ + + diff --git a/doc/Redis_2_0_0_Changelog.html b/doc/Redis_2_0_0_Changelog.html new file mode 100644 index 000000000..bc4e3c0d6 --- /dev/null +++ b/doc/Redis_2_0_0_Changelog.html @@ -0,0 +1,62 @@ + + + + + + + +
+ + + +
+
+ +Redis_2_0_0_Changelog: Contents
  Redis 2.0: What's new?
      MULTI/EXEC
      Blocking pop
      Publish/subscribe
      Hashes
      Virtual Memory
      Contributors
      Special Thanks
      DOWNLOAD +
+ +

Redis_2_0_0_Changelog

+ +
+ +
+ +
+

Redis 2.0: What's new?

The release of Redis 2.0 marks a major milestone in Redis development. Apart from an endless list of new features, there are some major ones that deserve to be highlighted.

It's worth to mention that while Redis 2.0.0 just reached its first stable release, Redis 2.2.0 is near to reach feature freeze, so ... be prepared for new exiting things in very short time!

MULTI/EXEC

+The MULTI/EXEC family of commands were added to fulfill the need to execute multiple commands as a single atomic block. +Because all commands inside a MULTI/EXEC block are serialized and executed sequentially, it is not possible that another +client request is served in the middle of executing this block. All commands are executed one after the other when +EXEC is called, which makes sure either all or no commands are executed, independent of the state of the client connection.

More on MULTI/EXEC: + +Note that WATCH, a CAS (check and set) variant of MULTI/EXEC will be available on 2.2.0 and is not part of 2.0.0.

Blocking pop

+The commands BLPOP and BRPOP were added to support popping from a list in a blocking fashion. This means the client +connection will be blocked for a certain amount of time until another client pushes an item on a list. These commands +are frequently used in producer/consumer scenarios.

More on blocking pop: + +

Publish/subscribe

+The family of publish/subscribe commands let clients publish messages onto channels and subscribe to receive all messages +that are published on channels. Also included are commands to receive all messages for which the channel matches a given pattern.

More on publish/subscribe: + +

Hashes

+This new datatype allows to store multiple key/value pairs on a single key. Together with the list of regular commands you +would expect for such a datatype (HSET, HGET, HDEL, HLEN, HKEYS, ...), it is also possible to use the values inside a hash +for any SORT operation.

More on hashes: + +

Virtual Memory

+Redis Virtual Memory allows users to grow their dataset beyond the limits of their RAM.

More on virtual memory: + +

Contributors

  • Salvatore Sanfilippo
  • Pieter Noordhuis
  • Antonio Ognio
  • Alex McHale
  • Michel Martens
  • Damian Janowski
  • Bruno Deferrari
  • Ashley Martens
  • Derek Collison
  • Damian Janowski
  • Jeremy Zawodny
  • Konstantin Merenkov
  • Michel Martens
  • Sam Hendley
+

Special Thanks

+Thanks to VMware sponsoring the work of Salvatore and Pieter, and the Redis community of users and client library developers. Redis 2.0.0 was possible only thanks to your support.

DOWNLOAD

+You can grab Redis 2.0.0 from Google Code.

It is also tagged on Git. +
+ +
+
+ + + diff --git a/doc/Redis_2_0_Whats_new.html b/doc/Redis_2_0_Whats_new.html new file mode 100644 index 000000000..95c5d95ed --- /dev/null +++ b/doc/Redis_2_0_Whats_new.html @@ -0,0 +1,59 @@ + + + + + + + +
+ + + +
+
+ +Redis_2_0_Whats_new: Contents
  Redis 2.0: What's new?
      MULTI/EXEC
      Blocking pop
      Publish/subscribe
      Hashes
      Virtual Memory
    Contributors +
+ +

Redis_2_0_Whats_new

+ +
+ +
+ +
+

Redis 2.0: What's new?

The release of Redis 2.0 marks a major milestone in Redis development. Apart from an endless list of new features, there are some major ones that deserve to be highlighted.

MULTI/EXEC

+The MULTI/EXEC family of commands were added to fulfill the need to execute multiple commands as a single atomic block. +Because all commands inside a MULTI/EXEC block are serialized and executed sequentially, it is not possible that another +client request is served in the middle of executing this block. All commands are executed one after the other when +EXEC is called, which makes sure either all or no commands are executed, independent of the state of the client connection.

More on MULTI/EXEC: + +

Blocking pop

+The commands BLPOP and BRPOP were added to support popping from a list in a blocking fashion. This means the client +connection will be blocked for a certain amount of time until another client pushes an item on a list. These commands +are frequently used in producer/consumer scenarios.

More on blocking pop: + +

Publish/subscribe

+The family of publish/subscribe commands let clients publish messages onto channels and subscribe to receive all messages +that are published on channels. Also included are commands to receive all messages for which the channel matches a given pattern.

More on publish/subscribe: + +

Hashes

+This new datatype allows to store multiple key/value pairs on a single key. Together with the list of regular commands you +would expect for such a datatype (HSET, HGET, HDEL, HLEN, HKEYS, ...), it is also possible to use the values inside a hash +for any SORT operation.

More on hashes: + +

Virtual Memory

+Redis Virtual Memory allows users to grow their dataset beyond the limits of their RAM.

More on virtual memory: + +

Contributors

  • Salvatore Sanfilippo
  • Pieter Noordhuis
  • Antonio Ognio
  • Alex McHale
  • Michel Martens
  • Damian Janowski
  • Bruno Deferrari
  • Ashley Martens
  • Derek Collison
  • Damian Janowski
  • Jeremy Zawodny
  • Konstantin Merenkov
  • Michel Martens
  • Sam Hendley
+
+ +
+
+ + + diff --git a/doc/SetbitCommand.html b/doc/SetbitCommand.html new file mode 100644 index 000000000..bcec9e222 --- /dev/null +++ b/doc/SetbitCommand.html @@ -0,0 +1,45 @@ + + + + + + + +
+ + + +
+
+ +SetbitCommand: Contents
  SETBIT _key_ _offset_ _value_ (Redis >
    Return value +
+ +

SetbitCommand

+ +
+ +
+ +
+ +

SETBIT _key_ _offset_ _value_ (Redis >

2.1.8) = +Time complexity: O(1)
Sets or clears the bit at offset in the string value stored at key.
+The bit is either set or cleared depending on value, which can be either 0 or 1. When key does not exist, a new string value is created. The string is grown to make sure it can hold a bit at offset. The offset argument is required to be greater than or equal to 0, and is limited to 232-1 (which limits bitmaps to 512MB). +When the string at key is grown, added bits are set to 0.

Warning: When setting the last possible bit (offset equal to 232-1) and the string value stored at key does not yet hold a string value, or holds a small string value, Redis needs to allocate all intermediate memory which can block the server for some time. +On a 2010 Macbook Pro, setting bit number 232-1 (512MB allocation) takes ~300ms, +setting bit number 230-1 (128MB allocation) takes ~80ms, +setting bit number 228-1 (32MB allocation) takes ~30ms and +setting bit number 226-1 (8MB allocation) takes ~8ms. +Note that once this first allocation is done, subsequent calls to SETBIT for the same key will not have the allocation overhead.

Return value

Integer reply, specifically: the original bit value stored at offset. +
+ +
+
+ + + diff --git a/doc/SetrangeCommand.html b/doc/SetrangeCommand.html new file mode 100644 index 000000000..1bd70b4e9 --- /dev/null +++ b/doc/SetrangeCommand.html @@ -0,0 +1,58 @@ + + + + + + + +
+ + + +
+
+ +SetrangeCommand: Contents
  SETRANGE _key_ _offset_ _value_ (Redis >
    Examples
    Patterns
    Return value +
+ +

SetrangeCommand

+ +
+ +
+ +
+ #sidebar StringCommandsSidebar

SETRANGE _key_ _offset_ _value_ (Redis >

2.1.8) = +Time complexity: O(1) not counting the time taken to copy the new string in place, as usually this string is small so the amoritzed time is O(1). Otheriwse O(M) with M being the length of the value argument
Overwrites part of a string at key starting at the specified offset,for all the length of value.If the offset is over the old length of the string, the string is paddedwith zero bytes until needed. Non existing keys are considered likealready containing an empty string.
+

Examples

First example, basic usage setting a range.

+redis> set foo "Hello World"
+OK
+redis> setrange foo 6 "Redis"
+(integer) 11
+redis> get foo
+"Hello Redis"
+
Example of the zero padding behavior.

+redis> del foo
+(integer) 1
+redis> setrange foo 10 bar
+(integer) 13
+redis> get foo
+"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00bar"
+
Note that the maximum offset that you can set is 536870911 as Redis Strings are limited to 512 megabytes. You can still create longer arrays of values using multiple keys.

Warning: When setting the last possible byte and the string value stored at key does not yet hold a string value, or holds a small string value, Redis needs to allocate all intermediate memory which can block the server for some time. +On a 2010 Macbook Pro, setting byte number 536870911 (512MB allocation) takes ~300ms, +setting byte number 134217728 (128MB allocation) takes ~80ms, +setting bit number 33554432 (32MB allocation) takes ~30ms and +setting bit number 8388608 (8MB allocation) takes ~8ms. +Note that once this first allocation is done, subsequent calls to SETRANGE for the same key will not have the allocation overhead.

Patterns

Thanks to SETRANGE and the analogous GETRANGE command you can use Redis strings as a linear array of memory with O(1) random access. This is a very fast and efficient storage in many real world use cases.

Return value

Integer reply, specifically: the length of the string after it was modified by the command. + +
+ +
+
+ + + diff --git a/doc/StrlenCommand.html b/doc/StrlenCommand.html new file mode 100644 index 000000000..1a580f448 --- /dev/null +++ b/doc/StrlenCommand.html @@ -0,0 +1,39 @@ + + + + + + + +
+ + + +
+
+ +StrlenCommand: Contents
  STRLEN _key_ (Redis >
    Return value +
+ +

StrlenCommand

+ +
+ +
+ +
+ #sidebar StringCommandsSidebar

STRLEN _key_ (Redis >

2.1.8) = +Time complexity: O(1)
Returns the length of the string stored at the specified key.
+

Return value

Integer reply, specifically: the length of the string. + +
+ +
+
+ + + -- GitLab