fix #82, #64 and #21: docs on replication

diff --git a/BUGS.md b/BUGS.md
new file mode 100644 (file)
index 0000000..e285ac1
--- /dev/null
+++ b/BUGS.md
@@ -0,0 +1,38 @@
+# Bugs, Known Issues and Insufficiencies
+
+## libhashkit
+
+### MurMur
+
+Hashkit's MurMur/MurMur3 are limited to the lower 32 bits.
+
+### crc32
+
+Commit "[More Hashing methods](./commits/1207354f)" from October 2007
+first released in v0.8, which main intention seems to have been to add 
+FNV1 hash algos, changed the result of the crc32 hash to only its upper 
+16 bits sans MSB, without any additional comment.
+
+The implementations referred to in the file header (Postgres and BSD)
+do not exhibit this behavior.
+
+A [bug report](https://bugs.launchpad.net/libmemcached/+bug/604178) was
+filed three years later on launchpad, which was marked `Won't fix` with
+the comment that it was for compatibility with other "drivers", which
+supposedly refers to other memcached client libraries.
+
+
+## libmemcached
+
+### Replication
+
+This is a somewhat badly named feature, because it **does not** provide
+any of the guaranties one would expect from a proper replication.
+
+One can set the intended number of additional servers where data should
+be stored with the behavior `MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS` and
+specify whether `MGET`s/`GET`s should read from a random server with 
+`MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ`. `DELETE`s will try to 
+delete the key from all replicas.
+
+The binary protocol is required and any other command is unaffected.

diff --git a/ChangeLog.md b/ChangeLog.md
index 8b0bdafdb69870428cab34ed2e0d74987eea3bf5..85df3e3606e214f58f0821a3b0ce6567b9b3e24b 100644 (file)
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -95,6 +95,10 @@ has been incremented due to the following changes:
 * Fix bin/memaslap to idnentify itself as memaslap instead of memslap.
 * Fix bin/memcapable to work with memcached >= 1.6.
 * Fix murmur and murmur3 hashes on big endian platforms.
+* Fix [gh #82](https://github.com/m6w6/libmemcached/issues/82),
+  [gh #64](https://github.com/m6w6/libmemcached/issues/64) and
+  [gh #21](https://github.com/m6w6/libmemcached/issues/21):
+  clarify documentation on replication.
 
 ---
 

diff --git a/README.md b/README.md
index 20f1d709ff119f6ae278a9d8fd2ad51956d27d96..42782e3fac2b272f227758de2e8e3b449d933577 100644 (file)
--- a/README.md
+++ b/README.md
@@ -67,6 +67,10 @@ found in the accompanying [LICENSE](./LICENSE) file.
 
 ## Contributing
 
+Please report any issues on the [bug tracker](https://github.com/m6w6/libmemcached/issues).
+
+A list of known permanent issues is maintained in [BUGS](./BUGS.md).
+
 All forms of contribution are welcome! Please see the bundled
 [CONTRIBUTING](./CONTRIBUTING.md) note for the general principles followed.
 

diff --git a/docs/source/libmemcached/memcached_behavior.rst b/docs/source/libmemcached/memcached_behavior.rst
index f8353d20995b65efef6c6302bdf07317c43f1ae1..6c1fa538458526e0c37e71286f83a1f3087b535a 100644 (file)
--- a/docs/source/libmemcached/memcached_behavior.rst
+++ b/docs/source/libmemcached/memcached_behavior.rst
@@ -222,7 +222,7 @@ SYNOPSIS
 
     .. enumerator:: MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
 
-        Specify the numbers of replicas `libmemcached` should store of each item
+        Specify the number of replicas `libmemcached` should store of each item
         (on different servers).
 
         This replication does not dedicate certain memcached servers to store
@@ -230,15 +230,21 @@ SYNOPSIS
         all of the other objects (on the 'n' next servers specified in your
         server list).
 
+        Requires the binary protocol and only supports (M)GET/SET/DELETE.
+
+        **NOTE**: `libmemcached` does not guarantee nor enforce any consistency.
+
     .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
 
         Allows randomizing the replica reads starting point. Normally the read
-        is done from primary server and in case of miss the read is done from
+        is done from primary server and in case of failure the read is done from
         primary + 1, then primary + 2 all the way to 'n' replicas.
 
-        If this option is set on the starting point of the replica reads is
-        randomized between the servers.  This allows distributing read load to
-        multiple servers with the expense of more write traffic.
+        This allows distributing read load to multiple servers with the expense
+        of more write traffic.
+
+        **NOTE**: Only errors to communicate with a server are considered 
+        failures, so `MEMCACHED_NOTFOUND` does *not* account for failure.
 
     .. enumerator:: MEMCACHED_BEHAVIOR_CORK