Merge pull request #1031 from BrianRossmajer/patch-1

Noting in documentation when client.duplicate() might be used

Author: BridgeAR

README.md

@@ -658,6 +658,33 @@ the second word as first parameter:
 Duplicate all current options and return a new redisClient instance. All options passed to the duplicate function are going to replace the original option.
 If you pass a callback, duplicate is going to wait until the client is ready and returns it in the callback. If an error occurs in the meanwhile, that is going to return an error instead in the callback.
 
+One example of when to use duplicate() would be to accomodate the connection- 
+blocking redis commands BRPOP, BLPOP, and BRPOPLPUSH.  If these commands
+are used on the same redisClient instance as non-blocking commands, the 
+non-blocking ones may be queued up until after the blocking ones finish.
+
+    var Redis=require('redis');
+    var client = Redis.createClient();
+    var clientBlocking = client.duplicate();
+
+    var get = function() {
+        console.log("get called");
+        client.get("any_key",function() { console.log("get returned"); });
+        setTimeout( get, 1000 );
+    };
+    var brpop = function() {
+        console.log("brpop called");
+        clientBlocking.brpop("nonexistent", 5, function() {
+            console.log("brpop return");
+            setTimeout( brpop, 1000 );
+        });
+    };
+    get();
+    brpop();
+    
+Another reason to use duplicate() is when multiple DBs on the same server are 
+accessed via the redis SELECT command.  Each DB could use its own connection.
+    
 ## client.send_command(command_name[, [args][, callback]])
 
 All Redis commands have been added to the `client` object. However, if new commands are introduced before this library is updated,