Merge branch 'master' into serializer

Author: nicolasff

README.markdown

@@ -20,9 +20,9 @@ phpize
 make && make install
 </pre>
 
-You can generate a debian package for PHP5, accessible from Apache 2 by running `./mkdeb-apache2.sh`.
+You can generate a debian package for PHP5, accessible from Apache 2 by running `./mkdeb-apache2.sh` or with `dpkg-buildpackage` or `svn-buildpackage`.
 
-This extension exports a single class, `Redis`.
+This extension exports a single class, `Redis` (and `RedisException` used in case of errors).
 
 Install on OSX
 ==============
@@ -43,10 +43,15 @@ Session handler (new)
 phpredis can be used to store PHP sessions. To do this, configure `session.save_handler` and `session.save_path` in your php.ini to tell phpredis where to store the sessions:
 <pre>
 session.save_handler = redis
-session.save_path = "tcp://host1:6379?weight=1, tcp://host2:6379?weight=2, tcp://host3:6379?weight=2"
+session.save_path = "tcp://host1:6379?weight=1, tcp://host2:6379?weight=2&timeout=2.5, tcp://host3:6379?weight=2"
 </pre>
 
-`session.save_path` can have a simple `host:port` format too, but you need to provide the `tcp://` scheme if you want to use the weight parameter.
+`session.save_path` can have a simple `host:port` format too, but you need to provide the `tcp://` scheme if you want to use the parameters. The following parameters are available:
+
+* weight (integer): the weight of a host is used in comparison with the others in order to customize the session distribution on several hosts. If host A has twice the weight of host B, it will get twice the amount of sessions. In the example, *host1* stores 20% of all the sessions (1/(1+2+2)) while *host2* and *host3* each store 40% (2/1+2+2). The target host is determined once and for all at the start of the session, and doesn't change. The default weight is 1.
+* timeout (float): the connection timeout to a redis host, expressed in seconds. If the host is unreachable in that amount of time, the session storage will be unavailable for the client. The default timeout is very high (86400 seconds).
+
+Sessions have a lifetime expressed in seconds and stored in the INI variable "session.gc_maxlifetime". You can change it with [`ini_set()`](http://php.net/ini_set).
 
 Error handling
 ==============
@@ -63,7 +68,9 @@ Creates a Redis client
 
 ##### *Example*
 
+<pre>
 $redis = new Redis();
+</pre>
 
 ## connect, open
 ##### *Description*
@@ -82,10 +89,46 @@ Connects to a Redis instance.
 
 ##### *Example*
 
+<pre>
 $redis->connect('127.0.0.1', 6379);
 $redis->connect('127.0.0.1'); // port 6379 by default
 $redis->connect('127.0.0.1', 6379, 2.5); // 2.5 sec timeout.
 $redis->connect('/tmp/redis.sock'); // unix domain socket.
+</pre>
+
+## pconnect, popen
+##### *Description*
+
+Connects to a Redis instance or reuse a connection already established with `pconnect`/`popen`.
+
+The connection will not be closed on `close` or end of request until the php process ends.
+So be patient on to many open FD's (specially on redis server side) when using persistent
+connections on many servers connecting to one redis server.
+
+Also more than one persistent connection can be made identified by either host + port + timeout
+or unix socket + timeout.
+
+This feature is not available in threaded versions. `pconnect` and `popen` then working like their non
+persistent equivalents.
+
+##### *Parameters*
+
+*host*: string. can be a host, or the path to a unix domain socket  
+*port*: int, optional  
+*timeout*: float, value in seconds (optional, default is 0 meaning unlimited)  
+
+##### *Return Value*
+
+*BOOL*: `TRUE` on success, `FALSE` on error.
+
+##### *Example*
+
+<pre>
+$redis->pconnect('127.0.0.1', 6379);
+$redis->pconnect('127.0.0.1'); // port 6379 by default - same connection like before.
+$redis->pconnect('127.0.0.1', 6379, 2.5); // 2.5 sec timeout and would be another connection then the two before.
+$redis->pconnect('/tmp/redis.sock'); // unix domain socket - would be another connection then the three before.
+</pre>
 
 
 ## setOption
@@ -152,7 +195,9 @@ Get the value related to the specified key
 
 ##### *Examples*
 
+<pre>
 $redis->get('key');
+</pre>
 
 ## set
 ##### Description

common.h

@@ -145,6 +145,7 @@ typedef struct {
     double         timeout;
     int            failed;
     int            status;
+    int            persistent;
 
     int            serializer;