From 2022f0a313c4cbe914ea1976c539cd0c436a88a8 Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Thu, 22 Oct 2020 08:10:25 +0200 Subject: [PATCH] fix #82, #64 and #21: docs on replication --- BUGS.md | 38 +++++++++++++++++++ ChangeLog.md | 4 ++ README.md | 4 ++ .../libmemcached/memcached_behavior.rst | 16 +++++--- 4 files changed, 57 insertions(+), 5 deletions(-) create mode 100644 BUGS.md diff --git a/BUGS.md b/BUGS.md new file mode 100644 index 00000000..e285ac19 --- /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 8b0bdafd..85df3e36 100644 --- 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 20f1d709..42782e3f 100644 --- 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 f8353d20..6c1fa538 100644 --- 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 -- 2.30.2