From 3301b2f6fc5a53b428d29b788ba85fe4dae7b12d Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Wed, 15 Sep 2021 09:06:49 +0200 Subject: [PATCH] docs: m2r BUGS.md issues.rst --- BUGS.md | 17 ++++++++++ docs/source/CMakeLists.txt | 45 +++++++++++++++----------- docs/source/index.rst | 1 + docs/source/issues.rst | 65 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 110 insertions(+), 18 deletions(-) create mode 100644 docs/source/issues.rst diff --git a/BUGS.md b/BUGS.md index 796ba388..cb6f6874 100644 --- a/BUGS.md +++ b/BUGS.md @@ -39,3 +39,20 @@ specify whether `MGET`s/`GET`s should read from a random server with delete the key from all replicas. The binary protocol is required and any other command is unaffected. + +### TLS/SSL + +libmemcached does not support TLS/SSL, yet. +See [github issue #37](https://github.com/awesomized/libmemcached/issues/37). + + +### Coroutines and event loops + +libmemcached does not support explicit asynchronous usage, yet. +See [github issue #54](https://github.com/awesomized/libmemcached/issues/54). + + +### META protocol + +libmemcached deos not support memcached's META protocol, yet. +See [github issue #121](https://github.com/awesomized/libmemcached/issues/121). diff --git a/docs/source/CMakeLists.txt b/docs/source/CMakeLists.txt index 3ee77d0d..134c8eb5 100644 --- a/docs/source/CMakeLists.txt +++ b/docs/source/CMakeLists.txt @@ -1,25 +1,34 @@ find_program(M2R NAMES m2r m2r-3) +function(DefaultRstPath MDFILE RSTFILE_VAR) + string(REGEX REPLACE "\\.md$" ".rst" FILEPATH ${MDFILE}) + get_filename_component(FILENAME ${FILEPATH} NAME) + set(${RSTFILE_VAR} "${CMAKE_CURRENT_SOURCE_DIR}/${FILENAME}" PARENT_SCOPE) +endfunction() + +function(UpdateRstFromMd RSTFILE MDFILE) + if(${MDFILE} IS_NEWER_THAN ${RSTFILE}) + message("-- Processing ${MDFILE} ...") + execute_process( + COMMAND ${M2R} --overwrite --parse-relative-links ${MDFILE} + RESULTS_VARIABLE M2R_STATUS + ) + if(M2R_STATUS) + message(" Failed to update ${RSTFILE}: ${M2R_STATUS}") + else() + string(REGEX REPLACE "\\.md$" ".rst" FILEPATH ${MDFILE}) + file(RENAME ${FILEPATH} ${RSTFILE} ) + message(" Updated ${RSTFILE}: OK") + endif() + endif() +endfunction() + if(M2R) + message("-- Checking ChangeLogs, BUGS, etc...") file(GLOB CHANGELOGS "${CMAKE_SOURCE_DIR}/ChangeLog-*.md") - message("-- Checking ChangeLogs ...") foreach(CHANGELOG IN LISTS CHANGELOGS) - string(REGEX REPLACE "\\.md$" ".rst" FILEPATH ${CHANGELOG}) - get_filename_component(FILENAME ${FILEPATH} NAME) - - set(RESTFILE "${CMAKE_CURRENT_SOURCE_DIR}/${FILENAME}") - if(${CHANGELOG} IS_NEWER_THAN ${RESTFILE}) - message("-- Processing ${CHANGELOG} ...") - execute_process( - COMMAND ${M2R} --overwrite --parse-relative-links ${CHANGELOG} - RESULTS_VARIABLE M2R_STATUS - ) - if(M2R_STATUS) - message(" Failed to update ${RESTFILE}: ${M2R_STATUS}") - else() - file(RENAME ${FILEPATH} ${RESTFILE} ) - message(" Updated ${RESTFILE}: OK") - endif() - endif() + DefaultRstPath(${CHANGELOG} RESTFILE) + UpdateRstFromMd(${RESTFILE} ${CHANGELOG}) endforeach() + UpdateRstFromMd(issues.rst "${CMAKE_SOURCE_DIR}/BUGS.md") endif() diff --git a/docs/source/index.rst b/docs/source/index.rst index b3083ebc..a870db40 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,6 +20,7 @@ memory usage, thread safe, and provide full access to server side methods. :maxdepth: 1 changelogs + Known issues copyright Index diff --git a/docs/source/issues.rst b/docs/source/issues.rst new file mode 100644 index 00000000..988fd83b --- /dev/null +++ b/docs/source/issues.rst @@ -0,0 +1,65 @@ + +Bugs, Known Issues and Insufficiencies +====================================== + +libhashkit +---------- + +libhashkit is not usable for general purpose hashing, because it is geared to +usage by libmemcached. + +MurMur +^^^^^^ + +Hashkit's MurMur/MurMur3 are limited to the lower 32 bits. + +crc32 +^^^^^ + +Commit "\ `More Hashing methods `_\ " +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 `_ 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. + +TLS/SSL +^^^^^^^ + +libmemcached does not support TLS/SSL, yet. +See `github issue #37 `_. + +Coroutines and event loops +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +libmemcached does not support explicit asynchronous usage, yet. +See `github issue #54 `_. + +META protocol +^^^^^^^^^^^^^ + +libmemcached deos not support memcached's META protocol, yet. +See `github issue #121 `_. -- 2.30.2