readme update from #125

README.rst

@@ -5,15 +5,16 @@ libmc
 |status| |pypiv| |pyversions| |wheel| |license|
 
 libmc is a memcached client library for Python without any other
-dependencies in runtime. It's mainly written in C++ and Cython. libmc
-can be considered as a drop in replacement for libmemcached and
+dependencies at runtime. It's mainly written in C++ and Cython and
+can be considered a drop in replacement for libmemcached and
 `python-libmemcached <https://github.com/douban/python-libmemcached>`__.
 
-libmc is developing and maintaining by Douban Inc. Currently, It is
-working in production environment, powering all web traffics in
-douban.com. Realtime `benchmark
-result <https://travis-ci.org/douban/libmc/builds/57124335#L1611>`__ is
-available on travis.
+libmc is developed and maintained by Douban Inc. Currently, it is
+working in a production environment, powering all web traffic on
+`douban.com <https://www.semrush.com/website/douban.com/overview/>`__. [#]_
+
+.. [#] The link not an endorsement of the traffic estimate site's accuracy, just
+   a publicly available reference point
 
 Build and Installation
 ----------------------
@@ -37,14 +38,14 @@ Usage:
 Under the hood
 --------------
 
-Under the hood, libmc consists of 2 parts: an internal fully-functional
+Under the hood, libmc consists of 2 parts: an internal, fully-functional
 memcached client implementation in C++ and a Cython wrapper around that
 implementation. Dynamic memory allocation and memory-copy are slow, so
-we tried our best to avoid them. The ``set_multi`` command is not
-natively supported by the `memcached
+we've tried our best to avoid them. libmc also supports the ``set_multi``
+command, which is not natively supported by the `memcached
 protocol <https://github.com/memcached/memcached/blob/master/doc/protocol.txt>`__.
-Some techniques are applied to make ``set_multi`` command extremely fast
-in libmc (compared to some other similiar libraries).
+Some techniques have been applied to make ``set_multi`` command extremely fast
+in libmc (compared to similiar libraries).
 
 Configuration
 -------------
@@ -77,24 +78,23 @@ Configuration
     mc.config(MC_RETRY_TIMEOUT, 5)  # 5 s
 
 
--  ``servers``: is a list of memcached server addresses. Each address
-   can be in format of ``hostname[:port] [alias]``. ``port`` and ``alias``
-   are optional. If ``port`` is not given, default port ``11211`` will
-   be used. ``alias`` will be used to compute server hash if given,
-   otherwise server hash will be computed based on ``host`` and ``port``
-   (i.e.: If ``port`` is not given or it is equal to ``11211``, ``host``
-   will be used to compute server hash. If ``port`` is not equal to ``11211``,
-   ``host:port`` will be used).
--  ``do_split``: Memcached server will refuse to store value if size >=
-   1MB, if ``do_split`` is enabled, large value (< 10 MB) will be
-   splitted into several blocks. If the value is too large (>= 10 MB),
-   it will not be stored. default: ``True``
--  ``comp_threshold``: All kinds of values will be encoded into string
-   buffer. If ``buffer length > comp_threshold > 0``, it will be
-   compressed using zlib. If ``comp_threshold = 0``, string buffer will
-   never be compressed using zlib. default: ``0``
--  ``noreply``: Whether to enable memcached's ``noreply`` behaviour.
-   default: ``False``
+-  ``servers``: a list of memcached server addresses. Each address
+   should be formated as ``hostname[:port] [alias]``, where ``port`` and
+   ``alias`` are optional. If ``port`` is not given, the default port ``11211``
+   will be used. If given, ``alias`` will be used to compute the server hash,
+   which would otherwise be computed based on ``host`` and ``port``
+   (i.e. whichever portion is given).
+-  ``do_split``: splits large values (up to 10MB) into chunks (<1MB). The
+   memcached server implementation will not store items larger than 1MB,
+   however in some environments it is beneficial to shard up to 10MB of data.
+   Attempts to store more than that are ignored. Default: ``True``.
+-  ``comp_threshold``: compresses large values using zlib. If
+   ``buffer length > comp_threshold > 0`` (in bytes), the buffer will be
+   compressed. If ``comp_threshold == 0``, the string buffer will never be
+   compressed. Default: ``0``
+-  ``noreply``: controls memcached's
+   ``noreply`` `feature <https://github.com/memcached/memcached/wiki/CommonFeatures#noreplyquiet>`__.
+   Default: ``False``
 -  ``prefix``: The key prefix. default: ``''``
 -  ``hash_fn``: hashing function for keys. possible values:
 
@@ -110,16 +110,16 @@ Configuration
    implementions in libmemcached.
 
 -  ``failover``: Whether to failover to next server when current server
-   is not available. default: ``False``
+   is not available. Default: ``False``
 
 -  ``MC_POLL_TIMEOUT`` Timeout parameter used during set/get procedure.
-   (default: ``300`` ms)
+   Default: ``300`` ms
 -  ``MC_CONNECT_TIMEOUT`` Timeout parameter used when connecting to
-   memcached server on initial phase. (default: ``100`` ms)
--  ``MC_RETRY_TIMEOUT`` When a server is not available dur to server-end
-   error. libmc will try to establish the broken connection in every
-   ``MC_RETRY_TIMEOUT`` s until the connection is back to live.(default:
-   ``5`` s)
+   memcached server in the initial phase. Default: ``100`` ms
+-  ``MC_RETRY_TIMEOUT`` When a server is not available due to server-end
+   error, libmc will try to establish the broken connection in every
+   ``MC_RETRY_TIMEOUT`` s until the connection is back to live. Default:
+   ``5`` s
 
 **NOTE:** The hashing algorithm for host mapping on continuum is always
 md5.
@@ -140,7 +140,7 @@ FAQ
 Does libmc support PHP?
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-No. But if you like, you can write a wrapper for PHP based on the C++
+No, but, if you like, you can write a wrapper for PHP based on the C++
 implementation.
 
 Is Memcached binary protocol supported ?
@@ -151,7 +151,7 @@ No. Only Memcached ASCII protocol is supported currently.
 Why reinventing the wheel?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Before libmc, we're using
+Before libmc, we were using
 `python-libmemcached <https://github.com/douban/python-libmemcached>`__,
 which is a python extention for
 `libmemcached <http://libmemcached.org/libMemcached.html>`__.
@@ -161,21 +161,32 @@ still some unsolved bugs.
 Is libmc thread-safe ?
 ^^^^^^^^^^^^^^^^^^^^^^
 
-libmc is a single-threaded memcached client. If you initialize a libmc
-client in one thread but reuse that in another thread, a Python
-Exception ``ThreadUnsafe`` will raise in Python.
+Yes. ``libmc.ThreadedClient`` is a thread-safe client implementation. To hold
+access for more than one request, ``libmc.ClientPool`` can be used with Python
+``with`` statements. ``libmc.Client``, however, is a single-threaded memcached
+client. If you initialize a standard client in one thread but reuse that in
+another thread, a Python ``ThreadUnsafe`` Exception will be raised.
 
 Is libmc compatible with gevent?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Yes, with the help of `greenify <https://github.com/douban/greenify>`__,
 libmc is friendly to gevent. Read ``tests/shabby/gevent_issue.py`` for
-details.
+details. ``libmc.ThreadedClient`` and ``libmc.ClientPool`` are not compatible.
+[#]_
+
+.. [#] In order to use a single executable for multiple greenlet contexts,
+   gevent has to `copy thread memory
+   <https://github.com/python-greenlet/greenlet/blob/937f150e07823ee03344aeeb5111c0bb371a831d/src/greenlet/greenlet.cpp#L105>`__
+   to and from the same stack space. This doesn't affect Python references,
+   which are handed off through gevent, but makes it impossible for shared
+   libraries to pass memory addresses across greenlets, which is required for
+   the worker pool.
 
 **Notice:**
 
-`gevent.monkey.patch_all()` will override
-`threading.current_thread().ident` to Greenlet's ID,
+``gevent.monkey.patch_all()`` will override
+``threading.current_thread().ident`` to Greenlet's ID,
 this will cause libmc to throw a ThreadUnSafe error
 or run into dead lock, you should only patch the things
 that you need, e.g.