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 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
 
 
 ## 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.
 
 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
 
 
     .. 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
         (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).
 
         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
     .. 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.
 
         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
 
 
     .. enumerator:: MEMCACHED_BEHAVIOR_CORK