Replace pod docs with sphinx docs.
authorMonty Taylor <mordred@inaugust.com>
Sun, 6 Mar 2011 22:11:25 +0000 (14:11 -0800)
committerMonty Taylor <mordred@inaugust.com>
Sun, 6 Mar 2011 22:11:25 +0000 (14:11 -0800)
87 files changed:
Makefile.am
configure.ac
docs/Makefile.am [deleted file]
docs/conf.py
docs/hashkit_create.pod [deleted file]
docs/hashkit_create.rst [new file with mode: 0644]
docs/hashkit_functions.pod [deleted file]
docs/hashkit_functions.rst [new file with mode: 0644]
docs/hashkit_value.pod [deleted file]
docs/hashkit_value.rst [new file with mode: 0644]
docs/include.am
docs/index.rst
docs/libmemcached.pod [deleted file]
docs/libmemcached.rst [new file with mode: 0644]
docs/libmemcached_examples.pod [deleted file]
docs/libmemcached_examples.rst [new file with mode: 0644]
docs/libmemcachedutil.pod [deleted file]
docs/libmemcachedutil.rst [new file with mode: 0644]
docs/make_index.pl [deleted file]
docs/memcached_analyze.pod [deleted file]
docs/memcached_analyze.rst [new file with mode: 0644]
docs/memcached_auto.pod [deleted file]
docs/memcached_auto.rst [new file with mode: 0644]
docs/memcached_behavior.pod [deleted file]
docs/memcached_behavior.rst [new file with mode: 0644]
docs/memcached_callback.pod [deleted file]
docs/memcached_callback.rst [new file with mode: 0644]
docs/memcached_create.pod [deleted file]
docs/memcached_create.rst [new file with mode: 0644]
docs/memcached_delete.pod [deleted file]
docs/memcached_delete.rst [new file with mode: 0644]
docs/memcached_dump.pod [deleted file]
docs/memcached_dump.rst [new file with mode: 0644]
docs/memcached_flush.pod [deleted file]
docs/memcached_flush.rst [new file with mode: 0644]
docs/memcached_flush_buffers.pod [deleted file]
docs/memcached_flush_buffers.rst [new file with mode: 0644]
docs/memcached_generate_hash_value.pod [deleted file]
docs/memcached_generate_hash_value.rst [new file with mode: 0644]
docs/memcached_get.pod [deleted file]
docs/memcached_get.rst [new file with mode: 0644]
docs/memcached_memory_allocators.pod [deleted file]
docs/memcached_memory_allocators.rst [new file with mode: 0644]
docs/memcached_pool.pod [deleted file]
docs/memcached_pool.rst [new file with mode: 0644]
docs/memcached_quit.pod [deleted file]
docs/memcached_quit.rst [new file with mode: 0644]
docs/memcached_result_st.pod [deleted file]
docs/memcached_result_st.rst [new file with mode: 0644]
docs/memcached_sasl.pod [deleted file]
docs/memcached_sasl.rst [new file with mode: 0644]
docs/memcached_server_st.pod [deleted file]
docs/memcached_server_st.rst [new file with mode: 0644]
docs/memcached_servers.pod [deleted file]
docs/memcached_servers.rst [new file with mode: 0644]
docs/memcached_set.pod [deleted file]
docs/memcached_set.rst [new file with mode: 0644]
docs/memcached_stats.pod [deleted file]
docs/memcached_stats.rst [new file with mode: 0644]
docs/memcached_strerror.pod [deleted file]
docs/memcached_strerror.rst [new file with mode: 0644]
docs/memcached_user_data.pod [deleted file]
docs/memcached_user_data.rst [new file with mode: 0644]
docs/memcached_verbosity.pod [deleted file]
docs/memcached_verbosity.rst [new file with mode: 0644]
docs/memcached_version.pod [deleted file]
docs/memcached_version.rst [new file with mode: 0644]
docs/memcapable.pod [deleted file]
docs/memcapable.rst [new file with mode: 0644]
docs/memcat.pod [deleted file]
docs/memcat.rst [new file with mode: 0644]
docs/memcp.pod [deleted file]
docs/memcp.rst [new file with mode: 0644]
docs/memdump.pod [deleted file]
docs/memdump.rst [new file with mode: 0644]
docs/memerror.pod [deleted file]
docs/memerror.rst [new file with mode: 0644]
docs/memflush.pod [deleted file]
docs/memflush.rst [new file with mode: 0644]
docs/memrm.pod [deleted file]
docs/memrm.rst [new file with mode: 0644]
docs/memslap.pod [deleted file]
docs/memslap.rst [new file with mode: 0644]
docs/memstat.pod [deleted file]
docs/memstat.rst [new file with mode: 0644]
m4/pod2man.m4 [deleted file]
m4/podchecker.m4 [deleted file]

index 1260791dbbae4f2bf47151e6691e1f88c1b6fac6..312d998e962ca9f3e2f95a9070e0a158844918fb 100644 (file)
@@ -5,9 +5,11 @@ SUFFIXES =
 PHONY =
 TESTS =
 CLEANFILES =
+DISTCLEANFILES =
 bin_PROGRAMS =
 noinst_HEADERS =
 lib_LTLIBRARIES =
+man_MANS =
 noinst_LTLIBRARIES =
 noinst_PROGRAMS =
 include_HEADERS =
@@ -31,14 +33,6 @@ EXTRA_DIST= \
            m4/po.m4 \
            m4/progtest.m4
 
-TEST_DOCS=
-if BUILD_DOCS
-SUBDIRS = docs
-TEST_DOCS+=test-docs
-endif
-
-test-docs:
-       (cd docs && $(MAKE) test-docs)
 include libmemcached/include.am
 include clients/include.am
 include libhashkit/include.am
@@ -81,6 +75,9 @@ merge-clean:
        find ./ | $(GREP) \~$$ | xargs rm -f
        bzr unknowns
 
+clean-local:
+       -rm -rf docs/_build docs/doctrees
+
 lcov: lcov-clean check
        @echo
        @echo " ------------------------------------------------------"
index 07927c92c1962b7003720996d70510395fa7612d..8657fc6e6133bedda9ee892ada1693299d47d117 100644 (file)
@@ -131,19 +131,6 @@ AS_IF([test "x$ac_cv_header_atomic_h" = "xyes"],[
                      [1],
                       [Define to true if you want to use functions from atomic.h])])])
 
-AC_ARG_WITH([docs],
-  [AS_HELP_STRING([--with-docs],
-    [Generate documentation (yes|no) @<:@default=yes@:>@])],
-  [with_docs=$withval],
-  [with_docs=yes])
-
-AS_IF([test "$with_docs" = "yes"],
-  [
-    REQUIRE_POD2MAN
-    REQUIRE_PODCHECKER
-  ])
-AM_CONDITIONAL(BUILD_DOCS, test "$with_docs" = "yes")
-
 AC_CHECK_HEADERS_ONCE(winsock2.h poll.h sys/wait.h fnmatch.h)
 AM_CONDITIONAL(BUILD_POLL, test "x$ac_cv_header_poll_h" = "xno")
 AM_CONDITIONAL(BUILD_WIN32_WRAPPERS, test "x$ac_cv_header_winsock2_h" = "xyes")
@@ -157,7 +144,6 @@ SOCKET_SEND_FLAGS
 
 AC_CONFIG_FILES([
   Makefile
-  docs/Makefile
   libhashkit/configure.h
   libmemcached/configure.h
   support/libmemcached.pc
@@ -191,13 +177,3 @@ case "$host_os" in
   ;;
 esac
 
-AS_IF(test "$with_docs" = "no",
-  [
-    echo "*****"
-    echo "*"
-    echo "*  WARNING: You are not generating any documentation."
-    echo "*           Please don't ship libmemcached to an end user"
-    echo "*           without documentation..."
-    echo "*"
-    echo "*****"
-  ])
diff --git a/docs/Makefile.am b/docs/Makefile.am
deleted file mode 100644 (file)
index e97ff32..0000000
+++ /dev/null
@@ -1,562 +0,0 @@
-# This file generates all of man/html pages that we use for documentation.
-#
-# When hacking this file you need to know that we take .pod files and turn
-# them into .pop files. .pop files are 1=1 for man pages, but one .pod
-# file may generate many .pop files.
-#
-#    -Brian
-#
-#
-CLEANFILES= *.1 *.3 *.html *.pop *.tmp
-
-BUILT_SOURCES=
-
-EXTRA_DIST= make_index.pl
-
-AUTO_PAGES= \
-           memcached_increment.pop \
-           memcached_increment_with_initial.pop \
-           memcached_decrement.pop \
-           memcached_decrement_with_initial.pop
-BUILT_SOURCES += ${AUTO_PAGES}
-
-BEHAVIOR_PAGES= \
-               memcached_behavior_get.pop \
-               memcached_behavior_set.pop
-BUILT_SOURCES += ${BEHAVIOR_PAGES}
-
-CALLBACK_PAGES= \
-               memcached_callback_get.pop \
-               memcached_callback_set.pop
-BUILT_SOURCES += ${CALLBACK_PAGES}
-
-CREATE_PAGES= \
-             memcached_clone.pop \
-             memcached_create.pop \
-             memcached_free.pop \
-             memcached_servers_reset.pop
-BUILT_SOURCES += ${CREATE_PAGES}
-
-DELETE_PAGES= \
-             memcached_delete.pop \
-             memcached_delete_by_key.pop
-BUILT_SOURCES += ${DELETE_PAGES}
-
-GENERIC_PAGES= \
-              libmemcached.pop \
-              libmemcached_examples.pop \
-              libmemcachedutil.pop \
-              memcached_analyze.pop \
-              memcached_dump.pop \
-              memcached_flush.pop \
-              memcached_flush_buffers.pop \
-              memcached_generate_hash_value.pop \
-              memcached_quit.pop \
-              memcached_strerror.pop \
-              memcached_verbosity.pop \
-              memcapable.pop \
-              memcat.pop \
-              memcp.pop \
-              memdump.pop \
-              memerror.pop \
-              memflush.pop \
-              memrm.pop \
-              memslap.pop \
-              memstat.pop
-BUILT_SOURCES += ${GENERIC_PAGES}
-
-GET_PAGES= \
-          memcached_get.pop \
-          memcached_get_by_key.pop \
-          memcached_fetch_result.pop \
-          memcached_fetch_execute.pop \
-          memcached_mget.pop \
-          memcached_mget_by_key.pop \
-          memcached_mget_execute.pop \
-          memcached_mget_execute_by_key.pop \
-          memcached_fetch.pop
-BUILT_SOURCES += ${GET_PAGES}
-
-MEMORY_ALLOCATORS_PAGES= \
-                        memcached_get_memory_allocators.pop \
-                        memcached_set_memory_allocators.pop \
-                        memcached_set_memory_allocators_context.pop
-BUILT_SOURCES += ${MEMORY_ALLOCATORS_PAGES}
-
-POOL_PAGES= \
-           memcached_pool_behavior_get.pop \
-           memcached_pool_behavior_set.pop \
-           memcached_pool_create.pop \
-           memcached_pool_destroy.pop \
-           memcached_pool_pop.pop \
-           memcached_pool_push.pop
-BUILT_SOURCES += ${POOL_PAGES}
-
-RESULT_PAGES= \
-             memcached_result_cas.pop \
-             memcached_result_create.pop \
-             memcached_result_flags.pop \
-             memcached_result_free.pop \
-             memcached_result_key_length.pop \
-             memcached_result_key_value.pop \
-             memcached_result_length.pop \
-             memcached_result_st.pop \
-             memcached_result_value.pop
-BUILT_SOURCES += ${RESULT_PAGES}
-
-
-SERVER_PAGES= \
-             memcached_server_count.pop \
-             memcached_server_cursor.pop \
-             memcached_server_list.pop \
-             memcached_server_add.pop \
-             memcached_server_add_unix_socket.pop \
-             memcached_server_push.pop
-BUILT_SOURCES += ${SERVER_PAGES}
-
-SERVER_ST_PAGES= \
-                memcached_server_list_free.pop \
-                memcached_server_list_count.pop \
-                memcached_server_list_append.pop \
-                memcached_servers_parse.pop
-BUILT_SOURCES += ${SERVER_ST_PAGES}
-
-SET_PAGES= \
-          memcached_set.pop \
-          memcached_set_by_key.pop \
-          memcached_cas.pop \
-          memcached_cas_by_key.pop \
-          memcached_replace.pop \
-          memcached_replace_by_key.pop \
-          memcached_add.pop \
-          memcached_add_by_key.pop \
-          memcached_prepend.pop \
-          memcached_prepend_by_key.pop \
-          memcached_append.pop \
-          memcached_append_by_key.pop
-BUILT_SOURCES += ${SET_PAGES}
-
-STATS_PAGES= \
-            memcached_stat.pop \
-            memcached_stat_execute.pop\
-            memcached_stat_get_keys.pop\
-            memcached_stat_get_value.pop \
-            memcached_stat_servername.pop
-BUILT_SOURCES += ${STATS_PAGES}
-
-USER_DATA_PAGES= \
-                memcached_get_user_data.pop \
-                memcached_set_user_data.pop
-BUILT_SOURCES += ${USER_DATA_PAGES}
-
-VERSION_PAGES= \
-              memcached_version.pop \
-              memcached_lib_version.pop
-BUILT_SOURCES += ${VERSION_PAGES}
-
-
-#
-# These are for libhashkit
-#
-HASHKIT_CREATE_PAGES= \
-                     hashkit_is_allocated.pop \
-                     hashkit_create.pop \
-                     hashkit_clone.pop \
-                     hashkit_free.pop
-BUILT_SOURCES += ${HASHKIT_CREATE_PAGES}
-
-HASHKIT_FUNCTIONS_PAGES= \
-                        hashkit_crc32.pop \
-                        hashkit_fnv1_32.pop \
-                        hashkit_fnv1_64.pop \
-                        hashkit_fnv1a_32.pop \
-                        hashkit_fnv1a_64.pop \
-                        hashkit_functions.pop \
-                        hashkit_hsieh.pop \
-                        hashkit_jenkins.pop \
-                        hashkit_md5.pop \
-                        hashkit_murmur.pop
-BUILT_SOURCES += ${HASHKIT_FUNCTIONS_PAGES}
-
-HASHKIT_ST_PAGES= \
-                 hashkit_value.pop
-BUILT_SOURCES += ${HASHKIT_ST_PAGES}
-
-
-HTML_FILES= \
-           hashkit_clone.html \
-           hashkit_crc32.html \
-           hashkit_create.html \
-           hashkit_fnv1_32.html \
-           hashkit_fnv1_64.html \
-           hashkit_fnv1a_32.html \
-           hashkit_fnv1a_64.html \
-           hashkit_free.html \
-           hashkit_functions.html \
-           hashkit_hsieh.html \
-           hashkit_is_allocated.html \
-           hashkit_jenkins.html \
-           hashkit_md5.html \
-           hashkit_murmur.html \
-           hashkit_value.html \
-           libmemcached_examples.html \
-           libmemcached.html \
-           libmemcachedutil.html \
-           memcached_add_by_key.html \
-           memcached_add.html \
-           memcached_analyze.html \
-           memcached_append_by_key.html \
-           memcached_append.html \
-           memcached_behavior_get.html \
-           memcached_behavior_set.html \
-           memcached_callback_get.html \
-           memcached_callback_set.html \
-           memcached_cas_by_key.html \
-           memcached_cas.html \
-           memcached_clone.html \
-           memcached_create.html \
-           memcached_decrement.html \
-           memcached_decrement_with_initial.html \
-           memcached_delete_by_key.html \
-           memcached_delete.html \
-           memcached_dump.html \
-           memcached_fetch_execute.html \
-           memcached_fetch.html \
-           memcached_fetch_result.html \
-           memcached_flush_buffers.html \
-           memcached_flush.html \
-           memcached_free.html \
-           memcached_generate_hash_value.html \
-           memcached_get_by_key.html \
-           memcached_get_memory_allocators.html \
-           memcached_get.html \
-           memcached_get_user_data.html \
-           memcached_increment.html \
-           memcached_increment_with_initial.html \
-           memcached_lib_version.html \
-           memcached_mget_by_key.html \
-           memcached_mget_execute_by_key.html \
-           memcached_mget_execute.html \
-           memcached_mget.html \
-           memcached_pool_behavior_get.html \
-           memcached_pool_behavior_set.html \
-           memcached_pool_create.html \
-           memcached_pool_destroy.html \
-           memcached_pool_pop.html \
-           memcached_pool_push.html \
-           memcached_prepend_by_key.html \
-           memcached_prepend.html \
-           memcached_quit.html \
-           memcached_replace_by_key.html \
-           memcached_replace.html \
-           memcached_result_cas.html \
-           memcached_result_create.html \
-           memcached_result_flags.html \
-           memcached_result_free.html \
-           memcached_result_key_length.html \
-           memcached_result_key_value.html \
-           memcached_result_length.html \
-           memcached_result_st.html \
-           memcached_result_value.html \
-           memcached_server_add.html \
-           memcached_server_add_unix_socket.html \
-           memcached_server_count.html \
-           memcached_server_cursor.html \
-           memcached_server_list_append.html \
-           memcached_server_list_count.html \
-           memcached_server_list_free.html \
-           memcached_server_list.html \
-           memcached_server_push.html \
-           memcached_servers_parse.html \
-           memcached_set_by_key.html \
-           memcached_set_memory_allocators.html \
-           memcached_set.html \
-           memcached_set_user_data.html \
-           memcached_stat_execute.html \
-           memcached_stat_get_keys.html \
-           memcached_stat_get_value.html \
-           memcached_stat.html \
-           memcached_stat_servername.html \
-           memcached_strerror.html \
-           memcached_verbosity.html \
-           memcached_version.html \
-           memcapable.html \
-           memcat.html \
-           memcp.html \
-           memdump.html \
-           memerror.html \
-           memflush.html \
-           memrm.html \
-           memslap.html \
-           memstat.html
-
-POD_FILES= \
-          hashkit_create.pod \
-          hashkit_functions.pod \
-          hashkit_value.pod \
-          libmemcached.pod \
-          libmemcached_examples.pod \
-          libmemcachedutil.pod \
-          memcached_analyze.pod \
-          memcached_auto.pod \
-          memcached_behavior.pod \
-          memcached_callback.pod \
-          memcached_create.pod \
-          memcached_delete.pod \
-          memcached_dump.pod \
-          memcached_flush.pod \
-          memcached_flush_buffers.pod \
-          memcached_generate_hash_value.pod \
-          memcached_get.pod \
-          memcached_memory_allocators.pod \
-          memcached_pool.pod \
-          memcached_quit.pod \
-          memcached_result_st.pod \
-          memcached_sasl.pod \
-          memcached_server_st.pod \
-          memcached_servers.pod \
-          memcached_set.pod \
-          memcached_stats.pod \
-          memcached_strerror.pod \
-          memcached_user_data.pod \
-          memcached_verbosity.pod \
-          memcached_version.pod \
-          memcapable.pod \
-          memcat.pod \
-          memcp.pod \
-          memdump.pod \
-          memerror.pod \
-          memflush.pod \
-          memrm.pod \
-          memslap.pod \
-          memstat.pod
-EXTRA_DIST+= $(POD_FILES)
-
-man_MANS = \
-          hashkit_clone.3 \
-          hashkit_crc32.3 \
-          hashkit_create.3 \
-          hashkit_fnv1_32.3 \
-          hashkit_fnv1_64.3 \
-          hashkit_fnv1a_32.3 \
-          hashkit_fnv1a_64.3 \
-          hashkit_free.3 \
-          hashkit_functions.3 \
-          hashkit_hsieh.3 \
-          hashkit_is_allocated.3 \
-          hashkit_jenkins.3 \
-          hashkit_md5.3 \
-          hashkit_murmur.3 \
-          hashkit_value.3 \
-          libmemcached.3 \
-          libmemcached_examples.3 \
-          memcached_add.3 \
-          memcached_add_by_key.3 \
-          memcached_analyze.3 \
-          memcached_append.3 \
-          memcached_append_by_key.3 \
-          memcached_behavior_get.3 \
-          memcached_behavior_set.3 \
-          memcached_callback_get.3 \
-          memcached_callback_set.3 \
-          memcached_cas.3 \
-          memcached_cas_by_key.3 \
-          memcached_clone.3 \
-          memcached_create.3 \
-          memcached_decrement.3 \
-          memcached_decrement_with_initial.3 \
-          memcached_delete.3 \
-          memcached_delete_by_key.3 \
-          memcached_dump.3 \
-          memcached_fetch.3 \
-          memcached_fetch_execute.3 \
-          memcached_fetch_result.3 \
-          memcached_flush_buffers.3 \
-          memcached_free.3 \
-          memcached_generate_hash_value.3 \
-          memcached_get.3 \
-          memcached_get_by_key.3 \
-          memcached_get_memory_allocators.3 \
-          memcached_get_user_data.3 \
-          memcached_increment.3 \
-          memcached_increment_with_initial.3 \
-          memcached_lib_version.3 \
-          memcached_mget.3 \
-          memcached_mget_by_key.3 \
-          memcached_mget_execute.3  \
-          memcached_mget_execute_by_key.3  \
-          memcached_prepend.3 \
-          memcached_prepend_by_key.3 \
-          memcached_quit.3 \
-          memcached_replace.3 \
-          memcached_replace_by_key.3 \
-          memcached_server_add.3 \
-          memcached_server_count.3 \
-          memcached_server_cursor.3 \
-          memcached_server_list.3 \
-          memcached_server_list_append.3 \
-          memcached_server_list_count.3 \
-          memcached_server_list_free.3 \
-          memcached_server_push.3 \
-          memcached_servers_parse.3 \
-          memcached_set.3 \
-          memcached_set_by_key.3 \
-          memcached_set_memory_allocators.3 \
-          memcached_set_user_data.3 \
-          memcached_stat.3 \
-          memcached_stat_execute.3 \
-          memcached_stat_get_keys.3 \
-          memcached_stat_get_value.3 \
-          memcached_stat_servername.3 \
-          memcached_strerror.3 \
-          memcached_verbosity.3 \
-          memcached_version.3 \
-          memcapable.1 \
-          memcat.1 \
-          memcp.1 \
-          memdump.1 \
-          memerror.1 \
-          memflush.1 \
-          memrm.1 \
-          memslap.1 \
-          memstat.1
-
-if HAVE_SASL
-POD_FILES+= memcached_sasl.pod
-man_MANS+= \
-           memcached_destroy_sasl_auth_data.3 \
-           memcached_get_sasl_callbacks.3 \
-           memcached_sasl_set_auth_data.3 \
-           memcached_set_sasl_callbacks.3
-
-HTML_FILES+= \
-           memcached_destroy_sasl_auth_data.html \
-           memcached_get_sasl_callbacks.html \
-           memcached_sasl_set_auth_data.html \
-           memcached_set_sasl_callbacks.html
-
-
-SASL_PAGES= \
-           memcached_destroy_sasl_auth_data.pop \
-           memcached_get_sasl_callbacks.pop \
-           memcached_sasl_set_auth_data.pop \
-           memcached_set_sasl_callbacks.pop
-BUILT_SOURCES += ${SASL_PAGES}
-
-${SASL_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_sasl.pod ${top_builddir}/docs/$@
-
-endif
-
-if BUILD_LIBMEMCACHEDUTIL
-man_MANS+= \
-         libmemcachedutil.3 \
-         memcached_pool_behavior_set.3 \
-         memcached_pool_behavior_get.3 \
-         memcached_pool_create.3 \
-         memcached_pool_destroy.3 \
-         memcached_pool_push.3 \
-         memcached_pool_pop.3
-endif
-
-
-${CREATE_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_create.pod ${top_builddir}/docs/$@
-
-${SET_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_set.pod ${top_builddir}/docs/$@
-
-${DELETE_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_delete.pod ${top_builddir}/docs/$@
-
-${AUTO_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_auto.pod ${top_builddir}/docs/$@
-
-${GET_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_get.pod ${top_builddir}/docs/$@
-
-${SERVER_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_servers.pod ${top_builddir}/docs/$@
-
-${SERVER_ST_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_server_st.pod ${top_builddir}/docs/$@
-
-${GENERIC_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/$*.pod ${top_builddir}/docs/$@
-
-${BEHAVIOR_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_behavior.pod ${top_builddir}/docs/$@
-
-${CALLBACK_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_callback.pod ${top_builddir}/docs/$@
-
-${STATS_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_stats.pod ${top_builddir}/docs/$@
-
-${RESULT_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_result_st.pod ${top_builddir}/docs/$@
-
-${VERSION_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_version.pod ${top_builddir}/docs/$@
-
-${MEMORY_ALLOCATORS_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_memory_allocators.pod ${top_builddir}/docs/$@
-
-${USER_DATA_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_user_data.pod ${top_builddir}/docs/$@
-
-${POOL_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/memcached_pool.pod ${top_builddir}/docs/$@
-
-${HASHKIT_CREATE_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/hashkit_create.pod ${top_builddir}/docs/$@
-
-
-${HASHKIT_FUNCTIONS_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/hashkit_functions.pod ${top_builddir}/docs/$@
-
-${HASHKIT_ST_PAGES}:
-       @rm -f $@
-       ln -s ${top_srcdir}/docs/hashkit_value.pod ${top_builddir}/docs/$@
-
-test-docs: $(POD_FILES)
-       ${PODCHECKER} $(top_srcdir)/docs/$?
-
-html-local: html-pages html-index
-
-html-pages: $(HTML_FILES)
-
-html-index: html-pages
-       perl make_index.pl *.html > index.html
-
-SUFFIXES= .pop .pod .html .1 .3
-
-.pop: ${_set}
-
-.pop.html:
-       pod2html --infile=$< >  $@
-
-.pop.1:
-       ${POD2MAN} -c "$*" -r "" -s 1 $< >  $@
-
-.pop.3:
-       ${POD2MAN} -c "$*" -r "" -s 3 $< >  $@
index 77cbb14b3eeb47b17db38e347863163ab0038a17..f90f68b0e06f222183bcfce009efbe7833d8db7b 100644 (file)
@@ -211,6 +211,43 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'libmemcached', u'libmemcached Documentation',
-     [u'Brian Aker'], 1)
-]
+  ('hashkit_create', 'hashkit_create', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('hashkit_functions', 'hashkit_functions', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('hashkit_value', 'hashkit_value', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('libmemcached_examples', 'libmemcached_examples', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('libmemcached', 'libmemcached', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('libmemcachedutil', 'libmemcachedutil', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_analyze', 'memcached_analyze', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_auto', 'memcached_auto', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_behavior', 'memcached_behavior', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_callback', 'memcached_callback', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_create', 'memcached_create', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_delete', 'memcached_delete', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_dump', 'memcached_dump', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_flush_buffers', 'memcached_flush_buffers', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_flush', 'memcached_flush', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_generate_hash_value', 'memcached_generate_hash_value', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_get', 'memcached_get', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_memory_allocators', 'memcached_memory_allocators', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_pool', 'memcached_pool', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_quit', 'memcached_quit', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_result_st', 'memcached_result_st', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_sasl', 'memcached_sasl', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_servers', 'memcached_servers', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_server_st', 'memcached_server_st', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_set', 'memcached_set', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_stats', 'memcached_stats', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_strerror', 'memcached_strerror', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_user_data', 'memcached_user_data', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_verbosity', 'memcached_verbosity', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcached_version', 'memcached_version', u'libmemcached Documentation', [u'Brian Aker'], 3),
+  ('memcapable', 'memcapable', u'libmemcached Documentation', [u'Brian Aker'], 1),
+  ('memcat', 'memcat', u'libmemcached Documentation', [u'Brian Aker'], 1),
+  ('memcp', 'memcp', u'libmemcached Documentation', [u'Brian Aker'], 1),
+  ('memdump', 'memdump', u'libmemcached Documentation', [u'Brian Aker'], 1),
+  ('memerror', 'memerror', u'libmemcached Documentation', [u'Brian Aker'], 1),
+  ('memflush', 'memflush', u'libmemcached Documentation', [u'Brian Aker'], 1),
+  ('memrm', 'memrm', u'libmemcached Documentation', [u'Brian Aker'], 1),
+  ('memslap', 'memslap', u'libmemcached Documentation', [u'Brian Aker'], 1),
+  ('memstat', 'memstat', u'libmemcached Documentation', [u'Brian Aker'], 1),
+  ]
diff --git a/docs/hashkit_create.pod b/docs/hashkit_create.pod
deleted file mode 100644 (file)
index bcd5390..0000000
+++ /dev/null
@@ -1,57 +0,0 @@
-=head1 NAME
-
-hashkit_create, hashkit_clone, hashkit_free, hashkit_is_allocated -
-Create and destroy hashkit objects
-
-=head1 LIBRARY
-
-C Library for hashing algorithms (libhashkit, -lhashkit)
-
-=head1 SYNOPSIS
-
-  #include <libhashkit/hashkit.h>
-
-  hashkit_st *hashkit_create(hashkit_st *hash);
-
-  hashkit_st *hashkit_clone(hashkit_st *destination, const hashkit_st *ptr);
-
-  void hashkit_free(hashkit_st *hash);
-
-  bool hashkit_is_allocated(const hashkit_st *hash);
-
-=head1 DESCRIPTION
-
-The hashkit_create() function initializes a hashkit object for use. If
-you pass a NULL argument for hash, then the memory for the object is
-allocated. If you specify a pre-allocated piece of memory, that is
-initialized for use.
-
-The hashkit_clone() function initializes a hashkit object much like
-hashkit_create(), but instead of using default settings it will use
-the settings of the ptr hashkit object.
-
-The hashkit_free() frees any resources being consumed by the hashkit
-objects that were initialized with hashkit_create() or hashkit_clone().
-
-The hashkit_is_allocated() reports where the memory was allocated 
-for a hashkit object.
-
-=head1 RETURN VALUE
-
-hashkit_create() and hashkit_clone() will return NULL on failure or
-non-NULL on success.
-
-hashkit_is_allocated() returns true if the memory for the hashkit
-object was allocated inside of hashkit_create() or hashkit_clone(),
-otherwise it is false and was user-supplied memory.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=cut
diff --git a/docs/hashkit_create.rst b/docs/hashkit_create.rst
new file mode 100644 (file)
index 0000000..4fa5974
--- /dev/null
@@ -0,0 +1,90 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+hashkit_create, hashkit_clone, hashkit_free, hashkit_is_allocated -
+Create and destroy hashkit objects
+
+
+*******
+LIBRARY
+*******
+
+
+C Library for hashing algorithms (libhashkit, -lhashkit)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <libhashkit/hashkit.h>
+   hashkit_st *hashkit_create(hashkit_st *hash);
+   hashkit_st *hashkit_clone(hashkit_st *destination, const hashkit_st *ptr);
+   void hashkit_free(hashkit_st *hash);
+   bool hashkit_is_allocated(const hashkit_st *hash);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+The hashkit_create() function initializes a hashkit object for use. If
+you pass a NULL argument for hash, then the memory for the object is
+allocated. If you specify a pre-allocated piece of memory, that is
+initialized for use.
+
+The hashkit_clone() function initializes a hashkit object much like
+hashkit_create(), but instead of using default settings it will use
+the settings of the ptr hashkit object.
+
+The hashkit_free() frees any resources being consumed by the hashkit
+objects that were initialized with hashkit_create() or hashkit_clone().
+
+The hashkit_is_allocated() reports where the memory was allocated 
+for a hashkit object.
+
+
+************
+RETURN VALUE
+************
+
+
+hashkit_create() and hashkit_clone() will return NULL on failure or
+non-NULL on success.
+
+hashkit_is_allocated() returns true if the memory for the hashkit
+object was allocated inside of hashkit_create() or hashkit_clone(),
+otherwise it is false and was user-supplied memory.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
diff --git a/docs/hashkit_functions.pod b/docs/hashkit_functions.pod
deleted file mode 100644 (file)
index 4af8418..0000000
+++ /dev/null
@@ -1,54 +0,0 @@
-=head1 NAME
-
-hashkit_default, hashkit_fnv1_64, hashkit_fnv1a_64, hashkit_fnv1_32,
-hashkit_fnv1a_32, hashkit_crc32, hashkit_hsieh, hashkit_murmur,
-hashkit_jenkins, hashkit_md5 - Various hash functions to use for
-calculating values for keys
-
-=head1 LIBRARY
-
-C Library for hashing algorithms (libhashkit, -lhashkit)
-
-=head1 SYNOPSIS
-
-  #include <libhashkit/hashkit.h>
-
-  uint32_t hashkit_default(const char *key, size_t key_length);
-  uint32_t hashkit_fnv1_64(const char *key, size_t key_length);
-  uint32_t hashkit_fnv1a_64(const char *key, size_t key_length);
-  uint32_t hashkit_fnv1_32(const char *key, size_t key_length);
-  uint32_t hashkit_fnv1a_32(const char *key, size_t key_length);
-  uint32_t hashkit_crc32(const char *key, size_t key_length);
-  uint32_t hashkit_hsieh(const char *key, size_t key_length);
-  uint32_t hashkit_murmur(const char *key, size_t key_length);
-  uint32_t hashkit_jenkins(const char *key, size_t key_length);
-  uint32_t hashkit_md5(const char *key, size_t key_length);
-
-=head1 DESCRIPTION
-
-These functions generate hash values from a key using a variety of
-algorithms. These functions can be used standalone, or as arguments
-to hashkit_set_hash_fn(3) or hashkit_set_continuum_hash_fn(3).
-
-The hashkit_hsieh() is only available if the library is built with
-the appropriate flag enabled.
-
-=head1 RETURN VALUE
-
-A 32-bit hash value.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-hashkit_create(3) hashkit_value(3) hashkit_set_hash_fn(3)
-hashkit_set_continuum_hash_fn(3)
-
-=cut
diff --git a/docs/hashkit_functions.rst b/docs/hashkit_functions.rst
new file mode 100644 (file)
index 0000000..883f6e1
--- /dev/null
@@ -0,0 +1,91 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+hashkit_default, hashkit_fnv1_64, hashkit_fnv1a_64, hashkit_fnv1_32,
+hashkit_fnv1a_32, hashkit_crc32, hashkit_hsieh, hashkit_murmur,
+hashkit_jenkins, hashkit_md5 - Various hash functions to use for
+calculating values for keys
+
+
+*******
+LIBRARY
+*******
+
+
+C Library for hashing algorithms (libhashkit, -lhashkit)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <libhashkit/hashkit.h>
+   uint32_t hashkit_default(const char *key, size_t key_length);
+   uint32_t hashkit_fnv1_64(const char *key, size_t key_length);
+   uint32_t hashkit_fnv1a_64(const char *key, size_t key_length);
+   uint32_t hashkit_fnv1_32(const char *key, size_t key_length);
+   uint32_t hashkit_fnv1a_32(const char *key, size_t key_length);
+   uint32_t hashkit_crc32(const char *key, size_t key_length);
+   uint32_t hashkit_hsieh(const char *key, size_t key_length);
+   uint32_t hashkit_murmur(const char *key, size_t key_length);
+   uint32_t hashkit_jenkins(const char *key, size_t key_length);
+   uint32_t hashkit_md5(const char *key, size_t key_length);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+These functions generate hash values from a key using a variety of
+algorithms. These functions can be used standalone, or as arguments
+to hashkit_set_hash_fn(3) or hashkit_set_continuum_hash_fn(3).
+
+The hashkit_hsieh() is only available if the library is built with
+the appropriate flag enabled.
+
+
+************
+RETURN VALUE
+************
+
+
+A 32-bit hash value.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+hashkit_create(3) hashkit_value(3) hashkit_set_hash_fn(3)
+hashkit_set_continuum_hash_fn(3)
+
diff --git a/docs/hashkit_value.pod b/docs/hashkit_value.pod
deleted file mode 100644 (file)
index db594bc..0000000
+++ /dev/null
@@ -1,41 +0,0 @@
-=head1 NAME
-
-hashkit_value - Generate a value for the given key
-
-=head1 LIBRARY
-
-C Library for hashing algorithms (libhashkit, -lhashkit)
-
-=head1 SYNOPSIS
-
-  #include <libhashkit/hashkit.h>
-
-  uint32_t hashkit_value(hashkit_st *hash,
-                         const char *key,
-                         size_t key_length);
-
-=head1 DESCRIPTION
-
-The hashkit_value() function generates a 32-bit hash value from the
-given key and key_length. The hash argument is an initialized hashkit
-object, and distribution type and hash function is used from this
-object while generating the value.
-
-=head1 RETURN VALUE
-
-A 32-bit hash value.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-hashkit_create(3) hashkit_set_distribution(3) hashkit_set_hash_fn(3)
-
-=cut
diff --git a/docs/hashkit_value.rst b/docs/hashkit_value.rst
new file mode 100644 (file)
index 0000000..5c34b15
--- /dev/null
@@ -0,0 +1,78 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+hashkit_value - Generate a value for the given key
+
+
+*******
+LIBRARY
+*******
+
+
+C Library for hashing algorithms (libhashkit, -lhashkit)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <libhashkit/hashkit.h>
+   uint32_t hashkit_value(hashkit_st *hash,
+                          const char *key,
+                          size_t key_length);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+The hashkit_value() function generates a 32-bit hash value from the
+given key and key_length. The hash argument is an initialized hashkit
+object, and distribution type and hash function is used from this
+object while generating the value.
+
+
+************
+RETURN VALUE
+************
+
+
+A 32-bit hash value.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+hashkit_create(3) hashkit_set_distribution(3) hashkit_set_hash_fn(3)
+
index 1c46e09e71ba8ce362c9a4ed7f2c20b8703c70d6..9538941151f83573b06e3abeb0a61f32a1434975 100644 (file)
@@ -20,8 +20,133 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(SPHINX_BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) ${top_srcdir}/docs
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest doxygen
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
+if HAVE_RECENT_SPHINX
+
+man_MANS+= \
+           docs/man/hashkit_create.3 \
+          docs/man/hashkit_functions.3 \
+          docs/man/hashkit_value.3 \
+          docs/man/libmemcached_examples.3 \
+          docs/man/libmemcached.3 \
+          docs/man/libmemcachedutil.3 \
+          docs/man/memcached_analyze.3 \
+          docs/man/memcached_auto.3 \
+          docs/man/memcached_behavior.3 \
+          docs/man/memcached_callback.3 \
+          docs/man/memcached_create.3 \
+          docs/man/memcached_delete.3 \
+          docs/man/memcached_dump.3 \
+          docs/man/memcached_flush_buffers.3 \
+          docs/man/memcached_flush.3 \
+          docs/man/memcached_generate_hash_value.3 \
+          docs/man/memcached_get.3 \
+          docs/man/memcached_memory_allocators.3 \
+          docs/man/memcached_pool.3 \
+          docs/man/memcached_quit.3 \
+          docs/man/memcached_result_st.3 \
+          docs/man/memcached_sasl.3 \
+          docs/man/memcached_servers.3 \
+          docs/man/memcached_server_st.3 \
+          docs/man/memcached_set.3 \
+          docs/man/memcached_stats.3 \
+          docs/man/memcached_strerror.3 \
+          docs/man/memcached_user_data.3 \
+          docs/man/memcached_verbosity.3 \
+          docs/man/memcached_version.3 \
+          docs/man/memcapable.1 \
+          docs/man/memcat.1 \
+          docs/man/memcp.1 \
+          docs/man/memdump.1 \
+          docs/man/memerror.1 \
+          docs/man/memflush.1 \
+          docs/man/memrm.1 \
+          docs/man/memslap.1 \
+          docs/man/memstat.1
+
+DISTCLEANFILES+= \
+                 docs/man/hashkit_create.3 \
+                docs/man/hashkit_functions.3 \
+                docs/man/hashkit_value.3 \
+                docs/man/libmemcached_examples.3 \
+                docs/man/libmemcached.3 \
+                docs/man/libmemcachedutil.3 \
+                docs/man/memcached_analyze.3 \
+                docs/man/memcached_auto.3 \
+                docs/man/memcached_behavior.3 \
+                docs/man/memcached_callback.3 \
+                docs/man/memcached_create.3 \
+                docs/man/memcached_delete.3 \
+                docs/man/memcached_dump.3 \
+                docs/man/memcached_flush_buffers.3 \
+                docs/man/memcached_flush.3 \
+                docs/man/memcached_generate_hash_value.3 \
+                docs/man/memcached_get.3 \
+                docs/man/memcached_memory_allocators.3 \
+                docs/man/memcached_pool.3 \
+                docs/man/memcached_quit.3 \
+                docs/man/memcached_result_st.3 \
+                docs/man/memcached_sasl.3 \
+                docs/man/memcached_servers.3 \
+                docs/man/memcached_server_st.3 \
+                docs/man/memcached_set.3 \
+                docs/man/memcached_stats.3 \
+                docs/man/memcached_strerror.3 \
+                docs/man/memcached_user_data.3 \
+                docs/man/memcached_verbosity.3 \
+                docs/man/memcached_version.3 \
+                docs/man/memcapable.1 \
+                docs/man/memcat.1 \
+                docs/man/memcp.1 \
+                docs/man/memdump.1 \
+                docs/man/memerror.1 \
+                docs/man/memflush.1 \
+                docs/man/memrm.1 \
+                docs/man/memslap.1 \
+                docs/man/memstat.1
+
+docs/man/hashkit_create.3: man
+docs/man/hashkit_functions.3: man
+docs/man/hashkit_value.3: man
+docs/man/libmemcached_examples.3: man
+docs/man/libmemcached.3: man
+docs/man/libmemcachedutil.3: man
+docs/man/memcached_analyze.3: man
+docs/man/memcached_auto.3: man
+docs/man/memcached_behavior.3: man
+docs/man/memcached_callback.3: man
+docs/man/memcached_create.3: man
+docs/man/memcached_delete.3: man
+docs/man/memcached_dump.3: man
+docs/man/memcached_flush_buffers.3: man
+docs/man/memcached_flush.3: man
+docs/man/memcached_generate_hash_value.3: man
+docs/man/memcached_get.3: man
+docs/man/memcached_memory_allocators.3: man
+docs/man/memcached_pool.3: man
+docs/man/memcached_quit.3: man
+docs/man/memcached_result_st.3: man
+docs/man/memcached_sasl.3: man
+docs/man/memcached_servers.3: man
+docs/man/memcached_server_st.3: man
+docs/man/memcached_set.3: man
+docs/man/memcached_stats.3: man
+docs/man/memcached_strerror.3: man
+docs/man/memcached_user_data.3: man
+docs/man/memcached_verbosity.3: man
+docs/man/memcached_version.3: man
+docs/man/memcapable.1: man
+docs/man/memcat.1: man
+docs/man/memcp.1: man
+docs/man/memdump.1: man
+docs/man/memerror.1: man
+docs/man/memflush.1: man
+docs/man/memrm.1: man
+docs/man/memslap.1: man
+docs/man/memstat.1: man
+endif
 
 if HAVE_SPHINX
 sphinx-help:
index 8987eaef21349abea54ac778fad80525991c32e1..316eba0229ca739704de9e080ab0fcba11af58b3 100644 (file)
@@ -11,6 +11,46 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   hashkit_create.rst
+   hashkit_functions.rst
+   hashkit_value.rst
+   libmemcached_examples.rst
+   libmemcached.rst
+   libmemcachedutil.rst
+   memcached_analyze.rst
+   memcached_auto.rst
+   memcached_behavior.rst
+   memcached_callback.rst
+   memcached_create.rst
+   memcached_delete.rst
+   memcached_dump.rst
+   memcached_flush_buffers.rst
+   memcached_flush.rst
+   memcached_generate_hash_value.rst
+   memcached_get.rst
+   memcached_memory_allocators.rst
+   memcached_pool.rst
+   memcached_quit.rst
+   memcached_result_st.rst
+   memcached_sasl.rst
+   memcached_servers.rst
+   memcached_server_st.rst
+   memcached_set.rst
+   memcached_stats.rst
+   memcached_strerror.rst
+   memcached_user_data.rst
+   memcached_verbosity.rst
+   memcached_version.rst
+   memcapable.rst
+   memcat.rst
+   memcp.rst
+   memdump.rst
+   memerror.rst
+   memflush.rst
+   memrm.rst
+   memslap.rst
+   memstat.rst
+
 Indices and tables
 ==================
 
diff --git a/docs/libmemcached.pod b/docs/libmemcached.pod
deleted file mode 100644 (file)
index 46fc2da..0000000
+++ /dev/null
@@ -1,127 +0,0 @@
-=head1 NAME
-
-libmemcached - Client library for memcached
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-=head1 DESCRIPTION
-
-"Memcached is a high-performance, distributed memory object caching
-system, generic in nature, but intended for use in speeding up dynamic web
-applications by alleviating database load." L<http://danga.com/memcached/>
-
-B<libmemcached> is a small, thread-safe client library for the
-memcached protocol. The code has all been written with an eye to allow
-for both web and embedded usage. It handles the work behind routing
-particular keys to specific servers that you specify (and values are
-matched based on server order as supplied by you). It implements both
-a modula and consistent method of object distribution.
-
-There are multiple implemented routing and hashing methods. See the
-memcached_behavior_set() manpage.
-
-All operations are performed against a C<memcached_st> structure.
-These structures can either be dynamically allocated or statically
-allocated and then initialized by memcached_create(). Functions have been
-written in order to encapsulate the C<memcached_st>. It is not
-recommended that you operate directly against the structure.
-
-Nearly all functions return a C<memcached_return_t> value.
-This value can be translated to a printable string with memcached_strerror(3).
-
-Partitioning based on keys is supported in the library. Using the key partioning 
-functions it is possible to group sets of object onto servers.
-
-C<memcached_st> structures are thread-safe, but each thread must
-contain its own structure (that is, if you want to share these among
-threads you must provide your own locking). No global variables are
-used in this library.
-
-If you are working with GNU autotools you will want to add the following to
-your configure.ac to properly include libmemcached in your application. 
-
-PKG_CHECK_MODULES(DEPS, libmemcached >= 0.8.0)
-AC_SUBST(DEPS_CFLAGS)
-AC_SUBST(DEPS_LIBS)
-
-Some features of the library must be enabled through memcached_behavior_set(). 
-
-Hope you enjoy it!
-
-=head1 CONSTANTS
-
-A number of constants have been provided for in the library.
-
-=over 4
-
-=item MEMCACHED_DEFAULT_PORT
-
-The default port used by memcached(3).
-
-=item MEMCACHED_MAX_KEY
-
-Default maximum size of a key (which includes the null pointer). Master keys
-have no limit, this only applies to keys used for storage.
-
-=item MEMCACHED_MAX_KEY
-
-Default size of key (which includes the null pointer).
-
-=item MEMCACHED_STRIDE
-
-This is the "stride" used in the consistent hash used between replicas.
-
-=item MEMCACHED_MAX_HOST_LENGTH
-
-Maximum allowed size of the hostname.
-
-=item MEMCACHED_VERSION_STRING
-
-String value of libmemcached version such as "1.23.4"
-
-=item MEMCACHED_MAJOR_VERSION
-
-Major version value. Such as 1.23.4, would be 1 
-
-=item MEMCACHED_MINOR_VERSION
-
-Major version value. Such as 1.23.4, would be 23 
-
-=item MEMCACHED_MICRO_VERSION
-
-Major version value. Such as 1.23.4, would be 4 
-
-
-=back
-
-
-
-=head1 THREADS AND PROCESSES
-
-When using threads or forked processes it is important to keep an instance
-of C<memcached_st> per process or thread. Without creating your own locking
-structures you can not share a single C<memcached_st>. You can though call
-memcached_quit(3) on a C<memcached_st> and then use the resulting cloned
-structure.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached_examples(3) libmemcached(1) memcat(1) memcp(1) memflush(1) memrm(1) memslap(1) memstat(1) memcached_fetch(3) memcached_replace(3) memcached_server_list_free(3) libmemcached_examples(3) memcached_clone(3) memcached_free(3) memcached_server_add(3) memcached_server_push(3) memcached_add(3) memcached_get(3) memcached_server_count(3) memcached_servers_parse(3) memcached_create(3) memcached_increment(3) memcached_server_list(3) memcached_set(3) memcached_decrement(3) memcached_mget(3) memcached_server_list_append(3) memcached_strerror(3) memcached_delete(3) memcached_quit(3) memcached_server_list_count(3) memcached_verbosity(3) memcached_server_add_unix_socket(3) memcached_result_create(3)  memcached_result_free(3)  memcached_result_key_value(3)  memcached_result_key_length(3)  memcached_result_value(3)  memcached_result_length(3)  memcached_result_flags(3)  memcached_result_cas(3) memcached_result_st(3) memcached_append(3) memcached_prepend(3) memcached_fetch_result(3) memerror(1) memcached_get_by_key(3) memcached_mget_by_key(3) memcached_delete_by_key(3) memcached_fetch_execute(3) memcached_callback_get(3) memcached_callback_set(3) memcached_version(3) memcached_lib_version(3) memcached_result_set_value(3) memcached_dump(3) memdump(1) memcached_set_memory_allocators(3) memcached_get_memory_allocators(3) memcached_get_user_data(3) memcached_set_user_data(3)
-
-=cut
-
diff --git a/docs/libmemcached.rst b/docs/libmemcached.rst
new file mode 100644 (file)
index 0000000..db88f68
--- /dev/null
@@ -0,0 +1,179 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+libmemcached - Client library for memcached
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+"Memcached is a high-performance, distributed memory object caching
+system, generic in nature, but intended for use in speeding up dynamic web
+applications by alleviating database load." `http://danga.com/memcached/ <http://danga.com/memcached/>`_
+
+\ **libmemcached**\  is a small, thread-safe client library for the
+memcached protocol. The code has all been written with an eye to allow
+for both web and embedded usage. It handles the work behind routing
+particular keys to specific servers that you specify (and values are
+matched based on server order as supplied by you). It implements both
+a modula and consistent method of object distribution.
+
+There are multiple implemented routing and hashing methods. See the
+memcached_behavior_set() manpage.
+
+All operations are performed against a \ ``memcached_st``\  structure.
+These structures can either be dynamically allocated or statically
+allocated and then initialized by memcached_create(). Functions have been
+written in order to encapsulate the \ ``memcached_st``\ . It is not
+recommended that you operate directly against the structure.
+
+Nearly all functions return a \ ``memcached_return_t``\  value.
+This value can be translated to a printable string with memcached_strerror(3).
+
+Partitioning based on keys is supported in the library. Using the key partioning 
+functions it is possible to group sets of object onto servers.
+
+\ ``memcached_st``\  structures are thread-safe, but each thread must
+contain its own structure (that is, if you want to share these among
+threads you must provide your own locking). No global variables are
+used in this library.
+
+If you are working with GNU autotools you will want to add the following to
+your configure.ac to properly include libmemcached in your application.
+
+PKG_CHECK_MODULES(DEPS, libmemcached >= 0.8.0)
+AC_SUBST(DEPS_CFLAGS)
+AC_SUBST(DEPS_LIBS)
+
+Some features of the library must be enabled through memcached_behavior_set().
+
+Hope you enjoy it!
+
+
+*********
+CONSTANTS
+*********
+
+
+A number of constants have been provided for in the library.
+
+
+MEMCACHED_DEFAULT_PORT
+ The default port used by memcached(3).
+
+
+MEMCACHED_MAX_KEY
+ Default maximum size of a key (which includes the null pointer). Master keys
+ have no limit, this only applies to keys used for storage.
+
+
+MEMCACHED_MAX_KEY
+ Default size of key (which includes the null pointer).
+
+
+MEMCACHED_STRIDE
+ This is the "stride" used in the consistent hash used between replicas.
+
+
+MEMCACHED_MAX_HOST_LENGTH
+ Maximum allowed size of the hostname.
+
+
+MEMCACHED_VERSION_STRING
+ String value of libmemcached version such as "1.23.4"
+
+
+MEMCACHED_MAJOR_VERSION
+ Major version value. Such as 1.23.4, would be 1
+
+
+MEMCACHED_MINOR_VERSION
+ Major version value. Such as 1.23.4, would be 23
+
+
+MEMCACHED_MICRO_VERSION
+ Major version value. Such as 1.23.4, would be 4
+
+
+
+*********************
+THREADS AND PROCESSES
+*********************
+
+
+When using threads or forked processes it is important to keep an instance
+of \ ``memcached_st``\  per process or thread. Without creating your own locking
+structures you can not share a single \ ``memcached_st``\ . You can though call
+memcached_quit(3) on a \ ``memcached_st``\  and then use the resulting cloned
+structure.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached_examples(3) libmemcached(1) memcat(1) memcp(1) memflush(1) memrm(1) memslap(1) memstat(1) memcached_fetch(3) memcached_replace(3) memcached_server_list_free(3) libmemcached_examples(3) memcached_clone(3) memcached_free(3) memcached_server_add(3) memcached_server_push(3) memcached_add(3) memcached_get(3) memcached_server_count(3) memcached_servers_parse(3) memcached_create(3) memcached_increment(3) memcached_server_list(3) memcached_set(3) memcached_decrement(3) memcached_mget(3) memcached_server_list_append(3) memcached_strerror(3) memcached_delete(3) memcached_quit(3) memcached_server_list_count(3) memcached_verbosity(3) memcached_server_add_unix_socket(3) memcached_result_create(3)  memcached_result_free(3)  memcached_result_key_value(3)  memcached_result_key_length(3)  memcached_result_value(3)  memcached_result_length(3)  memcached_result_flags(3)  memcached_result_cas(3) memcached_result_st(3) memcached_append(3) memcached_prepend(3) memcached_fetch_result(3) memerror(1) memcached_get_by_key(3) memcached_mget_by_key(3) memcached_delete_by_key(3) memcached_fetch_execute(3) memcached_callback_get(3) memcached_callback_set(3) memcached_version(3) memcached_lib_version(3) memcached_result_set_value(3) memcached_dump(3) memdump(1) memcached_set_memory_allocators(3) memcached_get_memory_allocators(3) memcached_get_user_data(3) memcached_set_user_data(3)
+
diff --git a/docs/libmemcached_examples.pod b/docs/libmemcached_examples.pod
deleted file mode 100644 (file)
index 1c937fe..0000000
+++ /dev/null
@@ -1,115 +0,0 @@
-=head1 NAME
-
-libmemcached_examples - Examples for libmemcached
-
-=head1 DESCRIPTION
-
-For full examples, test cases are found in tests/*.c in the main
-distribution. These are always up to date, and are used for each test run of
-the library.
-
-=head2 Creating and Freeing structure
-
-  memcached_st *memc;
-  memcached_return_t rc;
-
-  memc= memcached_create(NULL);
-  ...do stuff...
-  memcached_free(memc);
-
-The above code would create a connection and then free the connection when
-finished.
-
-=head2 Connecting to servers
-
-  memcached_server_st *servers;
-  memcached_st *memc= memcached_create(NULL);
-  char servername[]= "0.example.com";
-
-  servers= memcached_server_list_append(NULL, servername, 400, &rc);
-
-  for (x= 0; x < 20; x++)
-  {
-    char buffer[SMALL_STRING_LEN];
-
-    snprintf(buffer, SMALL_STRING_LEN, "%u.example.com", 400+x);
-    servers= memcached_server_list_append(servers, buffer, 401, &rc);
-  }
-  rc= memcached_server_push(memc, servers);
-  memcached_server_free(servers);
-  memcached_free(memc);
-
-In the above code you create a C<memcached_st> object that you then feed in a
-single host into. In the for loop you build a C<memcached_server_st>
-pointer that you then later feed via memcached_server_push() into the
-C<memcached_st> structure.
-
-You can reuse the C<memcached_server_st> object with multile C<memcached_st>
-structures.
-
-=head2 Adding a value to the server
-
-  char *key= "foo";
-  char *value;
-  size_t value_length= 8191;
-  unsigned int x;
-
-  value = (char*)malloc(value_length);
-  assert(value);
-
-  for (x= 0; x < value_length; x++)
-  value[x] = (char) (x % 127);
-
-  for (x= 0; x < 1; x++)
-  {
-    rc= memcached_set(memc, key, strlen(key), 
-    value, value_length,
-    (time_t)0, (uint32_t)0);
-    assert(rc == MEMCACHED_SUCCESS);
-  }
-
-  free(value);
-
-It is best practice to always look at the return value of any operation.
-
-=head2 Fetching multiple values
-
-  memcached_return_t rc;
-  char *keys[]= {"fudge", "son", "food"};
-  size_t key_length[]= {5, 3, 4};
-  unsigned int x;
-  uint32_t flags;
-
-  char return_key[MEMCACHED_MAX_KEY];
-  size_t return_key_length;
-  char *return_value;
-  size_t return_value_length;
-
-  rc= memcached_mget(memc, keys, key_length, 3);
-
-  x= 0;
-  while ((return_value= memcached_fetch(memc, return_key, &return_key_length, 
-                                        &return_value_length, &flags, &rc)))
-  {
-    free(return_value);
-    x++;
-  }
-
-Notice that you freed values returned from memcached_fetch(). The define
-C<MEMCACHED_MAX_KEY> is provided for usage.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1)
-
-=cut
-
diff --git a/docs/libmemcached_examples.rst b/docs/libmemcached_examples.rst
new file mode 100644 (file)
index 0000000..82e2858
--- /dev/null
@@ -0,0 +1,163 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+libmemcached_examples - Examples for libmemcached
+
+
+***********
+DESCRIPTION
+***********
+
+
+For full examples, test cases are found in tests/\*.c in the main
+distribution. These are always up to date, and are used for each test run of
+the library.
+
+Creating and Freeing structure
+==============================
+
+
+
+.. code-block:: perl
+
+   memcached_st *memc;
+   memcached_return_t rc;
+   memc= memcached_create(NULL);
+   ...do stuff...
+   memcached_free(memc);
+
+
+The above code would create a connection and then free the connection when
+finished.
+
+
+Connecting to servers
+=====================
+
+
+
+.. code-block:: perl
+
+   memcached_server_st *servers;
+   memcached_st *memc= memcached_create(NULL);
+   char servername[]= "0.example.com";
+   servers= memcached_server_list_append(NULL, servername, 400, &rc);
+   for (x= 0; x < 20; x++)
+   {
+     char buffer[SMALL_STRING_LEN];
+     snprintf(buffer, SMALL_STRING_LEN, "%u.example.com", 400+x);
+     servers= memcached_server_list_append(servers, buffer, 401, &rc);
+   }
+   rc= memcached_server_push(memc, servers);
+   memcached_server_free(servers);
+   memcached_free(memc);
+
+
+In the above code you create a \ ``memcached_st``\  object that you then feed in a
+single host into. In the for loop you build a \ ``memcached_server_st``\ 
+pointer that you then later feed via memcached_server_push() into the
+\ ``memcached_st``\  structure.
+
+You can reuse the \ ``memcached_server_st``\  object with multile \ ``memcached_st``\ 
+structures.
+
+
+Adding a value to the server
+============================
+
+
+
+.. code-block:: perl
+
+   char *key= "foo";
+   char *value;
+   size_t value_length= 8191;
+   unsigned int x;
+   value = (char*)malloc(value_length);
+   assert(value);
+   for (x= 0; x < value_length; x++)
+   value[x] = (char) (x % 127);
+   for (x= 0; x < 1; x++)
+   {
+     rc= memcached_set(memc, key, strlen(key), 
+     value, value_length,
+     (time_t)0, (uint32_t)0);
+     assert(rc == MEMCACHED_SUCCESS);
+   }
+   free(value);
+
+
+It is best practice to always look at the return value of any operation.
+
+
+Fetching multiple values
+========================
+
+
+
+.. code-block:: perl
+
+   memcached_return_t rc;
+   char *keys[]= {"fudge", "son", "food"};
+   size_t key_length[]= {5, 3, 4};
+   unsigned int x;
+   uint32_t flags;
+   char return_key[MEMCACHED_MAX_KEY];
+   size_t return_key_length;
+   char *return_value;
+   size_t return_value_length;
+   rc= memcached_mget(memc, keys, key_length, 3);
+   x= 0;
+   while ((return_value= memcached_fetch(memc, return_key, &return_key_length, 
+                                         &return_value_length, &flags, &rc)))
+   {
+     free(return_value);
+     x++;
+   }
+
+
+Notice that you freed values returned from memcached_fetch(). The define
+\ ``MEMCACHED_MAX_KEY``\  is provided for usage.
+
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1)
+
diff --git a/docs/libmemcachedutil.pod b/docs/libmemcachedutil.pod
deleted file mode 100644 (file)
index fd2e4f6..0000000
+++ /dev/null
@@ -1,40 +0,0 @@
-=head1 NAME
-
-libmemcachedutil - Utility library for libmemcached
-
-=head1 LIBRARY
-
-C Client Library containing utility functions for libmemcached (libmemcachedutil, -lmemcachedutil)
-
-=head1 SYNOPSIS
-
-  cc [ flag ... ] file ... -lmemcachedutil
-
-  #include <libmemcached/memcached_util.h>
-
-=head1 DESCRIPTION
-
-B<libmemcachedutil> is a small and thread-safe client library that provides
-extra functionality built on top of B<libmemcached>.
-
-=head1 THREADS
-
-Do not try to access an instance of C<memcached_st> from multiple threads
-at the same time. If you want to access memcached from multiple threads
-you should either clone the C<memcached_st>, or use the memcached pool
-implementation. see memcached_pool_create(3).
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Trond Norbye, E<lt>trond.norbye@gmail.comE<gt>
-
-=head1 SEE ALSO
-
-libmemcached(3) memcached_pool_create(3) memcached_pool_destroy(3) memcached_pool_pop(3) memcached_pool_push(3)
-
-=cut
diff --git a/docs/libmemcachedutil.rst b/docs/libmemcachedutil.rst
new file mode 100644 (file)
index 0000000..d213876
--- /dev/null
@@ -0,0 +1,77 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+libmemcachedutil - Utility library for libmemcached
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library containing utility functions for libmemcached (libmemcachedutil, -lmemcachedutil)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   cc [ flag ... ] file ... -lmemcachedutil
+   #include <libmemcached/memcached_util.h>
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **libmemcachedutil**\  is a small and thread-safe client library that provides
+extra functionality built on top of \ **libmemcached**\ .
+
+
+*******
+THREADS
+*******
+
+
+Do not try to access an instance of \ ``memcached_st``\  from multiple threads
+at the same time. If you want to access memcached from multiple threads
+you should either clone the \ ``memcached_st``\ , or use the memcached pool
+implementation. see memcached_pool_create(3).
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Trond Norbye, <trond.norbye@gmail.com>
+
+
+********
+SEE ALSO
+********
+
+
+libmemcached(3) memcached_pool_create(3) memcached_pool_destroy(3) memcached_pool_pop(3) memcached_pool_push(3)
+
diff --git a/docs/make_index.pl b/docs/make_index.pl
deleted file mode 100644 (file)
index cb0d190..0000000
+++ /dev/null
@@ -1,30 +0,0 @@
-#!/usr/bin/perl -w
-
-use strict;
-use CGI;
-
-sub main {
-  my $cgi = new CGI;
-
-  print $cgi->start_html('Libmemcached Documentation') . "\n";
-  print $cgi->h1('Libmemcached Documentation') . "\n";
-
-  print $cgi->a({ href => "libmemcached.html" }, "Introduction to Libmemcached") . $cgi->br() . "\n";
-  print $cgi->a({ href => "libmemcached_examples.html" }, "Libmemcached Examples") . $cgi->br() . "\n";
-  print $cgi->br() . "\n";
-  print $cgi->br() . "\n";
-
-  foreach (@ARGV)
-  {
-    my $url=  $_;
-    my $name= $_;
-    $name  =~ s/\.html//g;
-    next if $name eq 'index'; 
-    next if $name eq 'libmemcached'; 
-    next if $name eq 'libmemcached_examples'; 
-    print "<li\>" . $cgi->a({ href => $url }, $name) . $cgi->br() . "\n";
-  }
-  print $cgi->end_html; 
-}
-
-main();
diff --git a/docs/memcached_analyze.pod b/docs/memcached_analyze.pod
deleted file mode 100644 (file)
index 9c0401f..0000000
+++ /dev/null
@@ -1,53 +0,0 @@
-=head1 NAME
-
-memcached_analyze - Analyze server information
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_analysis_st *
-    memcached_analyze (memcached_st *ptr,
-                       memcached_stat_st *stat,
-                       memcached_return_t *error);
-
-=head1 DESCRIPTION
-
-libmemcached(3) has the ability to query a memcached server (or collection
-of servers) for their current state. Queries to find state return a
-C<memcached_analysis_st> structure. You are responsible for freeing this structure.
-
-memcached_analyze() analyzes useful information based on the provided servers
-and sets the result to the C<memcached_analysis_st> structure. The return value
-must be freed by the calling application.
-
-A command line tool, memstat(1) with the option --analyze, is provided so that
-you do not have to write an application to use this method.
-
-=head1 RETURN
-
-A pointer to the allocated C<memcached_analysis_st> structure on success and
-a NULL pointer on failure. You may inspect the error detail by checking the
-C<memcached_return_t> value.
-
-Any method returning a C<memcached_analysis_st> expects you to free the
-memory allocated for it.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Toru Maesaka, E<lt>dev@torum.netE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
diff --git a/docs/memcached_analyze.rst b/docs/memcached_analyze.rst
new file mode 100644 (file)
index 0000000..cd8f36f
--- /dev/null
@@ -0,0 +1,90 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_analyze - Analyze server information
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_analysis_st *
+     memcached_analyze (memcached_st *ptr,
+                        memcached_stat_st *stat,
+                        memcached_return_t *error);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) has the ability to query a memcached server (or collection
+of servers) for their current state. Queries to find state return a
+\ ``memcached_analysis_st``\  structure. You are responsible for freeing this structure.
+
+memcached_analyze() analyzes useful information based on the provided servers
+and sets the result to the \ ``memcached_analysis_st``\  structure. The return value
+must be freed by the calling application.
+
+A command line tool, memstat(1) with the option --analyze, is provided so that
+you do not have to write an application to use this method.
+
+
+******
+RETURN
+******
+
+
+A pointer to the allocated \ ``memcached_analysis_st``\  structure on success and
+a NULL pointer on failure. You may inspect the error detail by checking the
+\ ``memcached_return_t``\  value.
+
+Any method returning a \ ``memcached_analysis_st``\  expects you to free the
+memory allocated for it.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Toru Maesaka, <dev@torum.net>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_auto.pod b/docs/memcached_auto.pod
deleted file mode 100644 (file)
index bd6da19..0000000
+++ /dev/null
@@ -1,138 +0,0 @@
-=head1 NAME
-
-memcached_increment, memcached_decrement,
-memcached_increment_with_initial, memcached_decrement_with_initial - Manipulate
-counters
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_return_t
-    memcached_increment (memcached_st *ptr, 
-                         const char *key, size_t key_length,
-                         unsigned int offset,
-                         uint64_t *value);
-
-  memcached_return_t
-    memcached_decrement (memcached_st *ptr, 
-                         const char *key, size_t key_length,
-                         unsigned int offset,
-                         uint64_t *value);
-
-  memcached_return_t
-    memcached_increment_with_initial (memcached_st *ptr,
-                                      const char *key,
-                                      size_t key_length,
-                                      uint64_t offset,
-                                      uint64_t initial,
-                                      time_t expiration,
-                                      uint64_t *value);
-
-  memcached_return_t
-    memcached_decrement_with_initial (memcached_st *ptr,
-                                      const char *key,
-                                      size_t key_length,
-                                      uint64_t offset,
-                                      uint64_t initial,
-                                      time_t expiration,
-                                      uint64_t *value);
-
-  memcached_return_t
-    memcached_increment_by_key (memcached_st *ptr, 
-                                const char *master_key, size_t master_key_length,
-                                const char *key, size_t key_length,
-                                unsigned int offset,
-                                uint64_t *value);
-
-  memcached_return_t
-    memcached_decrement_by_key (memcached_st *ptr, 
-                                const char *master_key, size_t master_key_length,
-                                const char *key, size_t key_length,
-                                unsigned int offset,
-                                uint64_t *value);
-
-  memcached_return_t
-    memcached_increment_with_initial_by_key (memcached_st *ptr,
-                                             const char *master_key,
-                                             size_t master_key_length,
-                                             const char *key,
-                                             size_t key_length,
-                                             uint64_t offset,
-                                             uint64_t initial,
-                                             time_t expiration,
-                                             uint64_t *value);
-
-  memcached_return_t
-    memcached_decrement_with_initial_by_key (memcached_st *ptr,
-                                             const char *master_key,
-                                             size_t master_key_length,
-                                             const char *key,
-                                             size_t key_length,
-                                             uint64_t offset,
-                                             uint64_t initial,
-                                             time_t expiration,
-                                             uint64_t *value);
-
-=head1 DESCRIPTION
-
-memcached(1) servers have the ability to increment and decrement keys
-(overflow and underflow are not detected). This gives you the ability to use
-memcached to generate shared sequences of values.  
-
-memcached_increment() takes a key and keylength and increments the value by
-the offset passed to it. The value is then returned via the unsigned int
-value pointer you pass to it.
-
-memcached_decrement() takes a key and keylength and decrements the value by
-the offset passed to it. The value is then returned via the unsigned int
-value pointer you pass to it.
-
-memcached_increment_with_initial() takes a key and keylength and increments
-the value by the offset passed to it. If the object specified by key does
-not exist, one of two things may happen: If the expiration value is
-MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other
-expiration values, the operation will succeed by seeding the value for that
-key with a initial value to expire with the provided expiration time. The
-flags will be set to zero.The value is then returned via the unsigned int
-value pointer you pass to it.
-
-memcached_decrement_with_initial() takes a key and keylength and decrements
-the value by the offset passed to it. If the object specified by key does
-not exist, one of two things may happen: If the expiration value is
-MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other
-expiration values, the operation will succeed by seeding the value for that
-key with a initial value to expire with the provided expiration time. The
-flags will be set to zero.The value is then returned via the unsigned int
-value pointer you pass to it.
-
-memcached_increment_by_key(), memcached_decrement_by_key(),
-memcached_increment_with_initial_by_key(), and
-memcached_decrement_with_initial_by_key() are master key equivalents of the
-above.
-
-=head1 RETURN
-
-A value of type C<memcached_return_t> is returned.
-On success that value will be C<MEMCACHED_SUCCESS>.
-Use memcached_strerror() to translate this value to a printable string.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_auto.rst b/docs/memcached_auto.rst
new file mode 100644 (file)
index 0000000..a08400e
--- /dev/null
@@ -0,0 +1,174 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_increment, memcached_decrement,
+memcached_increment_with_initial, memcached_decrement_with_initial - Manipulate
+counters
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_return_t
+     memcached_increment (memcached_st *ptr, 
+                          const char *key, size_t key_length,
+                          unsigned int offset,
+                          uint64_t *value);
+   memcached_return_t
+     memcached_decrement (memcached_st *ptr, 
+                          const char *key, size_t key_length,
+                          unsigned int offset,
+                          uint64_t *value);
+   memcached_return_t
+     memcached_increment_with_initial (memcached_st *ptr,
+                                       const char *key,
+                                       size_t key_length,
+                                       uint64_t offset,
+                                       uint64_t initial,
+                                       time_t expiration,
+                                       uint64_t *value);
+   memcached_return_t
+     memcached_decrement_with_initial (memcached_st *ptr,
+                                       const char *key,
+                                       size_t key_length,
+                                       uint64_t offset,
+                                       uint64_t initial,
+                                       time_t expiration,
+                                       uint64_t *value);
+   memcached_return_t
+     memcached_increment_by_key (memcached_st *ptr, 
+                                 const char *master_key, size_t master_key_length,
+                                 const char *key, size_t key_length,
+                                 unsigned int offset,
+                                 uint64_t *value);
+   memcached_return_t
+     memcached_decrement_by_key (memcached_st *ptr, 
+                                 const char *master_key, size_t master_key_length,
+                                 const char *key, size_t key_length,
+                                 unsigned int offset,
+                                 uint64_t *value);
+   memcached_return_t
+     memcached_increment_with_initial_by_key (memcached_st *ptr,
+                                              const char *master_key,
+                                              size_t master_key_length,
+                                              const char *key,
+                                              size_t key_length,
+                                              uint64_t offset,
+                                              uint64_t initial,
+                                              time_t expiration,
+                                              uint64_t *value);
+   memcached_return_t
+     memcached_decrement_with_initial_by_key (memcached_st *ptr,
+                                              const char *master_key,
+                                              size_t master_key_length,
+                                              const char *key,
+                                              size_t key_length,
+                                              uint64_t offset,
+                                              uint64_t initial,
+                                              time_t expiration,
+                                              uint64_t *value);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached(1) servers have the ability to increment and decrement keys
+(overflow and underflow are not detected). This gives you the ability to use
+memcached to generate shared sequences of values.
+
+memcached_increment() takes a key and keylength and increments the value by
+the offset passed to it. The value is then returned via the unsigned int
+value pointer you pass to it.
+
+memcached_decrement() takes a key and keylength and decrements the value by
+the offset passed to it. The value is then returned via the unsigned int
+value pointer you pass to it.
+
+memcached_increment_with_initial() takes a key and keylength and increments
+the value by the offset passed to it. If the object specified by key does
+not exist, one of two things may happen: If the expiration value is
+MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other
+expiration values, the operation will succeed by seeding the value for that
+key with a initial value to expire with the provided expiration time. The
+flags will be set to zero.The value is then returned via the unsigned int
+value pointer you pass to it.
+
+memcached_decrement_with_initial() takes a key and keylength and decrements
+the value by the offset passed to it. If the object specified by key does
+not exist, one of two things may happen: If the expiration value is
+MEMCACHED_EXPIRATION_NOT_ADD, the operation will fail. For all other
+expiration values, the operation will succeed by seeding the value for that
+key with a initial value to expire with the provided expiration time. The
+flags will be set to zero.The value is then returned via the unsigned int
+value pointer you pass to it.
+
+memcached_increment_by_key(), memcached_decrement_by_key(),
+memcached_increment_with_initial_by_key(), and
+memcached_decrement_with_initial_by_key() are master key equivalents of the
+above.
+
+
+******
+RETURN
+******
+
+
+A value of type \ ``memcached_return_t``\  is returned.
+On success that value will be \ ``MEMCACHED_SUCCESS``\ .
+Use memcached_strerror() to translate this value to a printable string.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_behavior.pod b/docs/memcached_behavior.pod
deleted file mode 100644 (file)
index 02ab0de..0000000
+++ /dev/null
@@ -1,297 +0,0 @@
-=head1 NAME
-
-memcached_behavior_get, memcached_behavior_set - Manipulate behavior
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  uint64_t
-    memcached_behavior_get (memcached_st *ptr,
-                            memcached_behavior flag);
-
-  memcached_return_t
-    memcached_behavior_set (memcached_st *ptr,
-                            memcached_behavior flag,
-                            uint64_t data);
-
-=head1 DESCRIPTION
-
-libmemcached(3) behavior can be modified by use memcached_behavior_set().
-Default behavior is the library strives to be quick and accurate. Some
-behavior, while being faster, can also result in not entirely accurate
-behavior (for instance, memcached_set() will always respond with
-C<MEMCACHED_SUCCESS>).
-
-memcached_behavior_get() takes a behavior flag and returns whether or not
-that behavior is currently enabled in the client.
-
-memcached_behavior_set() changes the value of a particular option of the
-client. It takes both a flag (listed below) and a value. For simple on or
-off options you just need to pass in a value of 1. Calls to
-memcached_behavior_set() will flush and reset all connections.
-
-=over 4
-
-=item MEMCACHED_BEHAVIOR_USE_UDP
-
-Causes libmemcached(3) to use the UDP transport when communicating
-with a memcached server. Not all I/O operations are supported
-when this behavior is enababled. The following operations will return
-C<MEMCACHED_NOT_SUPPORTED> when executed with the MEMCACHED_BEHAVIOR_USE_UDP
-enabled: memcached_version(), memcached_stat(), memcached_get(),
-memcached_get_by_key(), memcached_mget(), memcached_mget_by_key(),
-memcached_fetch(), memcached_fetch_result(), memcached_value_fetch().
-
-All other operations are supported but are executed in a 'fire-and-forget'
-mode, in which once the client has executed the operation, no attempt
-will be made to ensure the operation has been received and acted on by the
-server.
-
-libmemcached(3) does not allow TCP and UDP servers to be shared within
-the same libmemached(3) client 'instance'. An attempt to add a TCP server
-when this behavior is enabled will result in a C<MEMCACHED_INVALID_HOST_PROTOCOL>,
-as will attempting to add a UDP server when this behavior has not been enabled.
-
-=item MEMCACHED_BEHAVIOR_NO_BLOCK
-
-Causes libmemcached(3) to use asychronous IO. This is the fastest transport
-available for storage functions.
-
-=item MEMCACHED_BEHAVIOR_SND_TIMEOUT
-
-This sets the microsecond behavior of the socket against the SO_SNDTIMEO flag.
-In cases where you cannot use non-blocking IO this will allow you to still have
-timeouts on the sending of data.
-
-=item MEMCACHED_BEHAVIOR_RCV_TIMEOUT
-
-This sets the microsecond behavior of the socket against the SO_RCVTIMEO flag.
-In cases where you cannot use non-blocking IO this will allow you to still have
-timeouts on the reading of data.
-
-=item MEMCACHED_BEHAVIOR_TCP_NODELAY
-
-Turns on the no-delay feature for connecting sockets (may be faster in some
-environments).
-
-=item MEMCACHED_BEHAVIOR_HASH
-
-Makes the default hashing algorithm for keys use MD5. The value can be set
-to either MEMCACHED_HASH_DEFAULT, MEMCACHED_HASH_MD5, MEMCACHED_HASH_CRC, MEMCACHED_HASH_FNV1_64, MEMCACHED_HASH_FNV1A_64, MEMCACHED_HASH_FNV1_32, MEMCACHED_HASH_FNV1A_32, MEMCACHED_HASH_JENKINS, MEMCACHED_HASH_HSIEH, and MEMCACHED_HASH_MURMUR.
-Each hash has it's advantages and it's weaknesses. If you don't know or don't care, just go with the default.
-Support for MEMCACHED_HASH_HSIEH is a compile time option that is disabled by default. To enable support for this hashing algorithm, configure and build libmemcached with the --enable-hash_hsieh.
-
-=item MEMCACHED_BEHAVIOR_DISTRIBUTION
-
-Using this you can enable different means of distributing values to servers.
-The default method is MEMCACHED_DISTRIBUTION_MODULA. You can enable
-consistent hashing by setting MEMCACHED_DISTRIBUTION_CONSISTENT.
-Consistent hashing delivers better distribution and allows servers to be
-added to the cluster with minimal cache losses. Currently
-MEMCACHED_DISTRIBUTION_CONSISTENT is an alias for the value
-MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA.
-
-=item MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
-
-Memcached can cache named lookups so that DNS lookups are made only once.
-
-=item MEMCACHED_BEHAVIOR_SUPPORT_CAS
-
-Support CAS operations (this is not enabled by default at this point in the server since it imposes a slight performance penalty).
-
-=item MEMCACHED_BEHAVIOR_KETAMA
-
-Sets the default distribution to MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
-and the hash to MEMCACHED_HASH_MD5.
-
-=item MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
-
-Sets the default distribution to MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA with the weighted support.
-and the hash to MEMCACHED_HASH_MD5.
-
-=item MEMCACHED_BEHAVIOR_KETAMA_HASH
-
-Sets the hashing algorithm for host mapping on continuum. The value can be set
-to either MEMCACHED_HASH_DEFAULT, MEMCACHED_HASH_MD5, MEMCACHED_HASH_CRC, MEMCACHED_HASH_FNV1_64, MEMCACHED_HASH_FNV1A_64, MEMCACHED_HASH_FNV1_32, and MEMCACHED_HASH_FNV1A_32.
-
-=item MEMCACHED_BEHAVIOR_KETAMA_COMPAT
-
-Sets the compatibility mode. The value can be set to either
-MEMCACHED_KETAMA_COMPAT_LIBMEMCACHED (this is the default) or
-MEMCACHED_KETAMA_COMPAT_SPY to be compatible with the SPY Memcached client
-for Java.
-
-=item MEMCACHED_BEHAVIOR_POLL_TIMEOUT
-
-Modify the timeout value that is used by poll(). The default value is -1. An signed int pointer must be passed to memcached_behavior_set() to change this value. For memcached_behavior_get() a signed int value will be cast and returned as the unsigned long long.
-
-=item MEMCACHED_BEHAVIOR_USER_DATA
-
-This allows you to store a pointer to a specifc piece of data. This can be
-retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st
-
-will copy the pointer to the clone. This was deprecated in 0.14 in favor
-of memcached_callback_set(3). This will be removed in 0.15.
-
-=item MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
-
-Enabling buffered IO causes commands to "buffer" instead of being sent. Any
-action that gets data causes this buffer to be be sent to the remote
-connection. Quiting the connection or closing down the connection will also
-cause the buffered data to be pushed to the remote connection.
-
-=item MEMCACHED_BEHAVIOR_VERIFY_KEY
-
-Enabling this will cause libmemcached(3) to test all keys to verify that they
-are valid keys.
-
-=item MEMCACHED_BEHAVIOR_SORT_HOSTS
-
-Enabling this will cause hosts that are added to be placed in the host list in
-sorted order. This will defeat consisten hashing.
-
-=item MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
-
-In non-blocking mode this changes the value of the timeout during socket
-connection.
-
-=item MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
-
-Enable the use of the binary protocol. Please note that you cannot toggle
-this flag on an open connection.
-
-=item MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
-
-Set this value to enable the server be removed after continuous MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
-times connection failure.
-
-=item MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
-
-Set this value to tune the number of messages that may be sent before
-libmemcached should start to automatically drain the input queue. Setting
-this value to high, may cause libmemcached to deadlock (trying to send data,
-but the send will block because the input buffer in the kernel is full).
-
-=item MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
-
-Set this value to tune the number of bytes that may be sent before
-libmemcached should start to automatically drain the input queue (need
-at least 10 IO requests sent without reading the input buffer). Setting
-this value to high, may cause libmemcached to deadlock (trying to send
-data, but the send will block because the input buffer in the kernel is full).
-
-=item MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
-
-The binary protocol works a bit different than the textual protocol in
-that a multiget is implemented as a pipe of single get-operations which
-are sent to the server in a chunk. If you are using large multigets from
-your application, you may improve the latency of the gets by setting
-this value so you send out the first chunk of requests when you hit the
-specified limit.  It allows the servers to start processing the requests
-to send the data back while the rest of the requests are created and
-sent to the server.
-
-=item MEMCACHED_BEHAVIOR_NOREPLY
-
-Set this value to specify that you really don't care about the result
-from your storage commands (set, add, replace, append, prepend).
-
-=item MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
-
-If you just want "a poor mans HA", you may specify the numbers of
-replicas libmemcached should store of each item (on different servers).
-This replication does not dedicate certain memcached servers to store the
-replicas in, but instead it will store the replicas together with all of the
-other objects (on the 'n' next servers specified in your server list).
-
-=item 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 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.
-
-=item MEMCACHED_BEHAVIOR_CORK
-
-Enable TCP_CORK behavior. This is only available as an option Linux.
-MEMCACHED_NO_SERVERS is returned if no servers are available to test with.
-MEMCACHED_NOT_SUPPORTED is returned if we were not able to determine
-if support was available. All other responses then MEMCACHED_SUCCESS
-report an error of some sort. This behavior also enables
-MEMCACHED_BEHAVIOR_TCP_NODELAY when set.
-
-=item MEMCACHED_BEHAVIOR_KEEPALIVE
-
-Enable TCP_KEEPALIVE behavior.
-
-=item MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
-
-Specify time, in seconds, to mark a connection as idle. This is only available as an option Linux.
-
-=item MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
-
-Find the current size of SO_SNDBUF. A value of 0 means either an error
-occured or no hosts were available. It is safe to assume system default
-if this occurs. If an error occurs you can checked the last cached errno statement to find the specific error.
-
-=item MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
-
-Find the current size of SO_RCVBUF. A value of 0 means either an error
-occured or no hosts were available. It is safe to assume system default
-if this occurs. If an error occurs you can checked the last cached errno statement to find the specific error.
-
-=item MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
-
-This number of times a host can have an error before it is disabled.
-
-=item MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
-
-If enabled any hosts which have been flagged as disabled will be removed
-from the list of servers in the memcached_st structure. This must be used
-in combination with MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT.
-
-=item MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
-
-When enabled a host which is problematic will only be checked for usage
-based on the amount of time set by this behavior.
-
-=item MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
-
-When enabled the prefix key will be added to the key when determining
-server by hash.
-
-=back
-
-=head1 RETURN
-
-memcached_behavior_get() returns either the current value of the get, or 0
-or 1 on simple flag behaviors (1 being enabled). memcached_behavior_set()
-returns failure or success.
-
-=head1 NOTES
-
-memcached_behavior_set() in version .17 was changed from taking a pointer
-to data value, to taking a uin64_t.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_behavior.rst b/docs/memcached_behavior.rst
new file mode 100644 (file)
index 0000000..72815b8
--- /dev/null
@@ -0,0 +1,406 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_behavior_get, memcached_behavior_set - Manipulate behavior
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   uint64_t
+     memcached_behavior_get (memcached_st *ptr,
+                             memcached_behavior flag);
+   memcached_return_t
+     memcached_behavior_set (memcached_st *ptr,
+                             memcached_behavior flag,
+                             uint64_t data);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) behavior can be modified by use memcached_behavior_set().
+Default behavior is the library strives to be quick and accurate. Some
+behavior, while being faster, can also result in not entirely accurate
+behavior (for instance, memcached_set() will always respond with
+\ ``MEMCACHED_SUCCESS``\ ).
+
+memcached_behavior_get() takes a behavior flag and returns whether or not
+that behavior is currently enabled in the client.
+
+memcached_behavior_set() changes the value of a particular option of the
+client. It takes both a flag (listed below) and a value. For simple on or
+off options you just need to pass in a value of 1. Calls to
+memcached_behavior_set() will flush and reset all connections.
+
+
+MEMCACHED_BEHAVIOR_USE_UDP
+ Causes libmemcached(3) to use the UDP transport when communicating
+ with a memcached server. Not all I/O operations are supported
+ when this behavior is enababled. The following operations will return
+ \ ``MEMCACHED_NOT_SUPPORTED``\  when executed with the MEMCACHED_BEHAVIOR_USE_UDP
+ enabled: memcached_version(), memcached_stat(), memcached_get(),
+ memcached_get_by_key(), memcached_mget(), memcached_mget_by_key(),
+ memcached_fetch(), memcached_fetch_result(), memcached_value_fetch().
+ All other operations are supported but are executed in a 'fire-and-forget'
+ mode, in which once the client has executed the operation, no attempt
+ will be made to ensure the operation has been received and acted on by the
+ server.
+ libmemcached(3) does not allow TCP and UDP servers to be shared within
+ the same libmemached(3) client 'instance'. An attempt to add a TCP server
+ when this behavior is enabled will result in a \ ``MEMCACHED_INVALID_HOST_PROTOCOL``\ ,
+ as will attempting to add a UDP server when this behavior has not been enabled.
+
+
+MEMCACHED_BEHAVIOR_NO_BLOCK
+ Causes libmemcached(3) to use asychronous IO. This is the fastest transport
+ available for storage functions.
+
+
+MEMCACHED_BEHAVIOR_SND_TIMEOUT
+ This sets the microsecond behavior of the socket against the SO_SNDTIMEO flag.
+ In cases where you cannot use non-blocking IO this will allow you to still have
+ timeouts on the sending of data.
+
+
+MEMCACHED_BEHAVIOR_RCV_TIMEOUT
+ This sets the microsecond behavior of the socket against the SO_RCVTIMEO flag.
+ In cases where you cannot use non-blocking IO this will allow you to still have
+ timeouts on the reading of data.
+
+
+MEMCACHED_BEHAVIOR_TCP_NODELAY
+ Turns on the no-delay feature for connecting sockets (may be faster in some
+ environments).
+
+
+MEMCACHED_BEHAVIOR_HASH
+ Makes the default hashing algorithm for keys use MD5. The value can be set
+ to either MEMCACHED_HASH_DEFAULT, MEMCACHED_HASH_MD5, MEMCACHED_HASH_CRC, MEMCACHED_HASH_FNV1_64, MEMCACHED_HASH_FNV1A_64, MEMCACHED_HASH_FNV1_32, MEMCACHED_HASH_FNV1A_32, MEMCACHED_HASH_JENKINS, MEMCACHED_HASH_HSIEH, and MEMCACHED_HASH_MURMUR.
+ Each hash has it's advantages and it's weaknesses. If you don't know or don't care, just go with the default.
+ Support for MEMCACHED_HASH_HSIEH is a compile time option that is disabled by default. To enable support for this hashing algorithm, configure and build libmemcached with the --enable-hash_hsieh.
+
+
+MEMCACHED_BEHAVIOR_DISTRIBUTION
+ Using this you can enable different means of distributing values to servers.
+ The default method is MEMCACHED_DISTRIBUTION_MODULA. You can enable
+ consistent hashing by setting MEMCACHED_DISTRIBUTION_CONSISTENT.
+ Consistent hashing delivers better distribution and allows servers to be
+ added to the cluster with minimal cache losses. Currently
+ MEMCACHED_DISTRIBUTION_CONSISTENT is an alias for the value
+ MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA.
+
+
+MEMCACHED_BEHAVIOR_CACHE_LOOKUPS
+ Memcached can cache named lookups so that DNS lookups are made only once.
+
+
+MEMCACHED_BEHAVIOR_SUPPORT_CAS
+ Support CAS operations (this is not enabled by default at this point in the server since it imposes a slight performance penalty).
+
+
+MEMCACHED_BEHAVIOR_KETAMA
+ Sets the default distribution to MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA
+ and the hash to MEMCACHED_HASH_MD5.
+
+
+MEMCACHED_BEHAVIOR_KETAMA_WEIGHTED
+ Sets the default distribution to MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA with the weighted support.
+ and the hash to MEMCACHED_HASH_MD5.
+
+
+MEMCACHED_BEHAVIOR_KETAMA_HASH
+ Sets the hashing algorithm for host mapping on continuum. The value can be set
+ to either MEMCACHED_HASH_DEFAULT, MEMCACHED_HASH_MD5, MEMCACHED_HASH_CRC, MEMCACHED_HASH_FNV1_64, MEMCACHED_HASH_FNV1A_64, MEMCACHED_HASH_FNV1_32, and MEMCACHED_HASH_FNV1A_32.
+
+
+MEMCACHED_BEHAVIOR_KETAMA_COMPAT
+ Sets the compatibility mode. The value can be set to either
+ MEMCACHED_KETAMA_COMPAT_LIBMEMCACHED (this is the default) or
+ MEMCACHED_KETAMA_COMPAT_SPY to be compatible with the SPY Memcached client
+ for Java.
+
+
+MEMCACHED_BEHAVIOR_POLL_TIMEOUT
+ Modify the timeout value that is used by poll(). The default value is -1. An signed int pointer must be passed to memcached_behavior_set() to change this value. For memcached_behavior_get() a signed int value will be cast and returned as the unsigned long long.
+
+
+MEMCACHED_BEHAVIOR_USER_DATA
+ This allows you to store a pointer to a specifc piece of data. This can be
+ retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st
+ will copy the pointer to the clone. This was deprecated in 0.14 in favor
+ of memcached_callback_set(3). This will be removed in 0.15.
+
+
+MEMCACHED_BEHAVIOR_BUFFER_REQUESTS
+ Enabling buffered IO causes commands to "buffer" instead of being sent. Any
+ action that gets data causes this buffer to be be sent to the remote
+ connection. Quiting the connection or closing down the connection will also
+ cause the buffered data to be pushed to the remote connection.
+
+
+MEMCACHED_BEHAVIOR_VERIFY_KEY
+ Enabling this will cause libmemcached(3) to test all keys to verify that they
+ are valid keys.
+
+
+MEMCACHED_BEHAVIOR_SORT_HOSTS
+ Enabling this will cause hosts that are added to be placed in the host list in
+ sorted order. This will defeat consisten hashing.
+
+
+MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT
+ In non-blocking mode this changes the value of the timeout during socket
+ connection.
+
+
+MEMCACHED_BEHAVIOR_BINARY_PROTOCOL
+ Enable the use of the binary protocol. Please note that you cannot toggle
+ this flag on an open connection.
+
+
+MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
+ Set this value to enable the server be removed after continuous MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
+ times connection failure.
+
+
+MEMCACHED_BEHAVIOR_IO_MSG_WATERMARK
+ Set this value to tune the number of messages that may be sent before
+ libmemcached should start to automatically drain the input queue. Setting
+ this value to high, may cause libmemcached to deadlock (trying to send data,
+ but the send will block because the input buffer in the kernel is full).
+
+
+MEMCACHED_BEHAVIOR_IO_BYTES_WATERMARK
+ Set this value to tune the number of bytes that may be sent before
+ libmemcached should start to automatically drain the input queue (need
+ at least 10 IO requests sent without reading the input buffer). Setting
+ this value to high, may cause libmemcached to deadlock (trying to send
+ data, but the send will block because the input buffer in the kernel is full).
+
+
+MEMCACHED_BEHAVIOR_IO_KEY_PREFETCH
+ The binary protocol works a bit different than the textual protocol in
+ that a multiget is implemented as a pipe of single get-operations which
+ are sent to the server in a chunk. If you are using large multigets from
+ your application, you may improve the latency of the gets by setting
+ this value so you send out the first chunk of requests when you hit the
+ specified limit.  It allows the servers to start processing the requests
+ to send the data back while the rest of the requests are created and
+ sent to the server.
+
+
+MEMCACHED_BEHAVIOR_NOREPLY
+ Set this value to specify that you really don't care about the result
+ from your storage commands (set, add, replace, append, prepend).
+
+
+MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
+ If you just want "a poor mans HA", you may specify the numbers of
+ replicas libmemcached should store of each item (on different servers).
+ This replication does not dedicate certain memcached servers to store the
+ replicas in, but instead it will store the replicas together with all of the
+ other objects (on the 'n' next servers specified in your server list).
+
+
+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 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.
+
+
+MEMCACHED_BEHAVIOR_CORK
+ Enable TCP_CORK behavior. This is only available as an option Linux.
+ MEMCACHED_NO_SERVERS is returned if no servers are available to test with.
+ MEMCACHED_NOT_SUPPORTED is returned if we were not able to determine
+ if support was available. All other responses then MEMCACHED_SUCCESS
+ report an error of some sort. This behavior also enables
+ MEMCACHED_BEHAVIOR_TCP_NODELAY when set.
+
+
+MEMCACHED_BEHAVIOR_KEEPALIVE
+ Enable TCP_KEEPALIVE behavior.
+
+
+MEMCACHED_BEHAVIOR_KEEPALIVE_IDLE
+ Specify time, in seconds, to mark a connection as idle. This is only available as an option Linux.
+
+
+MEMCACHED_BEHAVIOR_SOCKET_SEND_SIZE
+ Find the current size of SO_SNDBUF. A value of 0 means either an error
+ occured or no hosts were available. It is safe to assume system default
+ if this occurs. If an error occurs you can checked the last cached errno statement to find the specific error.
+
+
+MEMCACHED_BEHAVIOR_SOCKET_RECV_SIZE
+ Find the current size of SO_RCVBUF. A value of 0 means either an error
+ occured or no hosts were available. It is safe to assume system default
+ if this occurs. If an error occurs you can checked the last cached errno statement to find the specific error.
+
+
+MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT
+ This number of times a host can have an error before it is disabled.
+
+
+MEMCACHED_BEHAVIOR_AUTO_EJECT_HOSTS
+ If enabled any hosts which have been flagged as disabled will be removed
+ from the list of servers in the memcached_st structure. This must be used
+ in combination with MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT.
+
+
+MEMCACHED_BEHAVIOR_RETRY_TIMEOUT
+ When enabled a host which is problematic will only be checked for usage
+ based on the amount of time set by this behavior.
+
+
+MEMCACHED_BEHAVIOR_HASH_WITH_PREFIX_KEY
+ When enabled the prefix key will be added to the key when determining
+ server by hash.
+
+
+
+******
+RETURN
+******
+
+
+memcached_behavior_get() returns either the current value of the get, or 0
+or 1 on simple flag behaviors (1 being enabled). memcached_behavior_set()
+returns failure or success.
+
+
+*****
+NOTES
+*****
+
+
+memcached_behavior_set() in version .17 was changed from taking a pointer
+to data value, to taking a uin64_t.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_callback.pod b/docs/memcached_callback.pod
deleted file mode 100644 (file)
index 9175c29..0000000
+++ /dev/null
@@ -1,123 +0,0 @@
-=head1 NAME
-
-memcached_callback_get, memcached_callback_set - Get and set a callback
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_return_t 
-    memcached_callback_set (memcached_st *ptr, 
-                            memcached_callback_t flag, 
-                            void *data);
-
-  void *
-    memcached_callback_get (memcached_st *ptr, 
-                            memcached_callback_t flag,
-                            memcached_return_t *error);
-
-=head1 DESCRIPTION
-
-libmemcached(3) can have callbacks set key execution points. These either
-provide function calls at points in the code, or return pointers to
-structures for particular usages.
-
-memcached_callback_get() takes a callback flag and returns the structure or
-function set by memcached_callback_set().
-
-memcached_callback_set() changes the function/structure assigned by a
-callback flag. No connections are reset. 
-
-You can use MEMCACHED_CALLBACK_USER_DATA to provide custom context if required for any 
-of the callbacks
-
-=over 4
-
-=item MEMCACHED_CALLBACK_CLEANUP_FUNCTION
-
-When memcached_delete() is called this function will be excuted. At the
-point of its execution all connections have been closed.
-
-=item MEMCACHED_CALLBACK_CLONE_FUNCTION
-
-When memcached_delete() is called this function will be excuted. At the
-point of its execution all connections have been closed.
-
-=item MEMCACHED_CALLBACK_PREFIX_KEY
-
-You can set a value which will be used to create a domain for your keys.
-The value specified here will be prefixed to each of your keys. The value can not
-be greater then MEMCACHED_PREFIX_KEY_MAX_SIZE - 1 and will reduce MEMCACHED_MAX_KEY by
-the value of your key. The prefix key is only applied to the primary key,
-not the master key. MEMCACHED_FAILURE will be returned if no key is set. In the case
-of a key which is too long MEMCACHED_BAD_KEY_PROVIDED will be returned.
-
-=item MEMCACHED_CALLBACK_USER_DATA
-
-This allows you to store a pointer to a specifc piece of data. This can be
-retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st
-will copy the pointer to the clone.
-
-=item  MEMCACHED_CALLBACK_MALLOC_FUNCTION
-
-DEPRECATED: use memcached_set_memory_allocators instead.
-
-=item  MEMCACHED_CALLBACK_REALLOC_FUNCTION
-
-DEPRECATED: use memcached_set_memory_allocators instead.
-
-=item  MEMCACHED_CALLBACK_FREE_FUNCTION
-
-DEPRECATED: use memcached_set_memory_allocators instead.
-
-=item  MEMCACHED_CALLBACK_GET_FAILURE
-
-This function implements the read through cache behavior. On failure of retrieval this callback will be called. 
-You are responsible for populating the result object provided. This result object will then be stored in the server and
-returned to the calling process. You must clone the memcached_st in order to
-make use of it. The value will be stored only if you return
-MEMCACHED_SUCCESS or MEMCACHED_BUFFERED. Returning MEMCACHED_BUFFERED will
-cause the object to be buffered and not sent immediatly (if this is the default behavior based on your connection setup this will happen automatically).
-
-The prototype for this is:
-memcached_return_t (*memcached_trigger_key)(memcached_st *ptr, char *key, size_t key_length, memcached_result_st *result);
-
-=item  MEMCACHED_CALLBACK_DELETE_TRIGGER
-
-This function implements a trigger upon successful deletion of a key. The memcached_st structure will need to be cloned
-in order to make use of it.
-
-The prototype for this is:
-typedef memcached_return_t (*memcached_trigger_delete_key)(memcached_st *ptr, char *key, size_t key_length);
-
-
-=back
-
-=head1 RETURN
-
-memcached_callback_get() return the function or structure that was provided.
-Upon error, nothing is set, null is returned, and the memcached_return_t
-argument is set to MEMCACHED_FAILURE.
-
-memcached_callback_set() returns MEMCACHED_SUCCESS upon successful setting,
-otherwise MEMCACHED_FAILURE on error.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_callback.rst b/docs/memcached_callback.rst
new file mode 100644 (file)
index 0000000..e830b7a
--- /dev/null
@@ -0,0 +1,173 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_callback_get, memcached_callback_set - Get and set a callback
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_return_t 
+     memcached_callback_set (memcached_st *ptr, 
+                             memcached_callback_t flag, 
+                             void *data);
+   void *
+     memcached_callback_get (memcached_st *ptr, 
+                             memcached_callback_t flag,
+                             memcached_return_t *error);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) can have callbacks set key execution points. These either
+provide function calls at points in the code, or return pointers to
+structures for particular usages.
+
+memcached_callback_get() takes a callback flag and returns the structure or
+function set by memcached_callback_set().
+
+memcached_callback_set() changes the function/structure assigned by a
+callback flag. No connections are reset.
+
+You can use MEMCACHED_CALLBACK_USER_DATA to provide custom context if required for any 
+of the callbacks
+
+
+MEMCACHED_CALLBACK_CLEANUP_FUNCTION
+ When memcached_delete() is called this function will be excuted. At the
+ point of its execution all connections have been closed.
+
+
+MEMCACHED_CALLBACK_CLONE_FUNCTION
+ When memcached_delete() is called this function will be excuted. At the
+ point of its execution all connections have been closed.
+
+
+MEMCACHED_CALLBACK_PREFIX_KEY
+ You can set a value which will be used to create a domain for your keys.
+ The value specified here will be prefixed to each of your keys. The value can not
+ be greater then MEMCACHED_PREFIX_KEY_MAX_SIZE - 1 and will reduce MEMCACHED_MAX_KEY by
+ the value of your key. The prefix key is only applied to the primary key,
+ not the master key. MEMCACHED_FAILURE will be returned if no key is set. In the case
+ of a key which is too long MEMCACHED_BAD_KEY_PROVIDED will be returned.
+
+
+MEMCACHED_CALLBACK_USER_DATA
+ This allows you to store a pointer to a specifc piece of data. This can be
+ retrieved from inside of memcached_fetch_execute(). Cloning a memcached_st
+ will copy the pointer to the clone.
+
+
+MEMCACHED_CALLBACK_MALLOC_FUNCTION
+ DEPRECATED: use memcached_set_memory_allocators instead.
+
+
+MEMCACHED_CALLBACK_REALLOC_FUNCTION
+ DEPRECATED: use memcached_set_memory_allocators instead.
+
+
+MEMCACHED_CALLBACK_FREE_FUNCTION
+ DEPRECATED: use memcached_set_memory_allocators instead.
+
+
+MEMCACHED_CALLBACK_GET_FAILURE
+ This function implements the read through cache behavior. On failure of retrieval this callback will be called. 
+ You are responsible for populating the result object provided. This result object will then be stored in the server and
+ returned to the calling process. You must clone the memcached_st in order to
+ make use of it. The value will be stored only if you return
+ MEMCACHED_SUCCESS or MEMCACHED_BUFFERED. Returning MEMCACHED_BUFFERED will
+ cause the object to be buffered and not sent immediatly (if this is the default behavior based on your connection setup this will happen automatically).
+ The prototype for this is:
+ memcached_return_t (\*memcached_trigger_key)(memcached_st \*ptr, char \*key, size_t key_length, memcached_result_st \*result);
+
+
+MEMCACHED_CALLBACK_DELETE_TRIGGER
+ This function implements a trigger upon successful deletion of a key. The memcached_st structure will need to be cloned
+ in order to make use of it.
+ The prototype for this is:
+ typedef memcached_return_t (\*memcached_trigger_delete_key)(memcached_st \*ptr, char \*key, size_t key_length);
+
+
+
+******
+RETURN
+******
+
+
+memcached_callback_get() return the function or structure that was provided.
+Upon error, nothing is set, null is returned, and the memcached_return_t
+argument is set to MEMCACHED_FAILURE.
+
+memcached_callback_set() returns MEMCACHED_SUCCESS upon successful setting,
+otherwise MEMCACHED_FAILURE on error.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_create.pod b/docs/memcached_create.pod
deleted file mode 100644 (file)
index 4323723..0000000
+++ /dev/null
@@ -1,67 +0,0 @@
-=head1 NAME
-
-memcached_create, memcached_free, memcached_clone, memcached_servers_reset- Create a memcached_st structure
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_st *memcached_create (memcached_st *ptr);
-
-  void memcached_free (memcached_st *ptr);
-
-  memcached_st *memcached_clone (memcached_st *destination, memcached_st *source);
-
-  void memcached_servers_reset(memcached_st);
-
-=head1 DESCRIPTION
-
-memcached_create() is used to create a C<memcached_st> structure that will then
-be used by other libmemcached(3) functions to communicate with the server. You
-should either pass a statically declared C<memcached_st> to memcached_create() or
-a NULL. If a NULL passed in then a structure is allocated for you.
-
-memcached_clone() is similar to memcached_create(3) but it copies the
-defaults and list of servers from the source C<memcached_st>. If you pass a null as
-the argument for the source to clone, it is the same as a call to memcached_create().
-If the destination argument is NULL a C<memcached_st> will be allocated for you.
-
-memcached_servers_reset() allows you to zero out the list of servers that
-the memcached_st has.
-
-To clean up memory associated with a C<memcached_st> structure you should pass
-it to memcached_free() when you are finished using it. memcached_free() is
-the only way to make sure all memory is deallocated when you finish using
-the structure.
-
-You may wish to avoid using memcached_create(3) or memcached_clone(3) with a
-stack based allocation. The most common issues related to ABI safety involve
-heap allocated structures.
-
-=head1 RETURN
-
-memcached_create() returns a pointer to the memcached_st that was created
-(or initialized). On an allocation failure, it returns NULL.
-
-memcached_clone() returns a pointer to the memcached_st that was created
-(or initialized). On an allocation failure, it returns NULL.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_create.rst b/docs/memcached_create.rst
new file mode 100644 (file)
index 0000000..31f4af9
--- /dev/null
@@ -0,0 +1,103 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_create, memcached_free, memcached_clone, memcached_servers_reset- Create a memcached_st structure
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_st *memcached_create (memcached_st *ptr);
+   void memcached_free (memcached_st *ptr);
+   memcached_st *memcached_clone (memcached_st *destination, memcached_st *source);
+   void memcached_servers_reset(memcached_st);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_create() is used to create a \ ``memcached_st``\  structure that will then
+be used by other libmemcached(3) functions to communicate with the server. You
+should either pass a statically declared \ ``memcached_st``\  to memcached_create() or
+a NULL. If a NULL passed in then a structure is allocated for you.
+
+memcached_clone() is similar to memcached_create(3) but it copies the
+defaults and list of servers from the source \ ``memcached_st``\ . If you pass a null as
+the argument for the source to clone, it is the same as a call to memcached_create().
+If the destination argument is NULL a \ ``memcached_st``\  will be allocated for you.
+
+memcached_servers_reset() allows you to zero out the list of servers that
+the memcached_st has.
+
+To clean up memory associated with a \ ``memcached_st``\  structure you should pass
+it to memcached_free() when you are finished using it. memcached_free() is
+the only way to make sure all memory is deallocated when you finish using
+the structure.
+
+You may wish to avoid using memcached_create(3) or memcached_clone(3) with a
+stack based allocation. The most common issues related to ABI safety involve
+heap allocated structures.
+
+
+******
+RETURN
+******
+
+
+memcached_create() returns a pointer to the memcached_st that was created
+(or initialized). On an allocation failure, it returns NULL.
+
+memcached_clone() returns a pointer to the memcached_st that was created
+(or initialized). On an allocation failure, it returns NULL.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_delete.pod b/docs/memcached_delete.pod
deleted file mode 100644 (file)
index e104eab..0000000
+++ /dev/null
@@ -1,61 +0,0 @@
-=head1 NAME
-
-memcached_delete - Delete a key
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_return_t
-    memcached_delete (memcached_st *ptr,
-                      const char *key, size_t key_length,
-                      time_t expiration);
-
-  memcached_return_t
-  memcached_delete_by_key (memcached_st *ptr,
-                           const char *master_key, size_t master_key_length,
-                           const char *key, size_t key_length,
-                           time_t expiration);
-
-=head1 DESCRIPTION
-
-memcached_delete() is used to delete a particular key. 
-memcached_delete_by_key() works the same, but it takes a master key to
-find the given value.
-
-Expiration works by placing the item into a delete queue, which means that
-it won't possible to retrieve it by the "get" command, but "add" and 
-"replace" command with this key will also fail (the "set" command will 
-succeed, however). After the time passes, the item is finally deleted from server memory.
-
-Please note the the Danga memcached server removed support for expiration in
-the 1.4 version.
-
-=head1 RETURN
-
-A value of type C<memcached_return_t> is returned
-On success that value will be C<MEMCACHED_SUCCESS>.
-Use memcached_strerror() to translate this value to a printable string.
-
-If you are using the non-blocking mode of the library, success only
-means that the message was queued for delivery.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_delete.rst b/docs/memcached_delete.rst
new file mode 100644 (file)
index 0000000..7c99276
--- /dev/null
@@ -0,0 +1,97 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_delete - Delete a key
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_return_t
+     memcached_delete (memcached_st *ptr,
+                       const char *key, size_t key_length,
+                       time_t expiration);
+   memcached_return_t
+   memcached_delete_by_key (memcached_st *ptr,
+                            const char *master_key, size_t master_key_length,
+                            const char *key, size_t key_length,
+                            time_t expiration);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_delete() is used to delete a particular key. 
+memcached_delete_by_key() works the same, but it takes a master key to
+find the given value.
+
+Expiration works by placing the item into a delete queue, which means that
+it won't possible to retrieve it by the "get" command, but "add" and 
+"replace" command with this key will also fail (the "set" command will 
+succeed, however). After the time passes, the item is finally deleted from server memory.
+
+Please note the the Danga memcached server removed support for expiration in
+the 1.4 version.
+
+
+******
+RETURN
+******
+
+
+A value of type \ ``memcached_return_t``\  is returned
+On success that value will be \ ``MEMCACHED_SUCCESS``\ .
+Use memcached_strerror() to translate this value to a printable string.
+
+If you are using the non-blocking mode of the library, success only
+means that the message was queued for delivery.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_dump.pod b/docs/memcached_dump.pod
deleted file mode 100644 (file)
index 2d53701..0000000
+++ /dev/null
@@ -1,53 +0,0 @@
-=head1 NAME
-
-memcached_dump - get a list of keys found on memcached servers
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_return_t
-    memcached_dump (memcached_st *ptr, 
-                    memcached_dump_fn *function, 
-                    void *context, 
-                    uint32_t number_of_callbacks);
-
-  typedef memcached_return_t (*memcached_dump_fn)(memcached_st *ptr,  
-                                                  const char *key, 
-                                                  size_t key_length, 
-                                                  void *context);
-
-=head1 DESCRIPTION
-
-memcached_dump() is used to get a list of keys found  memcached(1) servers.
-Because memcached(1) does not guarentee to dump all keys you can not assume
-you have fetched all keys from the server. The function takes an array
-of callbacks that it will use to execute on keys as they are found.
-
-Currently the binar protocol is not supported.
-
-=head1 RETURN
-
-A value of type C<memcached_return_t> is returned
-On success that value will be C<MEMCACHED_SUCCESS>.
-Use memcached_strerror() to translate this value to a printable string.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_dump.rst b/docs/memcached_dump.rst
new file mode 100644 (file)
index 0000000..c9c110f
--- /dev/null
@@ -0,0 +1,89 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_dump - get a list of keys found on memcached servers
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_return_t
+     memcached_dump (memcached_st *ptr, 
+                     memcached_dump_fn *function, 
+                     void *context, 
+                     uint32_t number_of_callbacks);
+   typedef memcached_return_t (*memcached_dump_fn)(memcached_st *ptr,  
+                                                   const char *key, 
+                                                   size_t key_length, 
+                                                   void *context);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_dump() is used to get a list of keys found  memcached(1) servers.
+Because memcached(1) does not guarentee to dump all keys you can not assume
+you have fetched all keys from the server. The function takes an array
+of callbacks that it will use to execute on keys as they are found.
+
+Currently the binar protocol is not supported.
+
+
+******
+RETURN
+******
+
+
+A value of type \ ``memcached_return_t``\  is returned
+On success that value will be \ ``MEMCACHED_SUCCESS``\ .
+Use memcached_strerror() to translate this value to a printable string.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_flush.pod b/docs/memcached_flush.pod
deleted file mode 100644 (file)
index 0ca9547..0000000
+++ /dev/null
@@ -1,46 +0,0 @@
-=head1 NAME
-
-memcached_flush - wipe contents of memcached servers
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_return_t
-    memcached_flush (memcached_st *ptr,
-                     time_t expiration);
-
-=head1 DESCRIPTION
-
-memcached_flush() is used to wipe clean the contents of memcached(1) servers.
-It will either do this immediately or expire the content based on the
-expiration time passed to the method (a value of zero causes an immediate
-flush). The operation is not atomic to multiple servers, just atomic to a
-single server. That is, it will flush the servers in the order that they were
-added.
-
-=head1 RETURN
-
-A value of type C<memcached_return_t> is returned
-On success that value will be C<MEMCACHED_SUCCESS>.
-Use memcached_strerror() to translate this value to a printable string.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_flush.rst b/docs/memcached_flush.rst
new file mode 100644 (file)
index 0000000..0c6538b
--- /dev/null
@@ -0,0 +1,82 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_flush - wipe contents of memcached servers
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_return_t
+     memcached_flush (memcached_st *ptr,
+                      time_t expiration);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_flush() is used to wipe clean the contents of memcached(1) servers.
+It will either do this immediately or expire the content based on the
+expiration time passed to the method (a value of zero causes an immediate
+flush). The operation is not atomic to multiple servers, just atomic to a
+single server. That is, it will flush the servers in the order that they were
+added.
+
+
+******
+RETURN
+******
+
+
+A value of type \ ``memcached_return_t``\  is returned
+On success that value will be \ ``MEMCACHED_SUCCESS``\ .
+Use memcached_strerror() to translate this value to a printable string.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_flush_buffers.pod b/docs/memcached_flush_buffers.pod
deleted file mode 100644 (file)
index 11c06dc..0000000
+++ /dev/null
@@ -1,42 +0,0 @@
-=head1 NAME
-
-memcached_flush_buffers - Flush buffers and send buffered commands
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_return_t
-    memcached_flush_buffers (memcached_st *ptr);
-
-=head1 DESCRIPTION
-
-memcached_flush_buffers() is used in conjunction with 
-MEMCACHED_BEHAVIOR_BUFFER_REQUESTS (see memcached_behavior(3)) to flush
-all buffers by sending the buffered commands to the server for processing.
-
-=head1 RETURN
-
-A value of type C<memcached_return_t> is returned
-On success that value will be C<MEMCACHED_SUCCESS>.
-Use memcached_strerror() to translate this value to a printable string.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Trond Norbye, E<lt>trond.norbye@gmail.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3) memcached_behavior(3)
-
-=cut
-
diff --git a/docs/memcached_flush_buffers.rst b/docs/memcached_flush_buffers.rst
new file mode 100644 (file)
index 0000000..497d96e
--- /dev/null
@@ -0,0 +1,78 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_flush_buffers - Flush buffers and send buffered commands
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_return_t
+     memcached_flush_buffers (memcached_st *ptr);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_flush_buffers() is used in conjunction with 
+MEMCACHED_BEHAVIOR_BUFFER_REQUESTS (see memcached_behavior(3)) to flush
+all buffers by sending the buffered commands to the server for processing.
+
+
+******
+RETURN
+******
+
+
+A value of type \ ``memcached_return_t``\  is returned
+On success that value will be \ ``MEMCACHED_SUCCESS``\ .
+Use memcached_strerror() to translate this value to a printable string.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Trond Norbye, <trond.norbye@gmail.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3) memcached_behavior(3)
+
diff --git a/docs/memcached_generate_hash_value.pod b/docs/memcached_generate_hash_value.pod
deleted file mode 100644 (file)
index a2af1fc..0000000
+++ /dev/null
@@ -1,60 +0,0 @@
-=head1 NAME
-
-memcached_generate_hash_value - Hash a key value
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  uint32_t
-    memcached_generate_hash_value (const char *key,
-                                   size_t key_length,
-                                   memcached_hash_t hash_algorithm);
-
-  uint32_t 
-    memcached_generate_hash (memcached_st *ptr,
-                             const char *key, 
-                             size_t key_length);
-
-=head1 DESCRIPTION
-
-memcached_generate_hash_value() allows you to hash a key using one of
-the hash functions defined in the library. This method is provided for
-the convenience of higher-level language bindings and is not necessary
-for normal memcache operations.
-
-The allowed hash algorithm constants are listed in the manpage for
-memcached_behavior_set().
-
-memcached_generate_hash() takes a memcached_st struture and produces
-the hash value that would have been generated based on the defaults
-of the memcached_st structure.
-
-As of version 0.36 all hash methods have been placed into the library
-libhashkit(3) which is linked with libmemcached(3).
-
-=head1 RETURN
-
-A 32-bit integer which is the result of hashing the given key.
-For 64-bit hash algorithms, only the least-significant 32 bits are
-returned.
-
-=head1 HOME
-
-To find out more information please check: 
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_behavior_set(3) libhashkit(3)
-
-=cut
-
diff --git a/docs/memcached_generate_hash_value.rst b/docs/memcached_generate_hash_value.rst
new file mode 100644 (file)
index 0000000..278bf9c
--- /dev/null
@@ -0,0 +1,96 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_generate_hash_value - Hash a key value
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   uint32_t
+     memcached_generate_hash_value (const char *key,
+                                    size_t key_length,
+                                    memcached_hash_t hash_algorithm);
+   uint32_t 
+     memcached_generate_hash (memcached_st *ptr,
+                              const char *key, 
+                              size_t key_length);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_generate_hash_value() allows you to hash a key using one of
+the hash functions defined in the library. This method is provided for
+the convenience of higher-level language bindings and is not necessary
+for normal memcache operations.
+
+The allowed hash algorithm constants are listed in the manpage for
+memcached_behavior_set().
+
+memcached_generate_hash() takes a memcached_st struture and produces
+the hash value that would have been generated based on the defaults
+of the memcached_st structure.
+
+As of version 0.36 all hash methods have been placed into the library
+libhashkit(3) which is linked with libmemcached(3).
+
+
+******
+RETURN
+******
+
+
+A 32-bit integer which is the result of hashing the given key.
+For 64-bit hash algorithms, only the least-significant 32 bits are
+returned.
+
+
+****
+HOME
+****
+
+
+To find out more information please check: 
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_behavior_set(3) libhashkit(3)
+
diff --git a/docs/memcached_get.pod b/docs/memcached_get.pod
deleted file mode 100644 (file)
index 5faa2db..0000000
+++ /dev/null
@@ -1,177 +0,0 @@
-=head1 NAME
-
-memcached_get, memcached_mget, memcached_fetch, memcached_mget_execute,
-memcached_mget_execute_by_key - Get a value
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_result_st *
-    memcached_fetch_result (memcached_st *ptr,
-                            memcached_result_st *result,
-                            memcached_return_t *error);
-
-  char *
-    memcached_get (memcached_st *ptr,
-                   const char *key, size_t key_length,
-                   size_t *value_length,
-                   uint32_t *flags,
-                   memcached_return_t *error);
-
-  memcached_return_t
-    memcached_mget (memcached_st *ptr,
-                  const char * const *keys,
-                  const size_t *key_length,
-                  size_t number_of_keys);
-  char *
-    memcached_get_by_key (memcached_st *ptr,
-                          const char *master_key, size_t master_key_length,
-                          const char *key, size_t key_length,
-                          size_t *value_length,
-                          uint32_t *flags,
-                          memcached_return_t *error);
-
-  memcached_return_t
-    memcached_mget_by_key (memcached_st *ptr,
-                           const char *master_key, size_t master_key_length,
-                           const char * const *keys,
-                           const size_t *key_length,
-                           size_t number_of_keys);
-
-  char *
-    memcached_fetch (memcached_st *ptr,
-                     char *key, size_t *key_length,
-                     size_t *value_length,
-                     uint32_t *flags,
-                     memcached_return_t *error);
-
-  memcached_return_t
-    memcached_fetch_execute (memcached_st *ptr,
-                             memcached_execute_fn *callback,
-                             void *context,
-                             uint32_t number_of_callbacks);
-
-
-  memcached_return_t
-    memcached_mget_execute (memcached_st *ptr,
-                            const char * const *keys,
-                            const size_t *key_length,
-                            size_t number_of_keys,
-                            memcached_execute_fn *callback,
-                            void *context,
-                            uint32_t number_of_callbacks);
-
-  memcached_return_t
-    memcached_mget_execute_by_key (memcached_st *ptr,
-                                   const char *master_key,
-                                   size_t master_key_length,
-                                   const char * const *keys,
-                                   const size_t *key_length,
-                                   size_t number_of_keys,
-                                   memcached_execute_fn *callback,
-                                   void *context,
-                                   uint32_t number_of_callbacks);
-
-
-=head1 DESCRIPTION
-
-memcached_get() is used to fetch an individual value from the server. You
-must pass in a key and its length to fetch the object. You must supply
-three pointer variables which will give you the state of the returned
-object.  A uint32_t pointer to contain whatever flags you stored with the value,
-a size_t pointer which will be filled with size of of the object, and a
-memcached_return_t pointer to hold any error. The object will be returned
-upon success and NULL will be returned on failure. Any object returned by
-memcached_get() must be released by the caller application.
-
-memcached_mget() is used to select multiple keys at once. For multiple key
-operations it is always faster to use this function. This function always
-works asynchronously. memcached_fetch() is then used to retrieve any keys
-found. No error is given on keys that are not found. You must call either
-memcached_fetch() or memcached_fetch_result() after a successful call to
-memcached_mget(). You should continue to call these functions until they
-return NULL (aka no more values). If you need to quit in the middle of a
-memcached_get() call, execute a memcached_quit(). After you do this, you can
-issue new queries against the server.
-
-memcached_fetch() is used to fetch an individual value from the server.
-memcached_mget() must always be called before using this method.  You
-must pass in a key and its length to fetch the object. You must supply
-three pointer variables which will give you the state of the returned
-object.  A uint32_t pointer to contain whatever flags you stored with the value,
-a size_t pointer which will be filled with size of of the object, and a
-memcached_return_t pointer to hold any error. The object will be returned
-upon success and NULL will be returned on failure. MEMCACHD_END is returned
-by the *error value when all objects that have been found are returned.
-The final value upon MEMCACHED_END is null. Values returned by
-memcached_fetch() musted be free'ed by the caller. memcached_fetch() will
-be DEPRECATED in the near future, memcached_fetch_result() should be used
-instead.
-
-memcached_fetch_result() is used to return a memcached_result_st(3) structure
-from a memcached server. The result object is forward compatible with changes
-to the server. For more information please refer to the memcached_result_st(3)
-help. This function will dynamically allocate a result structure for you
-if you do not pass one to the function.
-
-memcached_fetch_execute() is a callback function for result sets. Instead
-of returning the results to you for processing, it passes each of the
-result sets to the list of functions you provide. It passes to the function
-a memcached_st that can be cloned for use in the called function (it can not
-be used directly). It also passes a result set which does not need to be freed.
-Finally it passes a "context". This is just a pointer to a memory reference
-you supply the calling function. Currently only one value is being passed
-to each function call. In the future there will be an option to allow this
-to be an array.
-
-memcached_mget_execute() and memcached_mget_execute_by_key() is
-similar to memcached_mget(), but it may trigger the supplied callbacks
-with result sets while sending out the queries. If you try to perform
-a really large multiget with memcached_mget() you may encounter a
-deadlock in the OS kernel (we fail to write data to the socket because
-the input buffer is full). memcached_mget_execute() solves this
-problem by processing some of the results before continuing sending
-out requests. Please note that this function is only available in the
-binary protocol.
-
-memcached_get_by_key() and memcached_mget_by_key() behave in a similar nature
-as memcached_get() and memcached_mget(). The difference is that they take
-a master key that is used for determining which server an object was stored
-if key partitioning was used for storage.
-
-All of the above functions are not supported when the C<MEMCACHED_BEHAVIOR_USE_UDP>
-has been set. Executing any of these functions with this behavior on will result in
-C<MEMCACHED_NOT_SUPPORTED> being returned or, for those functions which do not return
-a C<memcached_return_t>, the error function parameter will be set to
-C<MEMCACHED_NOT_SUPPORTED>.
-
-=head1 RETURN
-
-All objects returned must be freed by the calling application.
-memcached_get() and memcached_fetch() will return NULL on error. You must
-look at the value of error to determine what the actual error was.
-
-MEMCACHED_KEY_TOO_BIG is set to error whenever memcached_fetch() was used
-and the key was set larger then MEMCACHED_MAX_KEY, which was the largest
-key allowed for the original memcached ascii server.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_get.rst b/docs/memcached_get.rst
new file mode 100644 (file)
index 0000000..a489af4
--- /dev/null
@@ -0,0 +1,212 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_get, memcached_mget, memcached_fetch, memcached_mget_execute,
+memcached_mget_execute_by_key - Get a value
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_result_st *
+     memcached_fetch_result (memcached_st *ptr,
+                             memcached_result_st *result,
+                             memcached_return_t *error);
+   char *
+     memcached_get (memcached_st *ptr,
+                    const char *key, size_t key_length,
+                    size_t *value_length,
+                    uint32_t *flags,
+                    memcached_return_t *error);
+   memcached_return_t
+     memcached_mget (memcached_st *ptr,
+                   const char * const *keys,
+                   const size_t *key_length,
+                   size_t number_of_keys);
+   char *
+     memcached_get_by_key (memcached_st *ptr,
+                           const char *master_key, size_t master_key_length,
+                           const char *key, size_t key_length,
+                           size_t *value_length,
+                           uint32_t *flags,
+                           memcached_return_t *error);
+   memcached_return_t
+     memcached_mget_by_key (memcached_st *ptr,
+                            const char *master_key, size_t master_key_length,
+                            const char * const *keys,
+                            const size_t *key_length,
+                            size_t number_of_keys);
+   char *
+     memcached_fetch (memcached_st *ptr,
+                      char *key, size_t *key_length,
+                      size_t *value_length,
+                      uint32_t *flags,
+                      memcached_return_t *error);
+   memcached_return_t
+     memcached_fetch_execute (memcached_st *ptr,
+                              memcached_execute_fn *callback,
+                              void *context,
+                              uint32_t number_of_callbacks);
+   memcached_return_t
+     memcached_mget_execute (memcached_st *ptr,
+                             const char * const *keys,
+                             const size_t *key_length,
+                             size_t number_of_keys,
+                             memcached_execute_fn *callback,
+                             void *context,
+                             uint32_t number_of_callbacks);
+   memcached_return_t
+     memcached_mget_execute_by_key (memcached_st *ptr,
+                                    const char *master_key,
+                                    size_t master_key_length,
+                                    const char * const *keys,
+                                    const size_t *key_length,
+                                    size_t number_of_keys,
+                                    memcached_execute_fn *callback,
+                                    void *context,
+                                    uint32_t number_of_callbacks);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_get() is used to fetch an individual value from the server. You
+must pass in a key and its length to fetch the object. You must supply
+three pointer variables which will give you the state of the returned
+object.  A uint32_t pointer to contain whatever flags you stored with the value,
+a size_t pointer which will be filled with size of of the object, and a
+memcached_return_t pointer to hold any error. The object will be returned
+upon success and NULL will be returned on failure. Any object returned by
+memcached_get() must be released by the caller application.
+
+memcached_mget() is used to select multiple keys at once. For multiple key
+operations it is always faster to use this function. This function always
+works asynchronously. memcached_fetch() is then used to retrieve any keys
+found. No error is given on keys that are not found. You must call either
+memcached_fetch() or memcached_fetch_result() after a successful call to
+memcached_mget(). You should continue to call these functions until they
+return NULL (aka no more values). If you need to quit in the middle of a
+memcached_get() call, execute a memcached_quit(). After you do this, you can
+issue new queries against the server.
+
+memcached_fetch() is used to fetch an individual value from the server.
+memcached_mget() must always be called before using this method.  You
+must pass in a key and its length to fetch the object. You must supply
+three pointer variables which will give you the state of the returned
+object.  A uint32_t pointer to contain whatever flags you stored with the value,
+a size_t pointer which will be filled with size of of the object, and a
+memcached_return_t pointer to hold any error. The object will be returned
+upon success and NULL will be returned on failure. MEMCACHD_END is returned
+by the \*error value when all objects that have been found are returned.
+The final value upon MEMCACHED_END is null. Values returned by
+memcached_fetch() musted be free'ed by the caller. memcached_fetch() will
+be DEPRECATED in the near future, memcached_fetch_result() should be used
+instead.
+
+memcached_fetch_result() is used to return a memcached_result_st(3) structure
+from a memcached server. The result object is forward compatible with changes
+to the server. For more information please refer to the memcached_result_st(3)
+help. This function will dynamically allocate a result structure for you
+if you do not pass one to the function.
+
+memcached_fetch_execute() is a callback function for result sets. Instead
+of returning the results to you for processing, it passes each of the
+result sets to the list of functions you provide. It passes to the function
+a memcached_st that can be cloned for use in the called function (it can not
+be used directly). It also passes a result set which does not need to be freed.
+Finally it passes a "context". This is just a pointer to a memory reference
+you supply the calling function. Currently only one value is being passed
+to each function call. In the future there will be an option to allow this
+to be an array.
+
+memcached_mget_execute() and memcached_mget_execute_by_key() is
+similar to memcached_mget(), but it may trigger the supplied callbacks
+with result sets while sending out the queries. If you try to perform
+a really large multiget with memcached_mget() you may encounter a
+deadlock in the OS kernel (we fail to write data to the socket because
+the input buffer is full). memcached_mget_execute() solves this
+problem by processing some of the results before continuing sending
+out requests. Please note that this function is only available in the
+binary protocol.
+
+memcached_get_by_key() and memcached_mget_by_key() behave in a similar nature
+as memcached_get() and memcached_mget(). The difference is that they take
+a master key that is used for determining which server an object was stored
+if key partitioning was used for storage.
+
+All of the above functions are not supported when the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ 
+has been set. Executing any of these functions with this behavior on will result in
+\ ``MEMCACHED_NOT_SUPPORTED``\  being returned or, for those functions which do not return
+a \ ``memcached_return_t``\ , the error function parameter will be set to
+\ ``MEMCACHED_NOT_SUPPORTED``\ .
+
+
+******
+RETURN
+******
+
+
+All objects returned must be freed by the calling application.
+memcached_get() and memcached_fetch() will return NULL on error. You must
+look at the value of error to determine what the actual error was.
+
+MEMCACHED_KEY_TOO_BIG is set to error whenever memcached_fetch() was used
+and the key was set larger then MEMCACHED_MAX_KEY, which was the largest
+key allowed for the original memcached ascii server.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_memory_allocators.pod b/docs/memcached_memory_allocators.pod
deleted file mode 100644 (file)
index 6b9ddf9..0000000
+++ /dev/null
@@ -1,99 +0,0 @@
-=head1 NAME
-
-memcached_set_memory_allocators, memcached_get_memory_allocators, memcached_set_memory_allocators_context - Manage memory allocator functions
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_return_t
-    memcached_set_memory_allocators (memcached_st *ptr,
-                                     memcached_malloc_fn mem_malloc,
-                                     memcached_free_fn mem_free,
-                                     memcached_realloc_fn mem_realloc,
-                                     memcached_calloc_fn mem_calloc,
-                                    void *context);
-
-  void
-    memcached_get_memory_allocators (memcached_st *ptr,
-                                     memcached_malloc_fn *mem_malloc,
-                                     memcached_free_fn *mem_free,
-                                     memcached_realloc_fn *mem_realloc,
-                                     memcached_calloc_fn *mem_calloc);
-
-  void * 
-    memcached_get_memory_allocators_context(const memcached_st *ptr);
-
-  void *
-    (*memcached_malloc_fn) (memcached_st *ptr, const size_t size,
-                           void *context);
-
-  void *
-    (*memcached_realloc_fn) (memcached_st *ptr, void *mem,
-                             const size_t size,
-                            void *context);
-
-  void
-    (*memcached_free_fn) (memcached_st *ptr, void *mem,
-                         void *context);
-
-  void *
-  (*memcached_calloc_fn) (memcached_st *ptr,
-                         size_t nelem,
-                          const size_t elsize,
-                         void *context);
-
-
-=head1 DESCRIPTION
-
-libmemcached(3) allows you to specify your own memory allocators optimized
-for your application.
-
-memcached_set_memory_allocators() is used to set the memory allocators used
-by the memcached instance specified by ptr. Please note that you cannot
-override only one of the memory allocators, you have to specify a complete
-new set if you want to override one of them. All of the memory allocation
-functions should behave as specified in the C99 standard. Specify NULL as
-all functions to reset them to the default values.
-
-memcached_get_memory_allocators() is used to get the currently used memory
-allocators by a mamcached handle.
-
-memcached_get_memory_allocators_context() returns the void * that was
-passed in during the call to memcached_set_memory_allocators().
-
-The first argument to the memory allocator functions is a pointer to a
-memcached structure, the is passed as const and you will need to clone
-it in order to make use of any operation which would modify it.
-
-=head1 NOTES
-
-In version 0.38 all functions were modified to have a context void pointer
-passed to them. This was so that customer allocators could have their
-own space for memory.
-
-=head1 RETURN
-
-memcached_set_memory_allocators() return MEMCACHED_SUCCESS upon success,
-and MEMCACHED_FAILURE if you don't pass a complete set of function pointers.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Trond Norbye, E<lt>trond.norbye@gmail.comE<gt>
-Brian Aker, E<lt>brian@tangent.orf<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_get_user_data(3) memcached_set_user_data(3)
-
-=cut
-
diff --git a/docs/memcached_memory_allocators.rst b/docs/memcached_memory_allocators.rst
new file mode 100644 (file)
index 0000000..83c96b6
--- /dev/null
@@ -0,0 +1,138 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_set_memory_allocators, memcached_get_memory_allocators, memcached_set_memory_allocators_context - Manage memory allocator functions
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_return_t
+     memcached_set_memory_allocators (memcached_st *ptr,
+                                      memcached_malloc_fn mem_malloc,
+                                      memcached_free_fn mem_free,
+                                      memcached_realloc_fn mem_realloc,
+                                      memcached_calloc_fn mem_calloc,
+                                    void *context);
+   void
+     memcached_get_memory_allocators (memcached_st *ptr,
+                                      memcached_malloc_fn *mem_malloc,
+                                      memcached_free_fn *mem_free,
+                                      memcached_realloc_fn *mem_realloc,
+                                      memcached_calloc_fn *mem_calloc);
+   void * 
+     memcached_get_memory_allocators_context(const memcached_st *ptr);
+   void *
+     (*memcached_malloc_fn) (memcached_st *ptr, const size_t size,
+                           void *context);
+   void *
+     (*memcached_realloc_fn) (memcached_st *ptr, void *mem,
+                              const size_t size,
+                            void *context);
+   void
+     (*memcached_free_fn) (memcached_st *ptr, void *mem,
+                         void *context);
+   void *
+   (*memcached_calloc_fn) (memcached_st *ptr,
+                         size_t nelem,
+                           const size_t elsize,
+                         void *context);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) allows you to specify your own memory allocators optimized
+for your application.
+
+memcached_set_memory_allocators() is used to set the memory allocators used
+by the memcached instance specified by ptr. Please note that you cannot
+override only one of the memory allocators, you have to specify a complete
+new set if you want to override one of them. All of the memory allocation
+functions should behave as specified in the C99 standard. Specify NULL as
+all functions to reset them to the default values.
+
+memcached_get_memory_allocators() is used to get the currently used memory
+allocators by a mamcached handle.
+
+memcached_get_memory_allocators_context() returns the void \* that was
+passed in during the call to memcached_set_memory_allocators().
+
+The first argument to the memory allocator functions is a pointer to a
+memcached structure, the is passed as const and you will need to clone
+it in order to make use of any operation which would modify it.
+
+
+*****
+NOTES
+*****
+
+
+In version 0.38 all functions were modified to have a context void pointer
+passed to them. This was so that customer allocators could have their
+own space for memory.
+
+
+******
+RETURN
+******
+
+
+memcached_set_memory_allocators() return MEMCACHED_SUCCESS upon success,
+and MEMCACHED_FAILURE if you don't pass a complete set of function pointers.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Trond Norbye, <trond.norbye@gmail.com>
+Brian Aker, <brian@tangent.orf<gt>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_get_user_data(3) memcached_set_user_data(3)
+
diff --git a/docs/memcached_pool.pod b/docs/memcached_pool.pod
deleted file mode 100644 (file)
index b974be6..0000000
+++ /dev/null
@@ -1,99 +0,0 @@
-=head1 NAME
-
-memcached_pool_create, memcached_pool_destroy, memcached_pool_push, memcached_pool_pop - Manage pools
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcachedutil, -lmemcachedutil)
-
-=head1 SYNOPSIS
-
-  #include <libmemcached/memcached_pool.h>
-
-  memcached_pool_st *
-    memcached_pool_create(memcached_st* mmc, int initial, int max);
-
-  memcached_st *
-    memcached_pool_destroy(memcached_pool_st* pool);
-
-  memcached_st *
-    memcached_pool_pop (memcached_pool_st* pool, bool block, memcached_return_t *rc);
-
-  memcached_return_t
-    memcached_pool_push(memcached_pool_st* pool, memcached_st *mmc);
-
-  memcached_st *memcached_create (memcached_st *ptr);
-
-  memcached_return_t
-    memcached_pool_behavior_set(memcached_pool_st *pool,
-                                memcached_behavior_t flag,
-                                uint64_t data)
-
-  memcached_return_t
-    memcached_pool_behavior_get(memcached_pool_st *pool,
-                                memcached_behavior_t flag,
-                                uint64_t *value)
-
-=head1 DESCRIPTION
-
-memcached_pool_create() is used to create a connection pool of objects you
-may use to remove the overhead of using memcached_clone for short
-lived C<memcached_st> objects. The mmc argument should be an
-initialised C<memcached_st> structure, and a successfull invocation of
-memcached_pool_create takes full ownership of the variable (until it
-is released by memcached_pool_destroy). The C<initial> argument
-specifies the initial size of the connection pool, and the C<max>
-argument specifies the maximum size the connection pool should grow
-to. Please note that the library will allocate a fixed size buffer
-scaled to the max size of the connection pool, so you should not pass
-MAXINT or some other large number here.
-
-memcached_pool_destroy() is used to destroy the connection pool
-created with memcached_pool_create() and release all allocated
-resources. It will return the pointer to the C<memcached_st> structure
-passed as an argument to memcached_pool_create(), and returns the
-ownership of the pointer to the caller.
-
-memcached_pool_pop() is used to grab a connection structure from the
-connection pool. The block argument specifies if the function should
-block and wait for a connection structure to be available if we try
-to exceed the maximum size.
-
-memcached_pool_push() is used to return a connection structure back to the pool.
-
-memcached_pool_behavior_set() and memcached_pool_behagior_get() is
-used to get/set behavior flags on all connections in the pool.
-
-
-=head1 RETURN
-
-memcached_pool_create() returns a pointer to the newly created
-memcached_pool_st structure. On an allocation failure, it returns
-NULL.
-
-memcached_pool_destroy() returns the pointer (and ownership) to the
-memcached_st structure used to create the pool. If connections are in
-use it returns NULL.
-
-memcached_pool_pop() returns a pointer to a memcached_st structure
-from the pool (or NULL if an allocation cannot be satisfied).
-
-memcached_pool_push() returns MEMCACHED_SUCCESS upon success.
-
-memcached_pool_behavior_get() and memcached_pool_behavior_get()
-returns MEMCACHED_SUCCESS upon success.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Trond Norbye, E<lt>trond.norbye@gmail.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_create(3) memcached_free(3) libmemcachedutil(3) memcached_behavior_get(3) memcached_behavior_set(3)
-
-=cut
diff --git a/docs/memcached_pool.rst b/docs/memcached_pool.rst
new file mode 100644 (file)
index 0000000..a3e5789
--- /dev/null
@@ -0,0 +1,135 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_pool_create, memcached_pool_destroy, memcached_pool_push, memcached_pool_pop - Manage pools
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcachedutil, -lmemcachedutil)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <libmemcached/memcached_pool.h>
+   memcached_pool_st *
+     memcached_pool_create(memcached_st* mmc, int initial, int max);
+   memcached_st *
+     memcached_pool_destroy(memcached_pool_st* pool);
+   memcached_st *
+     memcached_pool_pop (memcached_pool_st* pool, bool block, memcached_return_t *rc);
+   memcached_return_t
+     memcached_pool_push(memcached_pool_st* pool, memcached_st *mmc);
+   memcached_st *memcached_create (memcached_st *ptr);
+   memcached_return_t
+     memcached_pool_behavior_set(memcached_pool_st *pool,
+                                 memcached_behavior_t flag,
+                                 uint64_t data)
+   memcached_return_t
+     memcached_pool_behavior_get(memcached_pool_st *pool,
+                                 memcached_behavior_t flag,
+                                 uint64_t *value)
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_pool_create() is used to create a connection pool of objects you
+may use to remove the overhead of using memcached_clone for short
+lived \ ``memcached_st``\  objects. The mmc argument should be an
+initialised \ ``memcached_st``\  structure, and a successfull invocation of
+memcached_pool_create takes full ownership of the variable (until it
+is released by memcached_pool_destroy). The \ ``initial``\  argument
+specifies the initial size of the connection pool, and the \ ``max``\ 
+argument specifies the maximum size the connection pool should grow
+to. Please note that the library will allocate a fixed size buffer
+scaled to the max size of the connection pool, so you should not pass
+MAXINT or some other large number here.
+
+memcached_pool_destroy() is used to destroy the connection pool
+created with memcached_pool_create() and release all allocated
+resources. It will return the pointer to the \ ``memcached_st``\  structure
+passed as an argument to memcached_pool_create(), and returns the
+ownership of the pointer to the caller.
+
+memcached_pool_pop() is used to grab a connection structure from the
+connection pool. The block argument specifies if the function should
+block and wait for a connection structure to be available if we try
+to exceed the maximum size.
+
+memcached_pool_push() is used to return a connection structure back to the pool.
+
+memcached_pool_behavior_set() and memcached_pool_behagior_get() is
+used to get/set behavior flags on all connections in the pool.
+
+
+******
+RETURN
+******
+
+
+memcached_pool_create() returns a pointer to the newly created
+memcached_pool_st structure. On an allocation failure, it returns
+NULL.
+
+memcached_pool_destroy() returns the pointer (and ownership) to the
+memcached_st structure used to create the pool. If connections are in
+use it returns NULL.
+
+memcached_pool_pop() returns a pointer to a memcached_st structure
+from the pool (or NULL if an allocation cannot be satisfied).
+
+memcached_pool_push() returns MEMCACHED_SUCCESS upon success.
+
+memcached_pool_behavior_get() and memcached_pool_behavior_get()
+returns MEMCACHED_SUCCESS upon success.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Trond Norbye, <trond.norbye@gmail.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_create(3) memcached_free(3) libmemcachedutil(3) memcached_behavior_get(3) memcached_behavior_set(3)
+
diff --git a/docs/memcached_quit.pod b/docs/memcached_quit.pod
deleted file mode 100644 (file)
index 270dd46..0000000
+++ /dev/null
@@ -1,47 +0,0 @@
-=head1 NAME
-
-memcached_quit - Disconnect from all servers
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  void memcached_quit (memcached_st *ptr);
-
-=head1 DESCRIPTION
-
-memcached_quit() will disconnect you from all currently connected servers.
-It will also reset the state of the connection (ie, any memcached_fetch() you
-are in the middle of will be terminated). This function is called
-automatically when you call memcached_free() on the C<memcached_st> structure.
-
-You do not need to call this on your own. All operations to change server
-hashes and parameters will handle connections to the server for you. This
-function is provided mainly so that you can timeout your connections or
-reset connections during the middle of a memcached_fetch().
-
-=head1 RETURN
-
-A value of type C<memcached_return> is returned
-On success that value will be C<MEMCACHED_SUCCESS>.
-Use memcached_strerror() to translate this value to a printable string.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_quit.rst b/docs/memcached_quit.rst
new file mode 100644 (file)
index 0000000..cf5abdb
--- /dev/null
@@ -0,0 +1,83 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_quit - Disconnect from all servers
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   void memcached_quit (memcached_st *ptr);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_quit() will disconnect you from all currently connected servers.
+It will also reset the state of the connection (ie, any memcached_fetch() you
+are in the middle of will be terminated). This function is called
+automatically when you call memcached_free() on the \ ``memcached_st``\  structure.
+
+You do not need to call this on your own. All operations to change server
+hashes and parameters will handle connections to the server for you. This
+function is provided mainly so that you can timeout your connections or
+reset connections during the middle of a memcached_fetch().
+
+
+******
+RETURN
+******
+
+
+A value of type \ ``memcached_return``\  is returned
+On success that value will be \ ``MEMCACHED_SUCCESS``\ .
+Use memcached_strerror() to translate this value to a printable string.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_result_st.pod b/docs/memcached_result_st.pod
deleted file mode 100644 (file)
index 7fbc394..0000000
+++ /dev/null
@@ -1,115 +0,0 @@
-=head1 NAME
-
-memcached_result_create, memcached_result_free,
-memcached_result_key_value, memcached_result_key_length,
-memcached_result_value, memcached_result_length,
-memcached_result_flags, memcached_result_cas - Work with memcached_result_st
-
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_result_st *
-    memcached_result_create (memcached_st *ptr,
-                             memcached_result_st *result);
-
-  void memcached_result_free (memcached_result_st *result);
-
-  const char * memcached_result_key_value (memcached_result_st *result);
-
-  size_t memcached_result_key_length (const memcached_result_st *result);
-
-  const char *memcached_result_value (memcached_result_st *ptr);
-
-  size_t memcached_result_length (const memcached_result_st *ptr);
-
-  uint32_t memcached_result_flags (const memcached_result_st *result)
-
-  uint64_t memcached_result_cas (const memcached_result_st *result);
-
-  memcached_return_t
-    memcached_result_set_value (memcached_result_st *ptr,
-                                const char *value, size_t length)
-
-  void memcached_result_set_flags (memcached_result_st *ptr, uint32_t flags)
-
-  void memcached_result_set_expiration (memcached_result_st *ptr, time_t)
-
-=head1 DESCRIPTION
-
-libmemcached(3) can optionally return a memcached_result_st which acts as a
-result object. The result objects have added benefits over the character
-pointer returns in that they are forward compatible with new return items
-that future memcached servers may implement (the best current example of
-this is the CAS return item). The structures can also be reused which will
-save on calls to malloc(3). It is suggested that you use result objects over
-char * return functions.
-
-The structure of memcached_result_st has been encapsulated, you should not
-write code to directly access members of the structure.
-
-memcached_result_create() will either allocate memory for a
-memcached_result_st or will initialize a structure passed to it.
-
-memcached_result_free() will deallocate any memory attached to the
-structure. If the structure was also alloacted, it will deallocate it.
-
-memcached_result_key_value() returns the key value associated with the
-current result object.
-
-memcached_result_key_length() returns the key length associated with the
-current result object.
-
-memcached_result_value() returns the result value associated with the
-current result object.
-
-memcached_result_length() returns the result length associated with the
-current result object.
-
-memcached_result_flags() returns the flags associated with the
-current result object.
-
-memcached_result_cas() returns the cas associated with the
-current result object. This value will only be available if the server
-supports it.
-
-memcached_result_set_value() takes a byte array and a size and sets
-the result to this value. This function is used for trigger responses.
-
-void memcached_result_set_flags() takes a result structure and stores
-a new value for the flags field.
-
-void memcached_result_set_expiration(A) takes a result structure and stores
-a new value for the expiration field (this is only used by read through
-triggers).
-
-You may wish to avoid using memcached_result_create(3) with a
-stack based allocation. The most common issues related to ABI safety involve
-heap allocated structures.
-
-=head1 RETURN
-
-Varies, see particular functions. All structures must have
-memcached_result_free() called on them for cleanup purposes. Failure to
-do this will result in leaked memory.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_result_st.rst b/docs/memcached_result_st.rst
new file mode 100644 (file)
index 0000000..c33852d
--- /dev/null
@@ -0,0 +1,150 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_result_create, memcached_result_free,
+memcached_result_key_value, memcached_result_key_length,
+memcached_result_value, memcached_result_length,
+memcached_result_flags, memcached_result_cas - Work with memcached_result_st
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_result_st *
+     memcached_result_create (memcached_st *ptr,
+                              memcached_result_st *result);
+   void memcached_result_free (memcached_result_st *result);
+   const char * memcached_result_key_value (memcached_result_st *result);
+   size_t memcached_result_key_length (const memcached_result_st *result);
+   const char *memcached_result_value (memcached_result_st *ptr);
+   size_t memcached_result_length (const memcached_result_st *ptr);
+   uint32_t memcached_result_flags (const memcached_result_st *result)
+   uint64_t memcached_result_cas (const memcached_result_st *result);
+   memcached_return_t
+     memcached_result_set_value (memcached_result_st *ptr,
+                                 const char *value, size_t length)
+   void memcached_result_set_flags (memcached_result_st *ptr, uint32_t flags)
+   void memcached_result_set_expiration (memcached_result_st *ptr, time_t)
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) can optionally return a memcached_result_st which acts as a
+result object. The result objects have added benefits over the character
+pointer returns in that they are forward compatible with new return items
+that future memcached servers may implement (the best current example of
+this is the CAS return item). The structures can also be reused which will
+save on calls to malloc(3). It is suggested that you use result objects over
+char \* return functions.
+
+The structure of memcached_result_st has been encapsulated, you should not
+write code to directly access members of the structure.
+
+memcached_result_create() will either allocate memory for a
+memcached_result_st or will initialize a structure passed to it.
+
+memcached_result_free() will deallocate any memory attached to the
+structure. If the structure was also alloacted, it will deallocate it.
+
+memcached_result_key_value() returns the key value associated with the
+current result object.
+
+memcached_result_key_length() returns the key length associated with the
+current result object.
+
+memcached_result_value() returns the result value associated with the
+current result object.
+
+memcached_result_length() returns the result length associated with the
+current result object.
+
+memcached_result_flags() returns the flags associated with the
+current result object.
+
+memcached_result_cas() returns the cas associated with the
+current result object. This value will only be available if the server
+supports it.
+
+memcached_result_set_value() takes a byte array and a size and sets
+the result to this value. This function is used for trigger responses.
+
+void memcached_result_set_flags() takes a result structure and stores
+a new value for the flags field.
+
+void memcached_result_set_expiration(A) takes a result structure and stores
+a new value for the expiration field (this is only used by read through
+triggers).
+
+You may wish to avoid using memcached_result_create(3) with a
+stack based allocation. The most common issues related to ABI safety involve
+heap allocated structures.
+
+
+******
+RETURN
+******
+
+
+Varies, see particular functions. All structures must have
+memcached_result_free() called on them for cleanup purposes. Failure to
+do this will result in leaked memory.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_sasl.pod b/docs/memcached_sasl.pod
deleted file mode 100644 (file)
index 541cd48..0000000
+++ /dev/null
@@ -1,64 +0,0 @@
-=head1 NAME
-
-memcached_set_sasl_callbacks, memcached_get_sasl_callbacks,
-memcached_sasl_set_auth_data, memcached_destroy_sasl_auth_data - SASL support
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  void memcached_set_sasl_callbacks(memcached_st *ptr,
-                                    const sasl_callback_t *callbacks)
-
-  const sasl_callback_t *memcached_get_sasl_callbacks(memcached_st *ptr)
-
-  memcached_return memcached_set_sasl_auth_data(memcached_st *ptr,
-                                                const char *username,
-                                                const char *password)
-  memcached_return memcached_destroy_sasl_auth_data(memcached_st *ptr)
-
-
-=head1 DESCRIPTION
-
-libmemcached(3) allows you to plug in your own callbacks function used by
-libsasl to perform SASL authentication.
-
-Please note that SASL requires the memcached binary protocol, and you have
-to specify the callbacks before you connect to the server.
-
-memcached_set_sasl_auth_data() is a helper function for you defining
-the basic functionality for you, but it will store the username and password
-in memory. If you choose to use this method you have to call
-memcached_destroy_sasl_auth_data before calling memcached_free to avoid
-a memory leak. You should NOT call memcached_destroy_sasl_auth_data if you
-specify your own callback function with memcached_set_sasl_callbacks().
-
-You as a client user have to initialize libsasl by using sasl_client_init
-before enabling it in libmemcached, and you have to shut down libsasl by
-calling sasl_done() when you are done using SASL from libmemcached.
-
-
-=head1 RETURN
-
-memcached_get_sasl_callbacks() returns the callbacks currently used
-by this memcached handle.
-memcached_get_sasl_set_auth_data() returns MEMCACHED_SUCCESS upon success.
-
-=head1 HOME
-
-To find out more information please check:
-L<http://libmemcached.org/>
-
-=head1 AUTHOR
-
-Trond Norbye, E<lt>trond.norbye@gmail.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
diff --git a/docs/memcached_sasl.rst b/docs/memcached_sasl.rst
new file mode 100644 (file)
index 0000000..1994c75
--- /dev/null
@@ -0,0 +1,99 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_set_sasl_callbacks, memcached_get_sasl_callbacks,
+memcached_sasl_set_auth_data, memcached_destroy_sasl_auth_data - SASL support
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   void memcached_set_sasl_callbacks(memcached_st *ptr,
+                                     const sasl_callback_t *callbacks)
+   const sasl_callback_t *memcached_get_sasl_callbacks(memcached_st *ptr)
+   memcached_return memcached_set_sasl_auth_data(memcached_st *ptr,
+                                                 const char *username,
+                                                 const char *password)
+   memcached_return memcached_destroy_sasl_auth_data(memcached_st *ptr)
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) allows you to plug in your own callbacks function used by
+libsasl to perform SASL authentication.
+
+Please note that SASL requires the memcached binary protocol, and you have
+to specify the callbacks before you connect to the server.
+
+memcached_set_sasl_auth_data() is a helper function for you defining
+the basic functionality for you, but it will store the username and password
+in memory. If you choose to use this method you have to call
+memcached_destroy_sasl_auth_data before calling memcached_free to avoid
+a memory leak. You should NOT call memcached_destroy_sasl_auth_data if you
+specify your own callback function with memcached_set_sasl_callbacks().
+
+You as a client user have to initialize libsasl by using sasl_client_init
+before enabling it in libmemcached, and you have to shut down libsasl by
+calling sasl_done() when you are done using SASL from libmemcached.
+
+
+******
+RETURN
+******
+
+
+memcached_get_sasl_callbacks() returns the callbacks currently used
+by this memcached handle.
+memcached_get_sasl_set_auth_data() returns MEMCACHED_SUCCESS upon success.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`http://libmemcached.org/ <http://libmemcached.org/>`_
+
+
+******
+AUTHOR
+******
+
+
+Trond Norbye, <trond.norbye@gmail.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memcached_server_st.pod b/docs/memcached_server_st.pod
deleted file mode 100644 (file)
index d50334a..0000000
+++ /dev/null
@@ -1,84 +0,0 @@
-=head1 NAME
-
-memcached_server_list_free, memcached_server_list_append,
-memcached_server_list_count, memcached_servers_parse - Manage server list
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  const memcached_server_instance_st
-    memcached_server_list (memcached_st *ptr);
-
-  void memcached_server_list_free (memcached_server_list_st list);
-
-  memcached_server_list_st
-    memcached_server_list_append (memcached_server_list_st list, 
-                                  const char *hostname,
-                                  unsigned int port, 
-                                  memcached_return_t *error);
-
-  uint32_t memcached_server_list_count (memcached_server_list_st list);
-
-  memcached_server_list_st memcached_servers_parse (const char *server_strings);
-
-  const char *memcached_server_error (memcached_server_instance_st instance);
-
-  DEPRECATED
-  void memcached_server_error_reset (memcached_server_instance_st list);
-
-=head1 DESCRIPTION
-
-libmemcached(3) operates on a list of hosts which are stored in
-memcached_server_st structures. You should not modify these structures
-directly. Functions are provided to modify these structures (and more can be
-added, just ask!).
-
-memcached_server_list() is used to provide an array of all defined hosts.
-This was incorrectly documented as "requiring free()" up till version 0.39.
-
-memcached_server_list_free() deallocates all memory associated with the array
-of memcached_server_st that you passed to it. 
-
-memcached_server_list_append() adds a server to the end of a
-memcached_server_st array. On error null will be returned and the
-memcached_return_t pointer you passed into the function will be set with the
-appropriate error. If the value of port is zero, it is set to the default
-port of a memcached server.
-
-memcached_servers_parse() takes a string, the type that is used for the
-command line applications, and parse it to an array of memcached_server_st.
-The example is "localhost, foo:555, foo, bar". All hosts except foo:555 will
-be set to the default port, while that host will have a port of 555.
-
-memcached_server_error() can be used to look at the text of the last error 
-message sent by the server to to the client.
-
-Before version 0.39 theses functions used a memcache_server_st *. In 0.39
-memcached_server_st * was aliased to memcached_server_list_st. This was
-done for a style reason/to help clean up some concepts in the code. 
-
-
-=head1 RETURN
-
-Varies, see particular functions.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_server_st.rst b/docs/memcached_server_st.rst
new file mode 100644 (file)
index 0000000..b1c5450
--- /dev/null
@@ -0,0 +1,119 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_server_list_free, memcached_server_list_append,
+memcached_server_list_count, memcached_servers_parse - Manage server list
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   const memcached_server_instance_st
+     memcached_server_list (memcached_st *ptr);
+   void memcached_server_list_free (memcached_server_list_st list);
+   memcached_server_list_st
+     memcached_server_list_append (memcached_server_list_st list, 
+                                   const char *hostname,
+                                   unsigned int port, 
+                                   memcached_return_t *error);
+   uint32_t memcached_server_list_count (memcached_server_list_st list);
+   memcached_server_list_st memcached_servers_parse (const char *server_strings);
+   const char *memcached_server_error (memcached_server_instance_st instance);
+   DEPRECATED
+   void memcached_server_error_reset (memcached_server_instance_st list);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) operates on a list of hosts which are stored in
+memcached_server_st structures. You should not modify these structures
+directly. Functions are provided to modify these structures (and more can be
+added, just ask!).
+
+memcached_server_list() is used to provide an array of all defined hosts.
+This was incorrectly documented as "requiring free()" up till version 0.39.
+
+memcached_server_list_free() deallocates all memory associated with the array
+of memcached_server_st that you passed to it.
+
+memcached_server_list_append() adds a server to the end of a
+memcached_server_st array. On error null will be returned and the
+memcached_return_t pointer you passed into the function will be set with the
+appropriate error. If the value of port is zero, it is set to the default
+port of a memcached server.
+
+memcached_servers_parse() takes a string, the type that is used for the
+command line applications, and parse it to an array of memcached_server_st.
+The example is "localhost, foo:555, foo, bar". All hosts except foo:555 will
+be set to the default port, while that host will have a port of 555.
+
+memcached_server_error() can be used to look at the text of the last error 
+message sent by the server to to the client.
+
+Before version 0.39 theses functions used a memcache_server_st \*. In 0.39
+memcached_server_st \* was aliased to memcached_server_list_st. This was
+done for a style reason/to help clean up some concepts in the code.
+
+
+******
+RETURN
+******
+
+
+Varies, see particular functions.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_servers.pod b/docs/memcached_servers.pod
deleted file mode 100644 (file)
index f2d66c9..0000000
+++ /dev/null
@@ -1,118 +0,0 @@
-=head1 NAME
-
-memcached_server_count, memcached_server_list, memcached_server_add, memcached_server_push, memcached_server_get_last_disconnect, memcached_server_cursor - Manage server list
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  uint32_t memcached_server_count (memcached_st *ptr);
-
-  memcached_return_t
-    memcached_server_add (memcached_st *ptr,
-                          const char *hostname,
-                          in_port_t port);
-
-  memcached_return_t
-    memcached_server_add_udp (memcached_st *ptr,
-                             const char *hostname,
-                             in_port_t port);
-
-  memcached_return_t
-    memcached_server_add_unix_socket (memcached_st *ptr,
-                                      const char *socket);
-
-  memcached_return_t
-    memcached_server_push (memcached_st *ptr,
-                           const memcached_server_st *list);
-
-  memcached_server_instance_st
-    memcached_server_by_key (const memcached_st *ptr,
-                             const char *key,
-                            size_t key_length,
-                             memcached_return_t *error);
-
-  memcached_server_instance_st
-    memcached_server_get_last_disconnect (const memcached_st *ptr)
-
-  memcached_return_t
-    memcached_server_cursor(const memcached_st *ptr,
-                           const memcached_server_fn *callback,
-                           void *context,
-                           uint32_t number_of_callbacks);
-
-
-=head1 DESCRIPTION
-
-libmemcached(3) performs operations on a list of hosts. The order of these
-hosts determine routing to keys. Functions are provided to add keys to
-memcached_st structures. To manipulate lists of servers see
-memcached_server_st(3).
-
-memcached_server_count() provides you a count of the current number of
-servers being used by a C<memcached_st> structure.
-
-memcached_server_add() pushes a single TCP server into the C<memcached_st>
-structure. This server will be placed at the end. Duplicate servers are
-allowed, so duplication is not checked. Executing this function with the
-C<MEMCACHED_BEHAVIOR_USE_UDP> behavior set will result in a
-C<MEMCACHED_INVALID_HOST_PROTOCOL>.
-
-memcached_server_add_udp() pushes a single UDP server into the C<memcached_st>
-structure. This server will be placed at the end. Duplicate servers are
-allowed, so duplication is not checked. Executing this function with out
-setting the C<MEMCACHED_BEHAVIOR_USE_UDP> behavior will result in a
-C<MEMCACHED_INVALID_HOST_PROTOCOL>.
-
-memcached_server_add_unix_socket() pushes a single UNIX socket into the
-C<memcached_st> structure. This UNIX socket will be placed at the end.
-Duplicate servers are allowed, so duplication is not checked. The length
-of the filename must be one character less then MEMCACHED_MAX_HOST_LENGTH.
-
-memcached_server_push() pushes an array of C<memcached_server_st> into
-the C<memcached_st> structure. These servers will be placed at the
-end. Duplicate servers are allowed, so duplication is not checked. A
-copy is made of structure so the list provided (and any operations on
-the list) are not saved.
-
-memcached_server_by_key() allows you to provide a key and retrieve the
-server which would be used for assignment. This structure is cloned
-from its original structure and must be freed. If NULL is returned you
-should consult *error. The returning structure should be freed with
-memcached_server_free().
-
-memcached_server_get_last_disconnect() returns a pointer to the last server
-for which there was a connection problem. It does not mean this particular
-server is currently dead but if the library is reporting a server is,
-the returned server is a very good candidate.
-
-memcached_server_cursor() takes a memcached_st and loops through the 
-list of hosts currently in the cursor calling the list of callback 
-functions provided. You can optionally pass in a value via 
-context which will be provided to each callback function. An error
-return from any callback will terminate the loop. memcached_server_cursor()
-is passed the original caller memcached_st in its current state. 
-
-=head1 RETURN
-
-Varies, see particular functions.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_servers.rst b/docs/memcached_servers.rst
new file mode 100644 (file)
index 0000000..2d58d9c
--- /dev/null
@@ -0,0 +1,153 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_server_count, memcached_server_list, memcached_server_add, memcached_server_push, memcached_server_get_last_disconnect, memcached_server_cursor - Manage server list
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   uint32_t memcached_server_count (memcached_st *ptr);
+   memcached_return_t
+     memcached_server_add (memcached_st *ptr,
+                           const char *hostname,
+                           in_port_t port);
+   memcached_return_t
+     memcached_server_add_udp (memcached_st *ptr,
+                             const char *hostname,
+                             in_port_t port);
+   memcached_return_t
+     memcached_server_add_unix_socket (memcached_st *ptr,
+                                       const char *socket);
+   memcached_return_t
+     memcached_server_push (memcached_st *ptr,
+                            const memcached_server_st *list);
+   memcached_server_instance_st
+     memcached_server_by_key (const memcached_st *ptr,
+                              const char *key,
+                            size_t key_length,
+                              memcached_return_t *error);
+   memcached_server_instance_st
+     memcached_server_get_last_disconnect (const memcached_st *ptr)
+   memcached_return_t
+     memcached_server_cursor(const memcached_st *ptr,
+                           const memcached_server_fn *callback,
+                           void *context,
+                           uint32_t number_of_callbacks);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) performs operations on a list of hosts. The order of these
+hosts determine routing to keys. Functions are provided to add keys to
+memcached_st structures. To manipulate lists of servers see
+memcached_server_st(3).
+
+memcached_server_count() provides you a count of the current number of
+servers being used by a \ ``memcached_st``\  structure.
+
+memcached_server_add() pushes a single TCP server into the \ ``memcached_st``\ 
+structure. This server will be placed at the end. Duplicate servers are
+allowed, so duplication is not checked. Executing this function with the
+\ ``MEMCACHED_BEHAVIOR_USE_UDP``\  behavior set will result in a
+\ ``MEMCACHED_INVALID_HOST_PROTOCOL``\ .
+
+memcached_server_add_udp() pushes a single UDP server into the \ ``memcached_st``\ 
+structure. This server will be placed at the end. Duplicate servers are
+allowed, so duplication is not checked. Executing this function with out
+setting the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\  behavior will result in a
+\ ``MEMCACHED_INVALID_HOST_PROTOCOL``\ .
+
+memcached_server_add_unix_socket() pushes a single UNIX socket into the
+\ ``memcached_st``\  structure. This UNIX socket will be placed at the end.
+Duplicate servers are allowed, so duplication is not checked. The length
+of the filename must be one character less then MEMCACHED_MAX_HOST_LENGTH.
+
+memcached_server_push() pushes an array of \ ``memcached_server_st``\  into
+the \ ``memcached_st``\  structure. These servers will be placed at the
+end. Duplicate servers are allowed, so duplication is not checked. A
+copy is made of structure so the list provided (and any operations on
+the list) are not saved.
+
+memcached_server_by_key() allows you to provide a key and retrieve the
+server which would be used for assignment. This structure is cloned
+from its original structure and must be freed. If NULL is returned you
+should consult \*error. The returning structure should be freed with
+memcached_server_free().
+
+memcached_server_get_last_disconnect() returns a pointer to the last server
+for which there was a connection problem. It does not mean this particular
+server is currently dead but if the library is reporting a server is,
+the returned server is a very good candidate.
+
+memcached_server_cursor() takes a memcached_st and loops through the 
+list of hosts currently in the cursor calling the list of callback 
+functions provided. You can optionally pass in a value via 
+context which will be provided to each callback function. An error
+return from any callback will terminate the loop. memcached_server_cursor()
+is passed the original caller memcached_st in its current state.
+
+
+******
+RETURN
+******
+
+
+Varies, see particular functions.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_set.pod b/docs/memcached_set.pod
deleted file mode 100644 (file)
index 13330dc..0000000
+++ /dev/null
@@ -1,187 +0,0 @@
-=head1 NAME
-
-memcached_set, memcached_add, memcached_replace - Store value on server
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_return_t
-    memcached_set (memcached_st *ptr,
-                   const char *key, size_t key_length, 
-                   const char *value, size_t value_length, 
-                   time_t expiration,
-                   uint32_t flags);
-
-  memcached_return_t
-    memcached_add (memcached_st *ptr,
-                   const char *key, size_t key_length,
-                   const char *value, size_t value_length, 
-                   time_t expiration,
-                   uint32_t flags);
-
-  memcached_return_t
-    memcached_replace (memcached_st *ptr,
-                       const char *key, size_t key_length,
-                       const char *value, size_t value_length, 
-                       time_t expiration,
-                       uint32_t flags);
-
-  memcached_return_t 
-    memcached_prepend(memcached_st *ptr, 
-                      const char *key, size_t key_length,
-                      const char *value, size_t value_length, 
-                      time_t expiration,
-                      uint32_t flags)
-
-  memcached_return_t 
-    memcached_append(memcached_st *ptr, 
-                     const char *key, size_t key_length,
-                      const char *value, size_t value_length, 
-                      time_t expiration,
-                      uint32_t flags)
-  memcached_return_t 
-    memcached_cas(memcached_st *ptr, 
-                  const char *key, size_t key_length,
-                  const char *value, size_t value_length, 
-                  time_t expiration,
-                  uint32_t flags,
-                  uint64_t cas);
-
-  memcached_return_t 
-    memcached_set_by_key(memcached_st *ptr, 
-                         const char *master_key, size_t master_key_length, 
-                         const char *key, size_t key_length, 
-                         const char *value, size_t value_length, 
-                         time_t expiration,
-                         uint32_t flags);
-
-  memcached_return_t 
-    memcached_add_by_key(memcached_st *ptr, 
-                         const char *master_key, size_t master_key_length,
-                         const char *key, size_t key_length,
-                         const char *value, size_t value_length, 
-                         time_t expiration,
-                         uint32_t flags);
-
-  memcached_return_t 
-    memcached_replace_by_key(memcached_st *ptr, 
-                             const char *master_key, size_t master_key_length,
-                             const char *key, size_t key_length,
-                             const char *value, size_t value_length, 
-                             time_t expiration,
-                             uint32_t flags);
-
-  memcached_return_t 
-    memcached_prepend_by_key(memcached_st *ptr, 
-                             const char *master_key, size_t master_key_length,
-                             const char *key, size_t key_length,
-                             const char *value, size_t value_length, 
-                             time_t expiration,
-                             uint32_t flags);
-
-  memcached_return_t 
-    memcached_append_by_key(memcached_st *ptr, 
-                            const char *master_key, size_t master_key_length,
-                            const char *key, size_t key_length,
-                            const char *value, size_t value_length, 
-                            time_t expiration,
-                            uint32_t flags);
-
-  memcached_return_t 
-    memcached_cas_by_key(memcached_st *ptr, 
-                         const char *master_key, size_t master_key_length,
-                         const char *key, size_t key_length,
-                         const char *value, size_t value_length, 
-                         time_t expiration,
-                         uint32_t flags,
-                         uint64_t cas);
-
-=head1 DESCRIPTION
-
-memcached_set(), memcached_add(), and memcached_replace() are all used to
-store information on the server. All methods take a key, and its length to
-store the object. Keys are currently limited to 250 characters by the
-memcached(1) server. You must also supply a value and a length. Optionally you
-may support an expiration time for the object and a 16 byte value (it is
-meant to be used as a bitmap).
-
-memcached_set() will write an object to the server. If an object already
-exists it will overwrite what is in the server. If the object does not exist
-it will be written. If you are using the non-blocking mode this function
-will always return true unless a network error occurs. 
-
-memcached_replace() replaces an object on the server. If the object is not
-found on the server an error occurs.
-
-memcached_add() adds an object to the server. If the object is found on the
-server an error occurs, otherwise the value is stored.
-
-memcached_prepend() places a segment of data before the last piece of data 
-stored. Currently expiration and key are not used in the server.
-
-memcached_append() places a segment of data at the end of the last piece of 
-data stored. Currently expiration and key are not used in the server.
-
-memcached_cas() overwrites data in the server as long as the "cas" value is 
-still the same in the server. You can get the cas value of a result by 
-calling memcached_result_cas() on a memcached_result_st(3) structure. At the point 
-that this note was written cas is still buggy in memached. Turning on support
-for it in libmemcached(3) is optional. Please see memcached_set() for 
-information on how to do this.
-
-memcached_set_by_key(), memcached_add_by_key(), memcached_replace_by_key(), 
-memcached_prepend_by_key(), memcached_append_by_key_by_key(), 
-memcached_cas_by_key() methods all behave in a similar method as the non key 
-methods. The difference is that they use their master_key parameter to map
-objects to particular servers.
-
-If you are looking for performance, memcached_set() with non-blocking IO is 
-the fastest way to store data on the server.
-
-All of the above functions are supported with the C<MEMCACHED_BEHAVIOR_USE_UDP>
-behavior enabled. But when using these operations with this behavior on, there 
-are limits to the size of the payload being sent to the server.  The reason for 
-these limits is that the Memcahed Server does not allow multi-datagram requests
-and the current server implementation sets a datagram size to 1400 bytes. Due 
-to protocol overhead, the actual limit of the user supplied data is less than 
-1400 bytes and depends on the protocol in use as well as the operation being 
-executed. When running with the binary protocol, C< MEMCACHED_BEHAVIOR_BINARY_PROTOCOL>, 
-the size of the key,value, flags and expiry combined may not exceed 1368 bytes. 
-When running with the ASCII protocol, the exact limit fluctuates depending on 
-which function is being executed and whether the function is a cas operation 
-or not. For non-cas ASCII set operations, there are at least 1335 bytes available 
-to split among the key, key_prefix, and value; for cas ASCII operations there are 
-at least 1318 bytes available to split among the key, key_prefix and value. If the
-total size of the command, including overhead, exceeds 1400 bytes, a C<MEMCACHED_WRITE_FAILURE>
-will be returned.
-
-
-=head1 RETURN
-
-All methods return a value of type C<memcached_return_t>.
-On success the value will be C<MEMCACHED_SUCCESS>.
-Use memcached_strerror() to translate this value to a printable string.
-
-For memcached_replace() and memcached_add(), C<MEMCACHED_NOTSTORED> is a
-legitmate error in the case of a collision.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_set.rst b/docs/memcached_set.rst
new file mode 100644 (file)
index 0000000..b09d863
--- /dev/null
@@ -0,0 +1,222 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_set, memcached_add, memcached_replace - Store value on server
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_return_t
+     memcached_set (memcached_st *ptr,
+                    const char *key, size_t key_length, 
+                    const char *value, size_t value_length, 
+                    time_t expiration,
+                    uint32_t flags);
+   memcached_return_t
+     memcached_add (memcached_st *ptr,
+                    const char *key, size_t key_length,
+                    const char *value, size_t value_length, 
+                    time_t expiration,
+                    uint32_t flags);
+   memcached_return_t
+     memcached_replace (memcached_st *ptr,
+                        const char *key, size_t key_length,
+                        const char *value, size_t value_length, 
+                        time_t expiration,
+                        uint32_t flags);
+   memcached_return_t 
+     memcached_prepend(memcached_st *ptr, 
+                       const char *key, size_t key_length,
+                       const char *value, size_t value_length, 
+                       time_t expiration,
+                       uint32_t flags)
+   memcached_return_t 
+     memcached_append(memcached_st *ptr, 
+                      const char *key, size_t key_length,
+                       const char *value, size_t value_length, 
+                       time_t expiration,
+                       uint32_t flags)
+   memcached_return_t 
+     memcached_cas(memcached_st *ptr, 
+                   const char *key, size_t key_length,
+                   const char *value, size_t value_length, 
+                   time_t expiration,
+                   uint32_t flags,
+                   uint64_t cas);
+   memcached_return_t 
+     memcached_set_by_key(memcached_st *ptr, 
+                          const char *master_key, size_t master_key_length, 
+                          const char *key, size_t key_length, 
+                          const char *value, size_t value_length, 
+                          time_t expiration,
+                          uint32_t flags);
+   memcached_return_t 
+     memcached_add_by_key(memcached_st *ptr, 
+                          const char *master_key, size_t master_key_length,
+                          const char *key, size_t key_length,
+                          const char *value, size_t value_length, 
+                          time_t expiration,
+                          uint32_t flags);
+   memcached_return_t 
+     memcached_replace_by_key(memcached_st *ptr, 
+                              const char *master_key, size_t master_key_length,
+                              const char *key, size_t key_length,
+                              const char *value, size_t value_length, 
+                              time_t expiration,
+                              uint32_t flags);
+   memcached_return_t 
+     memcached_prepend_by_key(memcached_st *ptr, 
+                              const char *master_key, size_t master_key_length,
+                              const char *key, size_t key_length,
+                              const char *value, size_t value_length, 
+                              time_t expiration,
+                              uint32_t flags);
+   memcached_return_t 
+     memcached_append_by_key(memcached_st *ptr, 
+                             const char *master_key, size_t master_key_length,
+                             const char *key, size_t key_length,
+                             const char *value, size_t value_length, 
+                             time_t expiration,
+                             uint32_t flags);
+   memcached_return_t 
+     memcached_cas_by_key(memcached_st *ptr, 
+                          const char *master_key, size_t master_key_length,
+                          const char *key, size_t key_length,
+                          const char *value, size_t value_length, 
+                          time_t expiration,
+                          uint32_t flags,
+                          uint64_t cas);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_set(), memcached_add(), and memcached_replace() are all used to
+store information on the server. All methods take a key, and its length to
+store the object. Keys are currently limited to 250 characters by the
+memcached(1) server. You must also supply a value and a length. Optionally you
+may support an expiration time for the object and a 16 byte value (it is
+meant to be used as a bitmap).
+
+memcached_set() will write an object to the server. If an object already
+exists it will overwrite what is in the server. If the object does not exist
+it will be written. If you are using the non-blocking mode this function
+will always return true unless a network error occurs.
+
+memcached_replace() replaces an object on the server. If the object is not
+found on the server an error occurs.
+
+memcached_add() adds an object to the server. If the object is found on the
+server an error occurs, otherwise the value is stored.
+
+memcached_prepend() places a segment of data before the last piece of data 
+stored. Currently expiration and key are not used in the server.
+
+memcached_append() places a segment of data at the end of the last piece of 
+data stored. Currently expiration and key are not used in the server.
+
+memcached_cas() overwrites data in the server as long as the "cas" value is 
+still the same in the server. You can get the cas value of a result by 
+calling memcached_result_cas() on a memcached_result_st(3) structure. At the point 
+that this note was written cas is still buggy in memached. Turning on support
+for it in libmemcached(3) is optional. Please see memcached_set() for 
+information on how to do this.
+
+memcached_set_by_key(), memcached_add_by_key(), memcached_replace_by_key(), 
+memcached_prepend_by_key(), memcached_append_by_key_by_key(), 
+memcached_cas_by_key() methods all behave in a similar method as the non key 
+methods. The difference is that they use their master_key parameter to map
+objects to particular servers.
+
+If you are looking for performance, memcached_set() with non-blocking IO is 
+the fastest way to store data on the server.
+
+All of the above functions are supported with the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ 
+behavior enabled. But when using these operations with this behavior on, there 
+are limits to the size of the payload being sent to the server.  The reason for 
+these limits is that the Memcahed Server does not allow multi-datagram requests
+and the current server implementation sets a datagram size to 1400 bytes. Due 
+to protocol overhead, the actual limit of the user supplied data is less than 
+1400 bytes and depends on the protocol in use as well as the operation being 
+executed. When running with the binary protocol, \ `` MEMCACHED_BEHAVIOR_BINARY_PROTOCOL``\ , 
+the size of the key,value, flags and expiry combined may not exceed 1368 bytes. 
+When running with the ASCII protocol, the exact limit fluctuates depending on 
+which function is being executed and whether the function is a cas operation 
+or not. For non-cas ASCII set operations, there are at least 1335 bytes available 
+to split among the key, key_prefix, and value; for cas ASCII operations there are 
+at least 1318 bytes available to split among the key, key_prefix and value. If the
+total size of the command, including overhead, exceeds 1400 bytes, a \ ``MEMCACHED_WRITE_FAILURE``\ 
+will be returned.
+
+
+******
+RETURN
+******
+
+
+All methods return a value of type \ ``memcached_return_t``\ .
+On success the value will be \ ``MEMCACHED_SUCCESS``\ .
+Use memcached_strerror() to translate this value to a printable string.
+
+For memcached_replace() and memcached_add(), \ ``MEMCACHED_NOTSTORED``\  is a
+legitmate error in the case of a collision.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_stats.pod b/docs/memcached_stats.pod
deleted file mode 100644 (file)
index 3b198d9..0000000
+++ /dev/null
@@ -1,96 +0,0 @@
-=head1 NAME
-
-memcached_stat, memcached_stat_servername, memcached_stat_get_value, memcached_stat_get_keys - Get memcached statistics
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_stat_st *memcached_stat (memcached_st *ptr,
-                                     char *args,
-                                     memcached_return_t *error);
-
-  memcached_return_t memcached_stat_servername (memcached_stat_st *stat,
-                                                char *args, 
-                                                const char *hostname,
-                                                unsigned int port);
-
-  char *
-    memcached_stat_get_value (memcached_st *ptr,
-                              memcached_stat_st *stat, 
-                              const char *key,
-                              memcached_return_t *error);
-
-  char ** 
-    memcached_stat_get_keys (memcached_st *ptr,
-                             memcached_stat_st *stat, 
-                             memcached_return_t *error);
-
-  memcached_return_t
-    memcached_stat_execute (memcached_st *memc,
-                            const char *args,
-                            memcached_stat_fn func,
-                            void *context);
-
-=head1 DESCRIPTION
-
-libmemcached(3) has the ability to query a memcached server (or collection
-of servers) for their current state. Queries to find state return a
-C<memcached_stat_st> structure. You are responsible for freeing this structure.
-While it is possible to access the structure directly it is not advisable.
-<memcached_stat_get_value() has been provided to query the structure.
-
-memcached_stat_execute() uses the servers found in C<memcached_stat_st> and 
-executes a "stat" command on each server. args is an optional argument that 
-can be passed in to modify the behavior of "stats". You will need to supply
-a callback function that will be supplied each pair of values returned by
-the memcached server.
-
-memcached_stat() fetches an array of C<memcached_stat_st> structures containing
-the state of all available memcached servers. The return value must be freed
-by the calling application. If called with the C<MEMCACHED_BEHAVIOR_USE_UDP>
-behavior set, a NULL value is returned and the error parameter is set to 
-C<MEMCACHED_NOT_SUPPORTED>.
-
-memcached_stat_servername() can be used standalone without a C<memcached_st> to
-obtain the state of a particular server.  "args" is used to define a
-particular state object (a list of these are not provided for by either
-the memcached_stat_get_keys() call nor are they defined in the memcached
-protocol). You must specify the hostname and port of the server you want to
-obtain information on.
-
-memcached_stat_get_value() returns the value of a particular state key. You
-specify the key you wish to obtain.  The key must be null terminated.
-
-memcached_stat_get_keys() returns a list of keys that the server has state
-objects on. You are responsible for freeing this list.
-
-A command line tool, memstat(1), is provided so that you do not have to write
-an application to do this.
-
-=head1 RETURN
-
-Varies, see particular functions.
-
-Any method returning a C<memcached_stat_st> expects you to free the
-memory allocated for it.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_stats.rst b/docs/memcached_stats.rst
new file mode 100644 (file)
index 0000000..f1f8970
--- /dev/null
@@ -0,0 +1,132 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_stat, memcached_stat_servername, memcached_stat_get_value, memcached_stat_get_keys - Get memcached statistics
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_stat_st *memcached_stat (memcached_st *ptr,
+                                      char *args,
+                                      memcached_return_t *error);
+   memcached_return_t memcached_stat_servername (memcached_stat_st *stat,
+                                                 char *args, 
+                                                 const char *hostname,
+                                                 unsigned int port);
+   char *
+     memcached_stat_get_value (memcached_st *ptr,
+                               memcached_stat_st *stat, 
+                               const char *key,
+                               memcached_return_t *error);
+   char ** 
+     memcached_stat_get_keys (memcached_st *ptr,
+                              memcached_stat_st *stat, 
+                              memcached_return_t *error);
+   memcached_return_t
+     memcached_stat_execute (memcached_st *memc,
+                             const char *args,
+                             memcached_stat_fn func,
+                             void *context);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) has the ability to query a memcached server (or collection
+of servers) for their current state. Queries to find state return a
+\ ``memcached_stat_st``\  structure. You are responsible for freeing this structure.
+While it is possible to access the structure directly it is not advisable.
+<memcached_stat_get_value() has been provided to query the structure.
+
+memcached_stat_execute() uses the servers found in \ ``memcached_stat_st``\  and 
+executes a "stat" command on each server. args is an optional argument that 
+can be passed in to modify the behavior of "stats". You will need to supply
+a callback function that will be supplied each pair of values returned by
+the memcached server.
+
+memcached_stat() fetches an array of \ ``memcached_stat_st``\  structures containing
+the state of all available memcached servers. The return value must be freed
+by the calling application. If called with the \ ``MEMCACHED_BEHAVIOR_USE_UDP``\ 
+behavior set, a NULL value is returned and the error parameter is set to 
+\ ``MEMCACHED_NOT_SUPPORTED``\ .
+
+memcached_stat_servername() can be used standalone without a \ ``memcached_st``\  to
+obtain the state of a particular server.  "args" is used to define a
+particular state object (a list of these are not provided for by either
+the memcached_stat_get_keys() call nor are they defined in the memcached
+protocol). You must specify the hostname and port of the server you want to
+obtain information on.
+
+memcached_stat_get_value() returns the value of a particular state key. You
+specify the key you wish to obtain.  The key must be null terminated.
+
+memcached_stat_get_keys() returns a list of keys that the server has state
+objects on. You are responsible for freeing this list.
+
+A command line tool, memstat(1), is provided so that you do not have to write
+an application to do this.
+
+
+******
+RETURN
+******
+
+
+Varies, see particular functions.
+
+Any method returning a \ ``memcached_stat_st``\  expects you to free the
+memory allocated for it.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_strerror.pod b/docs/memcached_strerror.pod
deleted file mode 100644 (file)
index 07801d8..0000000
+++ /dev/null
@@ -1,47 +0,0 @@
-=head1 NAME
-
-memcached_strerror - Get error string
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  const char *
-    memcached_strerror (memcached_st *ptr,
-                        memcached_return_t rc);
-
-=head1 DESCRIPTION
-
-memcached_strerror() takes a C<memcached_return_t> value and returns a string
-describing the error.
-
-This string must not be modified by the application.
-
-C<memcached_return_t> values are returned from nearly all libmemcached(3) functions.
-
-C<memcached_return_t> values are of an enum type so that you can set up responses
-with switch/case and know that you are capturing all possible return values.
-
-=head1 RETURN
-
-memcached_strerror() returns a string describing a C<memcached_return_t> value.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memcached_strerror.rst b/docs/memcached_strerror.rst
new file mode 100644 (file)
index 0000000..9ae6382
--- /dev/null
@@ -0,0 +1,83 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_strerror - Get error string
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   const char *
+     memcached_strerror (memcached_st *ptr,
+                         memcached_return_t rc);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_strerror() takes a \ ``memcached_return_t``\  value and returns a string
+describing the error.
+
+This string must not be modified by the application.
+
+\ ``memcached_return_t``\  values are returned from nearly all libmemcached(3) functions.
+
+\ ``memcached_return_t``\  values are of an enum type so that you can set up responses
+with switch/case and know that you are capturing all possible return values.
+
+
+******
+RETURN
+******
+
+
+memcached_strerror() returns a string describing a \ ``memcached_return_t``\  value.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memcached_user_data.pod b/docs/memcached_user_data.pod
deleted file mode 100644 (file)
index fc339df..0000000
+++ /dev/null
@@ -1,50 +0,0 @@
-=head1 NAME
-
-memcached_set_user_data, memcached_get_user_data - Manage user specific data
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  void *memcached_get_user_data (memcached_st *ptr);
-
-  void *memcached_set_user_data (memcached_st *ptr, void *data);
-
-=head1 DESCRIPTION
-
-libmemcached(3) allows you to store a pointer to a user specific data inside
-the memcached_st structure. 
-
-memcached_set_user_data() is used to set the user specific data in the
-memcached_st structure.
-
-memcached_get_user_data() is used to retrieve the user specific data in
-the memcached_st structure.
-
-=head1 RETURN
-
-memcached_set_user_data() returns the previous value of the user specific 
-data.
-
-memcached_get_user_data() returns the current value uf the user specific
-data.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Trond Norbye, E<lt>trond.norbye@gmail.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memcached_user_data.rst b/docs/memcached_user_data.rst
new file mode 100644 (file)
index 0000000..5f555f3
--- /dev/null
@@ -0,0 +1,86 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_set_user_data, memcached_get_user_data - Manage user specific data
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   void *memcached_get_user_data (memcached_st *ptr);
+   void *memcached_set_user_data (memcached_st *ptr, void *data);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+libmemcached(3) allows you to store a pointer to a user specific data inside
+the memcached_st structure.
+
+memcached_set_user_data() is used to set the user specific data in the
+memcached_st structure.
+
+memcached_get_user_data() is used to retrieve the user specific data in
+the memcached_st structure.
+
+
+******
+RETURN
+******
+
+
+memcached_set_user_data() returns the previous value of the user specific 
+data.
+
+memcached_get_user_data() returns the current value uf the user specific
+data.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Trond Norbye, <trond.norbye@gmail.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memcached_verbosity.pod b/docs/memcached_verbosity.pod
deleted file mode 100644 (file)
index 6cdac91..0000000
+++ /dev/null
@@ -1,42 +0,0 @@
-=head1 NAME
-
-memcached_verbosity - Modifiy verbosity of servers
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  memcached_return_t 
-    memcached_verbosity (memcached_st *ptr,
-                         unsigned int verbosity);
-
-=head1 DESCRIPTION
-
-memcached_verbosity() modifies the "verbosity" of the
-memcached(1) servers referenced in the C<memcached_st> parameter.
-
-=head1 RETURN
-
-A value of type C<memcached_return_t> is returned
-On success that value will be C<MEMCACHED_SUCCESS>.
-Use memcached_strerror() to translate this value to a printable string.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_verbosity.rst b/docs/memcached_verbosity.rst
new file mode 100644 (file)
index 0000000..4ec50e3
--- /dev/null
@@ -0,0 +1,78 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_verbosity - Modifiy verbosity of servers
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   memcached_return_t 
+     memcached_verbosity (memcached_st *ptr,
+                          unsigned int verbosity);
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_verbosity() modifies the "verbosity" of the
+memcached(1) servers referenced in the \ ``memcached_st``\  parameter.
+
+
+******
+RETURN
+******
+
+
+A value of type \ ``memcached_return_t``\  is returned
+On success that value will be \ ``MEMCACHED_SUCCESS``\ .
+Use memcached_strerror() to translate this value to a printable string.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcached_version.pod b/docs/memcached_version.pod
deleted file mode 100644 (file)
index 26e54e0..0000000
+++ /dev/null
@@ -1,56 +0,0 @@
-=head1 NAME
-
-memcached_lib_version, memcached_version - Get library version
-
-=head1 LIBRARY
-
-C Client Library for memcached (libmemcached, -lmemcached)
-
-=head1 SYNOPSIS
-
-  #include <memcached.h>
-
-  const char *
-    memcached_lib_version (void) 
-
-
-  memcached_return_t
-    memcached_version (memcached_st *ptr)
-
-
-=head1 DESCRIPTION
-
-memcached_lib_version() is used to return a simple version string representing
-the libmemcached version (version of the client library, not server)
-
-
-memcached_version() is used to set the major, minor, and micro versions of each
-memcached server being used by the memcached_st connection structure. It returns the 
-memcached server return code. 
-
-=head1 RETURN
-
-A string with the version of libmemcached driver is returned from
-memcached_lib_version()
-
-A value of type C<memcached_return_t> is returned from memcached_version()
-On success that value will be C<MEMCACHED_SUCCESS>. If called with the
-C<MEMCACHED_BEHAVIOR_USE_UDP> behavior set, the value C<MEMCACHED_NOT_SUPPORTED> 
-will be returned. Use memcached_strerror() to translate this value to 
-a printable string.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3) memcached_strerror(3)
-
-=cut
-
diff --git a/docs/memcached_version.rst b/docs/memcached_version.rst
new file mode 100644 (file)
index 0000000..00573d6
--- /dev/null
@@ -0,0 +1,90 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcached_lib_version, memcached_version - Get library version
+
+
+*******
+LIBRARY
+*******
+
+
+C Client Library for memcached (libmemcached, -lmemcached)
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   #include <memcached.h>
+   const char *
+     memcached_lib_version (void) 
+   memcached_return_t
+     memcached_version (memcached_st *ptr)
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+memcached_lib_version() is used to return a simple version string representing
+the libmemcached version (version of the client library, not server)
+
+memcached_version() is used to set the major, minor, and micro versions of each
+memcached server being used by the memcached_st connection structure. It returns the 
+memcached server return code.
+
+
+******
+RETURN
+******
+
+
+A string with the version of libmemcached driver is returned from
+memcached_lib_version()
+
+A value of type \ ``memcached_return_t``\  is returned from memcached_version()
+On success that value will be \ ``MEMCACHED_SUCCESS``\ . If called with the
+\ ``MEMCACHED_BEHAVIOR_USE_UDP``\  behavior set, the value \ ``MEMCACHED_NOT_SUPPORTED``\  
+will be returned. Use memcached_strerror() to translate this value to 
+a printable string.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3) memcached_strerror(3)
+
diff --git a/docs/memcapable.pod b/docs/memcapable.pod
deleted file mode 100644 (file)
index bd4d48f..0000000
+++ /dev/null
@@ -1,61 +0,0 @@
-=head1 NAME
-
-memcapable - Check memcached server capabilities
-
-=head1 SYNOPSIS
-
-  memcat [-h hostname] [-p port] [-c] [-v] [-t n]
-
-=head1 DESCRIPTION
-
-B<memcapable> connects to the specified memcached server and tries to
-determine its capabilities by running the various commands and verifying
-the response.
-
-=head1 OPTIONS
-
-The following options are supported:
-
-=over 3
-
-=item -h hostname
-
-Specify the hostname to connect to. The default is I<localhost>
-
-=item -p port
-
-Specify the port number to connect to. The default is I<11211>
-
-=item -c
-
-Generate a coredump when it detects an error from the server.
-
-=item -v
-
-Print out the comparison when it detects an error from the server.
-
-=item -t n
-
-Set the timeout from an IO operation to/from the server to I<n> seconds.
-
-=back
-
-=head1 LIMITATIONS
-
-The current version of memcapable will only verify the binary protocol.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Trond Norbye, E<lt>trond.norbye@gmail.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memcapable.rst b/docs/memcapable.rst
new file mode 100644 (file)
index 0000000..1583cc4
--- /dev/null
@@ -0,0 +1,104 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcapable - Check memcached server capabilities
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   memcat [-h hostname] [-p port] [-c] [-v] [-t n]
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **memcapable**\  connects to the specified memcached server and tries to
+determine its capabilities by running the various commands and verifying
+the response.
+
+
+*******
+OPTIONS
+*******
+
+
+The following options are supported:
+
+
+-h hostname
+ Specify the hostname to connect to. The default is \ *localhost*\ 
+
+
+-p port
+ Specify the port number to connect to. The default is \ *11211*\ 
+
+
+-c
+ Generate a coredump when it detects an error from the server.
+
+
+-v
+ Print out the comparison when it detects an error from the server.
+
+
+-t n
+ Set the timeout from an IO operation to/from the server to \ *n*\  seconds.
+
+
+
+***********
+LIMITATIONS
+***********
+
+
+The current version of memcapable will only verify the binary protocol.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Trond Norbye, <trond.norbye@gmail.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memcat.pod b/docs/memcat.pod
deleted file mode 100644 (file)
index 8e572b7..0000000
+++ /dev/null
@@ -1,37 +0,0 @@
-=head1 NAME
-
-memcat - Copy a set of keys to stdout
-
-=head1 SYNOPSIS
-
-  memcat [options] key key ...
-
-=head1 DESCRIPTION
-
-B<memcat> outputs to stdout the value a single or multiple set of keys
-stored in a memcached(1) server. If any key is not found an error is returned.
-
-It is similar to the standard UNIX cat(1) utility. 
-
-You can specify servers via the B<--servers> option or via the
-environment variable C<MEMCACHED_SERVERS>.
-
-For a full list of operations run the tool with the B<--help> option.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-Mark Atwood E<lt>mark@fallenpegasus.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memcat.rst b/docs/memcat.rst
new file mode 100644 (file)
index 0000000..c326573
--- /dev/null
@@ -0,0 +1,65 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcat - Copy a set of keys to stdout
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   memcat [options] key key ...
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **memcat**\  outputs to stdout the value a single or multiple set of keys
+stored in a memcached(1) server. If any key is not found an error is returned.
+
+It is similar to the standard UNIX cat(1) utility.
+
+You can specify servers via the \ **--servers**\  option or via the
+environment variable \ ``MEMCACHED_SERVERS``\ .
+
+For a full list of operations run the tool with the \ **--help**\  option.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+Mark Atwood <mark@fallenpegasus.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memcp.pod b/docs/memcp.pod
deleted file mode 100644 (file)
index 9be7cdd..0000000
+++ /dev/null
@@ -1,40 +0,0 @@
-=head1 NAME
-
-memcp - Copies files to a collection of memcached servers
-
-=head1 SYNOPSIS
-
-  memcp [options] file file <servers>
-
-=head1 DESCRIPTION
-
-B<memcp> copies one or more files into memcached(1) servers.
-It is similar to the standard UNIX cp(1) command.
-
-The key names will be the names of the files,
-without any directory path part.
-
-You can specify servers via the B<--servers> option or via the
-environment variable C<MEMCACHED_SERVERS>. If you specify neither of
-these, the final value in the command line list is the name of a
-server(s).
-
-For a full list of operations run the tool with the B<--help> option.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-Mark Atwood, E<lt>mark@fallenpegasus.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memcp.rst b/docs/memcp.rst
new file mode 100644 (file)
index 0000000..dda0100
--- /dev/null
@@ -0,0 +1,68 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memcp - Copies files to a collection of memcached servers
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   memcp [options] file file <servers>
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **memcp**\  copies one or more files into memcached(1) servers.
+It is similar to the standard UNIX cp(1) command.
+
+The key names will be the names of the files,
+without any directory path part.
+
+You can specify servers via the \ **--servers**\  option or via the
+environment variable \ ``MEMCACHED_SERVERS``\ . If you specify neither of
+these, the final value in the command line list is the name of a
+server(s).
+
+For a full list of operations run the tool with the \ **--help**\  option.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+Mark Atwood, <mark@fallenpegasus.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memdump.pod b/docs/memdump.pod
deleted file mode 100644 (file)
index 5a26be5..0000000
+++ /dev/null
@@ -1,31 +0,0 @@
-=head1 NAME
-
-memdump - Dump a list of keys from a server.
-
-=head1 SYNOPSIS
-
-  memdump [options]
-
-=head1 DESCRIPTION
-
-B<memdump> currently dumps a list of "keys" from all servers that 
-it is told to fetch from. Because memcached does not guarentee to
-provide all keys it is not possible to get a complete "dump".
-
-For a full list of operations run the tool with the B<--help> option.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memdump.rst b/docs/memdump.rst
new file mode 100644 (file)
index 0000000..8436470
--- /dev/null
@@ -0,0 +1,59 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memdump - Dump a list of keys from a server.
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   memdump [options]
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **memdump**\  currently dumps a list of "keys" from all servers that 
+it is told to fetch from. Because memcached does not guarentee to
+provide all keys it is not possible to get a complete "dump".
+
+For a full list of operations run the tool with the \ **--help**\  option.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memerror.pod b/docs/memerror.pod
deleted file mode 100644 (file)
index 4027877..0000000
+++ /dev/null
@@ -1,30 +0,0 @@
-=head1 NAME
-
-memerror - Translate a memcached error code to a string
-
-=head1 SYNOPSIS
-
-  memerror [options] error_code
-
-=head1 DESCRIPTION
-
-B<memerror> translate an error code from libmemcached(3) to  a human
-readable string.
-
-For a full list of operations run the tool with the B<--help> option.
-
-=head1 HOME
-
-To find out more infoerroration please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memerror.rst b/docs/memerror.rst
new file mode 100644 (file)
index 0000000..7253678
--- /dev/null
@@ -0,0 +1,58 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memerror - Translate a memcached error code to a string
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   memerror [options] error_code
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **memerror**\  translate an error code from libmemcached(3) to  a human
+readable string.
+
+For a full list of operations run the tool with the \ **--help**\  option.
+
+
+****
+HOME
+****
+
+
+To find out more infoerroration please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memflush.pod b/docs/memflush.pod
deleted file mode 100644 (file)
index f26e10c..0000000
+++ /dev/null
@@ -1,35 +0,0 @@
-=head1 NAME
-
-memflush - Reset a server or list of servers
-
-=head1 SYNOPSIS
-
-  memflush [options]
-
-=head1 DESCRIPTION
-
-B<memflush> resets the contents of memcached(1) servers.
-This means all data in these servers will be deleted.
-
-You can specify servers via the B<--servers> option or via the
-environment variable C<MEMCACHED_SERVERS>.
-
-For a full list of operations run the tool with the B<--help> option.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-Mark Atwood E<lt>mark@fallenpegasus.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memflush.rst b/docs/memflush.rst
new file mode 100644 (file)
index 0000000..5d6b865
--- /dev/null
@@ -0,0 +1,63 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memflush - Reset a server or list of servers
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   memflush [options]
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **memflush**\  resets the contents of memcached(1) servers.
+This means all data in these servers will be deleted.
+
+You can specify servers via the \ **--servers**\  option or via the
+environment variable \ ``MEMCACHED_SERVERS``\ .
+
+For a full list of operations run the tool with the \ **--help**\  option.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+Mark Atwood <mark@fallenpegasus.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memrm.pod b/docs/memrm.pod
deleted file mode 100644 (file)
index 9554f0a..0000000
+++ /dev/null
@@ -1,34 +0,0 @@
-=head1 NAME
-
-memrm - Remove a key(s) from a collection of memcached servers
-
-=head1 SYNOPSIS
-
-  memrm [options] key key ...
-
-=head1 DESCRIPTION
-
-B<memrm> removes items, specified by key, from memcached(1) servers. 
-
-You can specify servers via the B<--servers> option or via the
-environment variable C<MEMCACHED_SERVERS>.
-
-For a full list of operations run the tool with the B<--help> option.
-
-=head1 HOME
-
-To find out more information please check:
-L<https://launchpad.net/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-Mark Atwood, E<lt>mark@fallenpegasus.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memrm.rst b/docs/memrm.rst
new file mode 100644 (file)
index 0000000..21f5747
--- /dev/null
@@ -0,0 +1,62 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memrm - Remove a key(s) from a collection of memcached servers
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   memrm [options] key key ...
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **memrm**\  removes items, specified by key, from memcached(1) servers.
+
+You can specify servers via the \ **--servers**\  option or via the
+environment variable \ ``MEMCACHED_SERVERS``\ .
+
+For a full list of operations run the tool with the \ **--help**\  option.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`https://launchpad.net/libmemcached <https://launchpad.net/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+Mark Atwood, <mark@fallenpegasus.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memslap.pod b/docs/memslap.pod
deleted file mode 100644 (file)
index 462f67f..0000000
+++ /dev/null
@@ -1,1007 +0,0 @@
-=head1 NAME
-
-memslap - Load testing and benchmarking tool for memcached
-
-=head1 SYNOPSIS
-
-  memslap [options]
-
-=head1 DESCRIPTION
-
-B<memslap> is a load generation and benchmark tool for memcached(1)
-servers. It generates configurable workload such as threads, concurrencies, connections,
-run time, overwrite, miss rate, key size, value size, get/set proportion,
-expected throughput, and so on. Furthermore, it also supports data
-verification, expire-time verification, UDP, binary protocol, facebook test,
-replication test, multi-get and reconnection, etc.
-
-Memslap manages network connections like memcached with
-libevent. Each thread of memslap is bound with a CPU core, all
-the threads don't communicate with each other, and there are several socket
-connections in each thread. Each connection keeps key size distribution,
-value size distribution, and command distribution by itself.
-
-You can specify servers via the B<--servers> option or via the
-environment variable C<MEMCACHED_SERVERS>.
-
-
-=head1 FEATURES
-
-Memslap is developed to for the following purposes:
-
-=over
-
-=item Manages network connections with libevent asynchronously.
-
-=item Set both TCP and UDP up to use non-blocking IO.
-
-=item Improves parallelism: higher performance in multi-threads environments.
-
-=item Improves time efficiency: faster processing speed.
-
-=item Generates key and value more efficiently; key size distribution and value size distribution are configurable.
-
-=item Supports get, multi-get, and set commands; command distribution is configurable.
-
-=item Supports controllable miss rate and overwrite rate.
-
-=item Supports data and expire-time verification.
-
-=item Supports dumping statistic information periodically. 
-
-=item Supports thousands of TCP connections.
-
-=item Supports binary protocol.
-
-=item Supports facebook test (set with TCP and multi-get with UDP) and replication test.
-
-=back
-
-=head1 DETAILS
-
-=head2 Effective implementation of network.
-
-For memslap, both TCP and UDP use non-blocking network IO. All
-the network events are managed by libevent as memcached. The network module
-of memslap is similar to memcached. Libevent can ensure
-memslap can handle network very efficiently.
-
-=head2 Effective implementation of multi-threads and concurrency
-
-Memslap has the similar implementation of multi-threads to
-memcached. Memslap creates one or more self-governed threads;
-each thread is bound with one CPU core if the system supports setting CPU
-core affinity. 
-
-In addition, each thread has a libevent to manage the events of the network;
-each thread has one or more self-governed concurrencies; and each
-concurrency has one or more socket connections. All the concurrencies don’t
-communicate with each other even though they are in the same thread.
-
-Memslap can create thousands of socket connections, and each
-concurrency has tens of socket connections. Each concurrency randomly or
-sequentially selects one socket connection from its socket connection pool
-to run, so memslap can ensure each concurrency handles one
-socket connection at any given time. Users can specify the number of
-concurrency and socket connections of each concurrency according to their
-expected workload. 
-
-=head2 Effective implementation of generating key and value
-
-In order to improve time efficiency and space efficiency, 
-memslap creates a random characters table with 10M characters. All the
-suffixes of keys and values are generated from this random characters table.
-
-Memslap uses the offset in the character table and the length
-of the string to identify a string. It can save much memory.
-Each key contains two parts, a prefix and a suffix. The prefix is an
-uint64_t, 8 bytes. In order to verify the data set before, 
-memslap need to ensure each key is unique, so it uses the prefix to identify
-a key. The prefix cannot include illegal characters, such as ‘\r’, ‘\n’,
-‘\0’ and ‘ ‘. And memslap has an algorithm to ensure that. 
-
-Memslap doesn’t generate all the objects (key-value pairs) at
-the beginning. It only generates enough objects to fill the task window
-(default 10K objects) of each concurrency. Each object has the following
-basic information, key prefix, key suffix offset in the character table, key
-length, value offset in the character table, and value length.
-
-In the work process, each concurrency sequentially or randomly selects an
-object from the window to do set operation or get operation. At the same
-time, each concurrency kicks objects out of its window and adds new object
-into it. 
-
-=head2 Simple but useful task scheduling
-
-Memslap uses libevent to schedule all the concurrencies of
-threads, and each concurrency schedules tasks based on the local task
-window. Memslap assumes that if each concurrency keeps the same
-key distribution, value distribution and commands distribution, from
-outside, memslap keeps all the distribution as a whole. 
-Each task window includes a lot of objects, each object stores its basic
-information, such as key, value, expire time, and so on. At any time, all
-the objects in the window keep the same and fixed key and value
-distribution. If an object is overwritten, the value of the object will be
-updated. Memslap verifies the data or expire-time according to
-the object information stored in the task window.
-
-Libevent selects which concurrency to handle based on a specific network
-event. Then the concurrency selects which command (get or set) to operate
-based on the command distribution. If it needs to kick out an old object and
-add a new object, in order to keep the same key and value distribution, the
-new object must have the same key length and value length. 
-
-If memcached server has two cache layers (memory and SSD), running
-memslap with different window sizes can get different cache
-miss rates. If memslap adds enough objects into the windows at
-the beginning, and the cache of memcached cannot store all the objects
-initialized, then memslap will get some objects from the second
-cache layer. It causes the first cache layer to miss. So the user can
-specify the window size to get the expected miss rate of the first cache
-layer. 
-
-=head2 Useful implementation of multi-servers , UDP, TCP, multi-get and binary protocol
-
-Because each thread is self-governed, memslap can assign
-different threads to handle different memcached servers. This is just one of
-the ways in which memslap supports multiple servers. The only
-limitation is that the number of servers cannot be greater than the number
-of threads. The other way to support multiple servers is for replication
-test. Each concurrency has one socket connection to each memcached server.
-For the implementation, memslap can set some objects to one
-memcached server, and get these objects from the other servers.
-
-By default, Memslap does single get. If the user specifies
-multi-get option, memslap will collect enough get commands and
-pack and send the commands together. 
-
-Memslap supports both the ASCII protocol and binary protocol,
-but it runs on the ASCII protocol by default. 
-Memslap by default runs on the TCP protocol, but it also
-supports UDP. Because UDP is unreliable, dropped packages and out-of-order
-packages may occur. Memslap creates a memory buffer to handle
-these problems. Memslap tries to read all the response data of
-one command from the server and reorders the response data. If some packages
-get lost, the waiting timeout mechanism can ensure half-baked packages will
-be discarded and the next command will be sent.
-
-
-=head1 USAGE
-
-Below are some usage samples:
-
-=over 4
-
-=item memslap -s 127.0.0.1:11211 -S 5s
-
-=item memslap -s 127.0.0.1:11211 -t 2m -v 0.2 -e 0.05 -b
-
-=item memslap -s 127.0.0.1:11211 -F config -t 2m -w 40k -S 20s -o 0.2
-
-=item memslap -s 127.0.0.1:11211 -F config -t 2m -T 4 -c 128 -d 20 -P 40k
-
-=item memslap -s 127.0.0.1:11211 -F config -t 2m -d 50 -a -n 40
-
-=item memslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m
-
-=item memslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m -p 2
-
-=back
-
-The user must specify one server at least to run memslap. The
-rest of the parameters have default values, as shown below:
-
-Thread number = 1                    Concurrency = 16
-
-Run time = 600 seconds                Configuration file = NULL
-
-Key size = 64                         Value size = 1024
-
-Get/set = 9:1                         Window size = 10k
-
-Execute number = 0                   Single get = true
-
-Multi-get = false                      Number of sockets of each concurrency = 1
-
-Reconnect = false                     Data verification = false
-
-Expire-time verification = false           ASCII protocol = true
-
-Binary protocol = false                 Dumping statistic information
-
-periodically = false
-
-Overwrite proportion = 0%             UDP = false
-
-TCP = true                           Limit throughput = false
-
-Facebook test = false                  Replication test = false
-
-=head2 Key size, value size and command distribution.
-
-All the distributions are read from the configuration file specified by user
-with “—cfg_cmd” option. If the user does not specify a configuration file,
-memslap will run with the default distribution (key size = 64,
-value size = 1024, get/set = 9:1). For information on how to edit the
-configuration file, refer to the “Configuration File” section.
-
-The minimum key size is 16 bytes; the maximum key size is 250 bytes. The
-precision of proportion is 0.001. The proportion of distribution will be
-rounded to 3 decimal places.
-
-The minimum value size is 1 bytes; the maximum value size is 1M bytes. The
-precision of proportion is 0.001. The proportion of distribution will be
-rounded to 3 decimal places.
-Currently, memslap only supports set and get commands. And it
-supports 100% set and 100% get. For 100% get, it will preset some objects to
-the server.
-
-=head2 Multi-thread and concurrency
-
-The high performance of memslap benefits from the special
-schedule of thread and concurrency. It’s important to specify the proper
-number of them. The default number of threads is 1; the default number of
-concurrency is 16. The user can use “—threads” and “--concurrency” to
-specify these variables.
-
-If the system supports setting CPU affinity and the number of threads
-specified by the user is greater than 1, memslap will try to
-bind each thread to a different CPU core. So if you want to get the best
-performance memslap, it is better to specify the number of
-thread equal to the number of CPU cores. The number of threads specified by
-the user can also be less or greater than the number of CPU cores. Because
-of the limitation of implementation, the number of concurrencies could be
-the multiple of the number of threads.
-
-1. For 8 CPU cores system
-
-For example:
-
---threads=2 --concurrency=128
-
---threads=8 --concurrency=128
-
---threads=8 --concurrency=256
-
---threads=12 --concurrency=144
-
-2. For 16 CPU cores system
-
-For example:
-
---threads=8 --concurrency=128
-
---threads=16 --concurrency=256
-
---threads=16 --concurrency=512
-
---threads=24 --concurrency=288
-
-The memslap performs very well, when
-used to test the performance of memcached servers.
-Most of the time, the bottleneck is the network or
-the server. If for some reason the user wants to
-limit the performance of memslap, there
-are two ways to do this:
-
-Decrease the number of threads and concurrencies.
-Use the option “--tps” that memslap
-provides to limit the throughput. This option allows
-the user to get the expected throughput. For
-example, assume that the maximum throughput is 50
-kops/s for a specific configuration, you can specify
-the throughput equal to or less than the maximum
-throughput using “--tps” option.
-
-=head2 Window size
-
-Most of the time, the user does not need to specify the window size. The
-default window size is 10k. For Schooner Memcached, the user can specify
-different window sizes to get different cache miss rates based on the test
-case. Memslap supports cache miss rate between 0% and 100%.
-If you use this utility to test the performance of Schooner Memcached, you
-can specify a proper window size to get the expected cache miss rate. The
-formula for calculating window size is as follows:
-
-Assume that the key size is 128 bytes, and the value size is 2048 bytes, and
-concurrency=128.
-
-1. Small cache cache_size=1M, 100% cache miss (all data get from SSD).
-win_size=10k
-
-2. cache_size=4G
-
-(1). cache miss rate 0%
-
-win_size=8k
-
-(2). cache miss rate 5%
-
-win_size=11k
-
-3. cache_size=16G
-
-(1). cache miss rate 0%
-
-win_size=32k
-
-(2). cache miss
-
-rate 5%
-
-win_size=46k
-
-The formula for calculating window size for cache miss rate 0%: 
-
-cache_size / concurrency / (key_size + value_size) * 0.5
-
-The formula for calculating window size for cache miss rate 5%: 
-
-cache_size / concurrency / (key_size + value_size) * 0.7
-
-=head2 Verification
-
-Memslap supports both data verification and expire-time
-verification. The user can use "--verify=" or "-v" to specify the proportion
-of data verification. In theory, it supports 100% data verification. The
-user can use "--exp_verify=" or "-e" to specify the proportion of
-expire-time verification. In theory, it supports 100% expire-time
-verification. Specify the "--verbose" options to get more detailed error
-information.
-
-For example: --exp_verify=0.01 –verify=0.1 , it means that 1% of the objects 
-set with expire-time, 10% of the objects gotten will be verified. If the
-objects are gotten, memslap will verify the expire-time and
-value. 
-
-=head2 multi-servers and multi-clients
-
-Memslap supports multi-servers based on self-governed thread.
-There is a limitation that the number of servers cannot be greater than the
-number of threads. Memslap assigns one thread to handle one
-server at least. The user can use the "--servers=" or "-s" option to specify
-multi-servers. 
-
-For example:
-
---servers=10.1.1.1:11211,10.1.1.2:11212,10.1.1.3:11213 --threads=6 --concurrency=36
-
-The above command means that there are 6 threads, with each thread having 6
-concurrencies and that threads 0 and 3 handle server 0 (10.1.1.1); threads 1
-and 4 handle server 1 (10.1.1.2); and thread 2 and 5 handle server 2
-(10.1.1.3).  
-
-All the threads and concurrencies in memslap are self-governed.
-
-So is memslap. The user can start up several 
-memslap instances. The user can run memslap on different client
-machines to communicate with the same memcached server at the same. It is
-recommended that the user start different memslap on different
-machines using the same configuration. 
-
-=head2 Run with execute number mode or time mode
-
-The default memslap runs with time mode. The default run time
-is 10 minutes. If it times out, memslap will exit. Do not
-specify both execute number mode and time mode at the same time; just
-specify one instead. 
-
-For example:
-
---time=30s (It means the test will run 30 seconds.)
-
---execute_number=100000 (It means that after running 100000 commands, the test will exit.)
-
-=head2 Dump statistic information periodically.
-
-The user can use "--stat_freq=" or "-S" to specify the frequency.
-
-For example:
-
---stat_freq=20s
-
-Memslap will dump the statistics of the commands (get and set) at the frequency of every 20
-seconds. 
-
-For more information on the format of dumping statistic information, refer to “Format of Output” section.
-
-=head2 Multi-get
-
-The user can use "--division=" or "-d" to specify multi-get keys count.
-Memslap by default does single get with TCP. Memslap also supports data 
-verification and expire-time verification for multi-get. 
-
-Memslap supports multi-get with both TCP and UDP. Because of
-the different implementation of the ASCII protocol and binary protocol,
-there are some differences between the two. For the ASCII protocol,
-memslap sends one “multi-get” to the server once. For the
-binary protocol, memslap sends several single get commands
-together as “multi-get” to the server.
-
-=head2 UDP and TCP
-
-Memslap supports both UDP and TCP. For TCP,
-memslap does not reconnect the memcached server if socket connections are
-lost. If all the socket connections are lost or memcached server crashes,
-memslap will exit. If the user specifies the “--reconnect”
-option when socket connections are lost, it will reconnect them. 
-
-User can use “--udp” to enable the UDP feature, but UDP comes with some
-limitations: 
-
-UDP cannot set data more than 1400 bytes. 
-
-UDP is not supported by the binary protocol because the binary protocol of
-memcached does not support that.
-
-UDP doesn’t support reconnection.
-
-=head2 Facebook test
-
-Set data with TCP and multi-get with UDP. Specify the following options: 
-
-"--facebook --division=50"
-
-If you want to create thousands of TCP connections, specify the
-
-"--conn_sock=" option. 
-
-For example: --facebook --division=50 --conn_sock=200
-
-The above command means that memslap will do facebook test,
-each concurrency has 200 socket TCP connections and one UDP socket.
-
-Memslap sets objects with the TCP socket, and multi-gets 50
-objects once with the UDP socket.
-
-If you specify "--division=50", the key size must be less that 25 bytes
-because the UDP packet size is 1400 bytes.
-
-=head2 Replication test
-
-For replication test, the user must specify at least two memcached servers.
-The user can use “—rep_write=” option to enable feature. 
-
-For example:
-
---servers=10.1.1.1:11211,10.1.1.2:11212 –rep_write=2
-
-The above command means that there are 2 replication memcached servers,
-memslap will set objects to both server 0 and server 1, get
-objects which are set to server 0 before from server 1, and also get objects
-which are set to server 1 before from server 0. If server 0 crashes,
-memslap will only get objects from server 1. If server 0 comes
-back to life again, memslap will reconnect server 0. If both
-server 0 and server 1 crash, memslap will exit.
-
-=head2  Supports thousands of TCP connections
-
-Start memslap with "--conn_sock=" or "-n" to enable this
-feature. Make sure that your system can support opening thousands of files
-and creating thousands of sockets. However, this feature does not support
-reconnection if sockets disconnect. 
-
-For example: 
-
---threads=8 --concurrency=128 --conn_sock=128
-
-The above command means that memslap starts up 8 threads, each
-thread has 16 concurrencies, each concurrency has 128 TCP socket
-connections, and the total number of TCP socket connections is 128 * 128 =
-16384.
-
-=head2 Supports binary protocol
-
-Start memslap with "--binary" or "-B" options to enable this
-feature. It supports all the above features except UDP, because the latest
-memcached 1.3.3 does not implement binary UDP protocol.
-
-For example:
-
---binary
-
-Since memcached 1.3.3 doesn't implement binary UDP protocol,
-memslap does not support UDP. In addition, memcached 1.3.3 does not support
-multi-get. If you specify "--division=50" option, it just sends 50 get
-commands together as “mulit-get” to the server.
-
-=head1 Configuration file
-
-This section describes the format of the configuration file.  By default
-when no configuration file is specified memslap reads the default
-one located at ~/.memslap.cnf.
-
-Below is a sample configuration file:
-
- ***************************************************************************
- #comments should start with '#'
- #key 
- #start_len end_len proportion
- #
- #key length range from start_len to end_len
- #start_len must be equal to or greater than 16
- #end_len must be equal to or less than 250
- #start_len must be equal to or greater than end_len
- #memslap will generate keys according to the key range
- #proportion: indicates keys generated from one range accounts for the total
- generated keys  
- #
- #example1: key range 16~100 accounts for 80%
- #          key range 101~200 accounts for 10%
- #          key range 201~250 accounts for 10%
- #          total should be 1 (0.8+0.1+0.1 = 1)
- #
- #          16 100 0.8  
- #          101 200 0.1
- #          201 249 0.1
- #
- #example2: all keys length are 128 bytes
- #
- #          128 128 1 
- key
- 128 128 1  
- #value 
- #start_len end_len proportion
- #
- #value length range from start_len to end_len
- #start_len must be equal to or greater than 1
- #end_len must be equal to or less than 1M
- #start_len must be equal to or greater than end_len
- #memslap will generate values according to the value range
- #proportion: indicates values generated from one range accounts for the
- total generated values  
- #
- #example1: value range 1~1000 accounts for 80%
- #          value range 1001~10000 accounts for 10%
- #          value range 10001~100000 accounts for 10%
- #          total should be 1 (0.8+0.1+0.1 = 1)
- #
- #          1 1000 0.8  
- #          1001 10000 0.1
- #          10001 100000 0.1
- #
- #example2: all value length are 128 bytes
- #
- #          128 128 1 
- value
- 2048 2048 1
- #cmd
- #cmd_type cmd_proportion
- #
- #currently memslap only supports get and set command.
- #
- #cmd_type
- #set     0
- #get     1
- #
- #example: set command accounts for 50%
- #         get command accounts for 50%
- #         total should be 1 (0.5+0.5 = 1)
- #
- #         cmd
- #         0    0.5
- #         1    0.5
- cmd
- 0    0.1
- 1.0 0.9
-
-
-
-=head1 Format of output
-
-At the beginning, memslap displays some configuration information as follows:
-
-=over 4
-
-=item servers : 127.0.0.1:11211
-
-=item threads count: 1
-
-=item concurrency: 16
-
-=item run time: 20s
-
-=item windows size: 10k
-
-=item set proportion: set_prop=0.10
-
-=item get proportion: get_prop=0.90
-
-=back
-
-=head2 Where
-
-=over 4
-
-=item servers : "servers"
-
-The servers used by memslap.
-
-=item threads count
-
-The number of threads memslap runs with.
-
-=item concurrency
-
-The number of concurrencies memslap runs with.
-
-=item run time
-
-How long to run memslap.
-
-=item windows size
-
-The task window size of each concurrency.
-
-=item set proportion
-
-The proportion of set command.
-
-=item get proportion
-
-The proportion of get command.
-
-=back
-
-The output of dynamic statistics is something like this:
-
- ---------------------------------------------------------------------------------------------------------------------------------
- Get Statistics
- Type  Time(s)  Ops   TPS(ops/s)  Net(M/s)  Get_miss  Min(us)  Max(us)
- Avg(us)  Std_dev    Geo_dist  
- Period   5   345826  69165     65.3      0         27      2198     203
- 95.43      177.29
- Global  20  1257935  62896     71.8      0         26      3791     224
- 117.79     192.60
-  
- Set Statistics
- Type  Time(s)  Ops   TPS(ops/s)  Net(M/s)  Get_miss  Min(us)  Max(us)
- Avg(us)  Std_dev    Geo_dist  
- Period   5    38425   7685      7.3       0         42      628     240
- 88.05      220.21
- Global   20   139780  6989      8.0       0         37      3790    253
- 117.93     224.83
-  
- Total Statistics
- Type  Time(s)  Ops   TPS(ops/s)  Net(M/s)  Get_miss  Min(us)  Max(us)
- Avg(us)  Std_dev    Geo_dist 
- Period   5   384252   76850     72.5      0        27      2198     207
- 94.72      181.18
- Global  20  1397720   69886     79.7      0        26      3791     227
- 117.93     195.60
- ---------------------------------------------------------------------------------------------------------------------------------
-
-=head2 Where
-
-=over 4
-
-=item Get Statistics
-
-Statistics information of get command
-
-=item Set Statistics
-
-Statistics information of set command
-
-=item Total Statistics
-
-Statistics information of both get and set command
-
-=item Period
-
-Result within a period
-
-=item Global
-
-Accumulated results
-
-=item Ops
-
-Total operations
-
-=item TPS
-
-Throughput, operations/second
-
-=item Net
-
-The rate of network
-
-=item Get_miss
-
-How many objects can’t be gotten
-
-=item Min
-
-The minimum response time
-
-=item Max
-
-The maximum response time
-
-=item Avg: 
-
-The average response time
-
-=item Std_dev
-
-Standard deviation of response time
-
-=item Geo_dist
-
-Geometric distribution based on natural exponential function
-
-=back
-
-At the end, memslap will output something like this:
-
-  ---------------------------------------------------------------------------------------------------------------------------------
-  Get Statistics (1257956 events)
-    Min:        26
-    Max:      3791
-    Avg:       224
-    Geo:    192.60
-    Std:    116.23
-                    Log2 Dist:
-                      4:        0       10    84490   215345
-                      8:   484890   459823    12543      824
-                     12:       31
-
-   Set Statistics (139782 events)
-      Min:        37
-      Max:      3790
-      Avg:       253
-      Geo:    224.84
-      Std:    116.83
-      Log2 Dist: 
-        4:        0        0     4200 16988
-        8:    50784    65574 2064      167
-        12:        5
-   
-    Total Statistics (1397738 events)
-        Min:        26
-        Max:      3791
-        Avg:       227
-        Geo:    195.60
-        Std:    116.60
-        Log2 Dist:
-          4:        0       10    88690   232333
-          8:   535674   525397    14607      991
-          12:       36
-
-  cmd_get: 1257969
-  cmd_set: 139785
-  get_misses: 0
-  verify_misses: 0
-  verify_failed: 0
-  expired_get: 0
-  unexpired_unget: 0
-  written_bytes: 242516030
-  read_bytes: 1003702556
-  object_bytes: 152086080
-  packet_disorder: 0
-  packet_drop: 0
-  udp_timeout: 0
-
-  Run time: 20.0s Ops: 1397754 TPS: 69817 Net_rate: 59.4M/s
-  ---------------------------------------------------------------------------------------------------------------------------------
-
-=head2 Where
-
-=over 4
-
-=item Get Statistics
-
-Get statistics of response time
-
-=item Set Statistics
-
-Set statistics of response time
-
-=item Total Statistics
-
-Both get and set statistics of response time
-
-=item Min
-
-The accumulated and minimum response time
-
-=item Max
-
-The accumulated and maximum response time
-
-=item Avg
-
-The accumulated and average response time
-
-=item Std
-
-Standard deviation of response time
-
-=item Log2 Dist
-
-Geometric distribution based on logarithm 2
-
-=item cmd_get
-
-Total get commands done
-
-=item cmd_set
-
-Total set commands done
-
-=item get_misses
-
-How many objects can’t be gotten from server
-
-=item verify_misses
-
-How many objects need to verify but can’t get them
-
-=item verify_failed
-
-How many objects with insistent value
-
-=item expired_get
-
-How many objects are expired but we get them
-
-=item unexpired_unget
-
-How many objects are unexpired but we can’t get them
-
-=item written_bytes
-
-Total written bytes
-
-=item read_bytes
-
-Total read bytes
-
-=item object_bytes
-
-Total object bytes
-
-=item packet_disorder
-
-How many UDP packages are disorder
-
-=item packet_drop
-
-How many UDP packages are lost
-
-=item udp_timeout
-
-How many times UDP time out happen
-
-=item Run time
-
-Total run time
-
-=item Ops
-
-Total operations 
-
-=item TPS
-
-Throughput, operations/second
-
-=item Net_rate
-
-The average rate of network
-
-=back
-
-=head1 OPTIONS
-
--s, --servers=
-    List one or more servers to connect. Servers count must be less than
-    threads count. e.g.: --servers=localhost:1234,localhost:11211
-
--T, --threads=
-    Number of threads to startup, better equal to CPU numbers. Default 8.
-
--c, --concurrency=
-    Number of concurrency to simulate with load. Default 128.
-
--n, --conn_sock=
-    Number of TCP socks per concurrency. Default 1.
-
--x, --execute_number=
-    Number of operations(get and set) to execute for the
-    given test. Default 1000000.
-
--t, --time=
-    How long the test to run, suffix: s-seconds, m-minutes, h-hours,
-    d-days e.g.: --time=2h.
-
--F, --cfg_cmd=
-    Load the configure file to get command,key and value distribution list.
-
--w, --win_size=
-    Task window size of each concurrency, suffix: K, M e.g.: --win_size=10k.
-    Default 10k.
-
--X, --fixed_size=
-    Fixed length of value.
-
--v, --verify=
-    The proportion of date verification, e.g.: --verify=0.01
-
--d, --division=
-    Number of keys to multi-get once. Default 1, means single get.
-
--S, --stat_freq=
-    Frequency of dumping statistic information. suffix: s-seconds,
-    m-minutes, e.g.: --resp_freq=10s.
-
--e, --exp_verify=
-    The proportion of objects with expire time, e.g.: --exp_verify=0.01.
-    Default no object with expire time
-
--o, --overwrite=
-    The proportion of objects need overwrite, e.g.: --overwrite=0.01.
-    Default never overwrite object.
-
--R, --reconnect 
-    Reconnect support, when connection is closed it will be reconnected.
-
--U, --udp 
-    UDP support, default memslap uses TCP, TCP port and UDP port of
-    server must be same.
-
--a, --facebook 
-    Whether it enables facebook test feature, set with TCP and multi-get with UDP.
-
--B, --binary 
-    Whether it enables binary protocol. Default with ASCII protocol.
-
--P, --tps=
-    Expected throughput, suffix: K, e.g.: --tps=10k.
-
--p, --rep_write=
-    The first nth servers can write data, e.g.: --rep_write=2.
-
--b, --verbose 
-    Whether it outputs detailed information when verification fails.
-
--h, --help 
-    Display this message and then exit.
-
--V, --version 
-    Display the version of the application and then exit.
-
-=head1 EXAMPLES
-
-memslap -s 127.0.0.1:11211 -S 5s
-
-memslap -s 127.0.0.1:11211 -t 2m -v 0.2 -e 0.05 -b
-
-memslap -s 127.0.0.1:11211 -F config -t 2m -w 40k -S 20s -o 0.2
-
-memslap -s 127.0.0.1:11211 -F config -t 2m -T 4 -c 128 -d 20 -P 40k
-
-memslap -s 127.0.0.1:11211 -F config -t 2m -d 50 -a -n 40
-
-memslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m
-
-memslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m -p 2
-
-=head1 HOME
-
-To find out more information please check:
-L<http://launchpad.org/libmemcached>
-
-=head1 AUTHORS
-
-Mingqiang Zhuang E<lt>mingqiangzhuang@hengtiansoft.comE<gt> (Schooner Technolgy)
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memslap.rst b/docs/memslap.rst
new file mode 100644 (file)
index 0000000..80fb7a7
--- /dev/null
@@ -0,0 +1,1260 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memslap - Load testing and benchmarking tool for memcached
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   memslap [options]
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **memslap**\  is a load generation and benchmark tool for memcached(1)
+servers. It generates configurable workload such as threads, concurrencies, connections,
+run time, overwrite, miss rate, key size, value size, get/set proportion,
+expected throughput, and so on. Furthermore, it also supports data
+verification, expire-time verification, UDP, binary protocol, facebook test,
+replication test, multi-get and reconnection, etc.
+
+Memslap manages network connections like memcached with
+libevent. Each thread of memslap is bound with a CPU core, all
+the threads don't communicate with each other, and there are several socket
+connections in each thread. Each connection keeps key size distribution,
+value size distribution, and command distribution by itself.
+
+You can specify servers via the \ **--servers**\  option or via the
+environment variable \ ``MEMCACHED_SERVERS``\ .
+
+
+********
+FEATURES
+********
+
+
+Memslap is developed to for the following purposes:
+
+
+Manages network connections with libevent asynchronously.
+
+
+
+Set both TCP and UDP up to use non-blocking IO.
+
+
+
+Improves parallelism: higher performance in multi-threads environments.
+
+
+
+Improves time efficiency: faster processing speed.
+
+
+
+Generates key and value more efficiently; key size distribution and value size distribution are configurable.
+
+
+
+Supports get, multi-get, and set commands; command distribution is configurable.
+
+
+
+Supports controllable miss rate and overwrite rate.
+
+
+
+Supports data and expire-time verification.
+
+
+
+Supports dumping statistic information periodically.
+
+
+
+Supports thousands of TCP connections.
+
+
+
+Supports binary protocol.
+
+
+
+Supports facebook test (set with TCP and multi-get with UDP) and replication test.
+
+
+
+
+*******
+DETAILS
+*******
+
+
+Effective implementation of network.
+====================================
+
+
+For memslap, both TCP and UDP use non-blocking network IO. All
+the network events are managed by libevent as memcached. The network module
+of memslap is similar to memcached. Libevent can ensure
+memslap can handle network very efficiently.
+
+
+Effective implementation of multi-threads and concurrency
+=========================================================
+
+
+Memslap has the similar implementation of multi-threads to
+memcached. Memslap creates one or more self-governed threads;
+each thread is bound with one CPU core if the system supports setting CPU
+core affinity.
+
+In addition, each thread has a libevent to manage the events of the network;
+each thread has one or more self-governed concurrencies; and each
+concurrency has one or more socket connections. All the concurrencies don’t
+communicate with each other even though they are in the same thread.
+
+Memslap can create thousands of socket connections, and each
+concurrency has tens of socket connections. Each concurrency randomly or
+sequentially selects one socket connection from its socket connection pool
+to run, so memslap can ensure each concurrency handles one
+socket connection at any given time. Users can specify the number of
+concurrency and socket connections of each concurrency according to their
+expected workload.
+
+
+Effective implementation of generating key and value
+====================================================
+
+
+In order to improve time efficiency and space efficiency, 
+memslap creates a random characters table with 10M characters. All the
+suffixes of keys and values are generated from this random characters table.
+
+Memslap uses the offset in the character table and the length
+of the string to identify a string. It can save much memory.
+Each key contains two parts, a prefix and a suffix. The prefix is an
+uint64_t, 8 bytes. In order to verify the data set before, 
+memslap need to ensure each key is unique, so it uses the prefix to identify
+a key. The prefix cannot include illegal characters, such as ‘\r’, ‘\n’,
+‘\0’ and ‘ ‘. And memslap has an algorithm to ensure that.
+
+Memslap doesn’t generate all the objects (key-value pairs) at
+the beginning. It only generates enough objects to fill the task window
+(default 10K objects) of each concurrency. Each object has the following
+basic information, key prefix, key suffix offset in the character table, key
+length, value offset in the character table, and value length.
+
+In the work process, each concurrency sequentially or randomly selects an
+object from the window to do set operation or get operation. At the same
+time, each concurrency kicks objects out of its window and adds new object
+into it.
+
+
+Simple but useful task scheduling
+=================================
+
+
+Memslap uses libevent to schedule all the concurrencies of
+threads, and each concurrency schedules tasks based on the local task
+window. Memslap assumes that if each concurrency keeps the same
+key distribution, value distribution and commands distribution, from
+outside, memslap keeps all the distribution as a whole. 
+Each task window includes a lot of objects, each object stores its basic
+information, such as key, value, expire time, and so on. At any time, all
+the objects in the window keep the same and fixed key and value
+distribution. If an object is overwritten, the value of the object will be
+updated. Memslap verifies the data or expire-time according to
+the object information stored in the task window.
+
+Libevent selects which concurrency to handle based on a specific network
+event. Then the concurrency selects which command (get or set) to operate
+based on the command distribution. If it needs to kick out an old object and
+add a new object, in order to keep the same key and value distribution, the
+new object must have the same key length and value length.
+
+If memcached server has two cache layers (memory and SSD), running
+memslap with different window sizes can get different cache
+miss rates. If memslap adds enough objects into the windows at
+the beginning, and the cache of memcached cannot store all the objects
+initialized, then memslap will get some objects from the second
+cache layer. It causes the first cache layer to miss. So the user can
+specify the window size to get the expected miss rate of the first cache
+layer.
+
+
+Useful implementation of multi-servers , UDP, TCP, multi-get and binary protocol
+================================================================================
+
+
+Because each thread is self-governed, memslap can assign
+different threads to handle different memcached servers. This is just one of
+the ways in which memslap supports multiple servers. The only
+limitation is that the number of servers cannot be greater than the number
+of threads. The other way to support multiple servers is for replication
+test. Each concurrency has one socket connection to each memcached server.
+For the implementation, memslap can set some objects to one
+memcached server, and get these objects from the other servers.
+
+By default, Memslap does single get. If the user specifies
+multi-get option, memslap will collect enough get commands and
+pack and send the commands together.
+
+Memslap supports both the ASCII protocol and binary protocol,
+but it runs on the ASCII protocol by default. 
+Memslap by default runs on the TCP protocol, but it also
+supports UDP. Because UDP is unreliable, dropped packages and out-of-order
+packages may occur. Memslap creates a memory buffer to handle
+these problems. Memslap tries to read all the response data of
+one command from the server and reorders the response data. If some packages
+get lost, the waiting timeout mechanism can ensure half-baked packages will
+be discarded and the next command will be sent.
+
+
+
+*****
+USAGE
+*****
+
+
+Below are some usage samples:
+
+
+memslap -s 127.0.0.1:11211 -S 5s
+
+
+
+memslap -s 127.0.0.1:11211 -t 2m -v 0.2 -e 0.05 -b
+
+
+
+memslap -s 127.0.0.1:11211 -F config -t 2m -w 40k -S 20s -o 0.2
+
+
+
+memslap -s 127.0.0.1:11211 -F config -t 2m -T 4 -c 128 -d 20 -P 40k
+
+
+
+memslap -s 127.0.0.1:11211 -F config -t 2m -d 50 -a -n 40
+
+
+
+memslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m
+
+
+
+memslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m -p 2
+
+
+
+The user must specify one server at least to run memslap. The
+rest of the parameters have default values, as shown below:
+
+Thread number = 1                    Concurrency = 16
+
+Run time = 600 seconds                Configuration file = NULL
+
+Key size = 64                         Value size = 1024
+
+Get/set = 9:1                         Window size = 10k
+
+Execute number = 0                   Single get = true
+
+Multi-get = false                      Number of sockets of each concurrency = 1
+
+Reconnect = false                     Data verification = false
+
+Expire-time verification = false           ASCII protocol = true
+
+Binary protocol = false                 Dumping statistic information
+
+periodically = false
+
+Overwrite proportion = 0%             UDP = false
+
+TCP = true                           Limit throughput = false
+
+Facebook test = false                  Replication test = false
+
+Key size, value size and command distribution.
+==============================================
+
+
+All the distributions are read from the configuration file specified by user
+with “—cfg_cmd” option. If the user does not specify a configuration file,
+memslap will run with the default distribution (key size = 64,
+value size = 1024, get/set = 9:1). For information on how to edit the
+configuration file, refer to the “Configuration File” section.
+
+The minimum key size is 16 bytes; the maximum key size is 250 bytes. The
+precision of proportion is 0.001. The proportion of distribution will be
+rounded to 3 decimal places.
+
+The minimum value size is 1 bytes; the maximum value size is 1M bytes. The
+precision of proportion is 0.001. The proportion of distribution will be
+rounded to 3 decimal places.
+Currently, memslap only supports set and get commands. And it
+supports 100% set and 100% get. For 100% get, it will preset some objects to
+the server.
+
+
+Multi-thread and concurrency
+============================
+
+
+The high performance of memslap benefits from the special
+schedule of thread and concurrency. It’s important to specify the proper
+number of them. The default number of threads is 1; the default number of
+concurrency is 16. The user can use “—threads” and “--concurrency” to
+specify these variables.
+
+If the system supports setting CPU affinity and the number of threads
+specified by the user is greater than 1, memslap will try to
+bind each thread to a different CPU core. So if you want to get the best
+performance memslap, it is better to specify the number of
+thread equal to the number of CPU cores. The number of threads specified by
+the user can also be less or greater than the number of CPU cores. Because
+of the limitation of implementation, the number of concurrencies could be
+the multiple of the number of threads.
+
+1. For 8 CPU cores system
+
+For example:
+
+--threads=2 --concurrency=128
+
+--threads=8 --concurrency=128
+
+--threads=8 --concurrency=256
+
+--threads=12 --concurrency=144
+
+2. For 16 CPU cores system
+
+For example:
+
+--threads=8 --concurrency=128
+
+--threads=16 --concurrency=256
+
+--threads=16 --concurrency=512
+
+--threads=24 --concurrency=288
+
+The memslap performs very well, when
+used to test the performance of memcached servers.
+Most of the time, the bottleneck is the network or
+the server. If for some reason the user wants to
+limit the performance of memslap, there
+are two ways to do this:
+
+Decrease the number of threads and concurrencies.
+Use the option “--tps” that memslap
+provides to limit the throughput. This option allows
+the user to get the expected throughput. For
+example, assume that the maximum throughput is 50
+kops/s for a specific configuration, you can specify
+the throughput equal to or less than the maximum
+throughput using “--tps” option.
+
+
+Window size
+===========
+
+
+Most of the time, the user does not need to specify the window size. The
+default window size is 10k. For Schooner Memcached, the user can specify
+different window sizes to get different cache miss rates based on the test
+case. Memslap supports cache miss rate between 0% and 100%.
+If you use this utility to test the performance of Schooner Memcached, you
+can specify a proper window size to get the expected cache miss rate. The
+formula for calculating window size is as follows:
+
+Assume that the key size is 128 bytes, and the value size is 2048 bytes, and
+concurrency=128.
+
+1. Small cache cache_size=1M, 100% cache miss (all data get from SSD).
+win_size=10k
+
+2. cache_size=4G
+
+(1). cache miss rate 0%
+
+win_size=8k
+
+(2). cache miss rate 5%
+
+win_size=11k
+
+3. cache_size=16G
+
+(1). cache miss rate 0%
+
+win_size=32k
+
+(2). cache miss
+
+rate 5%
+
+win_size=46k
+
+The formula for calculating window size for cache miss rate 0%:
+
+cache_size / concurrency / (key_size + value_size) \* 0.5
+
+The formula for calculating window size for cache miss rate 5%:
+
+cache_size / concurrency / (key_size + value_size) \* 0.7
+
+
+Verification
+============
+
+
+Memslap supports both data verification and expire-time
+verification. The user can use "--verify=" or "-v" to specify the proportion
+of data verification. In theory, it supports 100% data verification. The
+user can use "--exp_verify=" or "-e" to specify the proportion of
+expire-time verification. In theory, it supports 100% expire-time
+verification. Specify the "--verbose" options to get more detailed error
+information.
+
+For example: --exp_verify=0.01 –verify=0.1 , it means that 1% of the objects 
+set with expire-time, 10% of the objects gotten will be verified. If the
+objects are gotten, memslap will verify the expire-time and
+value.
+
+
+multi-servers and multi-clients
+===============================
+
+
+Memslap supports multi-servers based on self-governed thread.
+There is a limitation that the number of servers cannot be greater than the
+number of threads. Memslap assigns one thread to handle one
+server at least. The user can use the "--servers=" or "-s" option to specify
+multi-servers.
+
+For example:
+
+--servers=10.1.1.1:11211,10.1.1.2:11212,10.1.1.3:11213 --threads=6 --concurrency=36
+
+The above command means that there are 6 threads, with each thread having 6
+concurrencies and that threads 0 and 3 handle server 0 (10.1.1.1); threads 1
+and 4 handle server 1 (10.1.1.2); and thread 2 and 5 handle server 2
+(10.1.1.3).
+
+All the threads and concurrencies in memslap are self-governed.
+
+So is memslap. The user can start up several 
+memslap instances. The user can run memslap on different client
+machines to communicate with the same memcached server at the same. It is
+recommended that the user start different memslap on different
+machines using the same configuration.
+
+
+Run with execute number mode or time mode
+=========================================
+
+
+The default memslap runs with time mode. The default run time
+is 10 minutes. If it times out, memslap will exit. Do not
+specify both execute number mode and time mode at the same time; just
+specify one instead.
+
+For example:
+
+--time=30s (It means the test will run 30 seconds.)
+
+--execute_number=100000 (It means that after running 100000 commands, the test will exit.)
+
+
+Dump statistic information periodically.
+========================================
+
+
+The user can use "--stat_freq=" or "-S" to specify the frequency.
+
+For example:
+
+--stat_freq=20s
+
+Memslap will dump the statistics of the commands (get and set) at the frequency of every 20
+seconds.
+
+For more information on the format of dumping statistic information, refer to “Format of Output” section.
+
+
+Multi-get
+=========
+
+
+The user can use "--division=" or "-d" to specify multi-get keys count.
+Memslap by default does single get with TCP. Memslap also supports data 
+verification and expire-time verification for multi-get.
+
+Memslap supports multi-get with both TCP and UDP. Because of
+the different implementation of the ASCII protocol and binary protocol,
+there are some differences between the two. For the ASCII protocol,
+memslap sends one “multi-get” to the server once. For the
+binary protocol, memslap sends several single get commands
+together as “multi-get” to the server.
+
+
+UDP and TCP
+===========
+
+
+Memslap supports both UDP and TCP. For TCP,
+memslap does not reconnect the memcached server if socket connections are
+lost. If all the socket connections are lost or memcached server crashes,
+memslap will exit. If the user specifies the “--reconnect”
+option when socket connections are lost, it will reconnect them.
+
+User can use “--udp” to enable the UDP feature, but UDP comes with some
+limitations:
+
+UDP cannot set data more than 1400 bytes.
+
+UDP is not supported by the binary protocol because the binary protocol of
+memcached does not support that.
+
+UDP doesn’t support reconnection.
+
+
+Facebook test
+=============
+
+
+Set data with TCP and multi-get with UDP. Specify the following options:
+
+"--facebook --division=50"
+
+If you want to create thousands of TCP connections, specify the
+
+"--conn_sock=" option.
+
+For example: --facebook --division=50 --conn_sock=200
+
+The above command means that memslap will do facebook test,
+each concurrency has 200 socket TCP connections and one UDP socket.
+
+Memslap sets objects with the TCP socket, and multi-gets 50
+objects once with the UDP socket.
+
+If you specify "--division=50", the key size must be less that 25 bytes
+because the UDP packet size is 1400 bytes.
+
+
+Replication test
+================
+
+
+For replication test, the user must specify at least two memcached servers.
+The user can use “—rep_write=” option to enable feature.
+
+For example:
+
+--servers=10.1.1.1:11211,10.1.1.2:11212 –rep_write=2
+
+The above command means that there are 2 replication memcached servers,
+memslap will set objects to both server 0 and server 1, get
+objects which are set to server 0 before from server 1, and also get objects
+which are set to server 1 before from server 0. If server 0 crashes,
+memslap will only get objects from server 1. If server 0 comes
+back to life again, memslap will reconnect server 0. If both
+server 0 and server 1 crash, memslap will exit.
+
+
+Supports thousands of TCP connections
+=====================================
+
+
+Start memslap with "--conn_sock=" or "-n" to enable this
+feature. Make sure that your system can support opening thousands of files
+and creating thousands of sockets. However, this feature does not support
+reconnection if sockets disconnect.
+
+For example:
+
+--threads=8 --concurrency=128 --conn_sock=128
+
+The above command means that memslap starts up 8 threads, each
+thread has 16 concurrencies, each concurrency has 128 TCP socket
+connections, and the total number of TCP socket connections is 128 \* 128 =
+16384.
+
+
+Supports binary protocol
+========================
+
+
+Start memslap with "--binary" or "-B" options to enable this
+feature. It supports all the above features except UDP, because the latest
+memcached 1.3.3 does not implement binary UDP protocol.
+
+For example:
+
+--binary
+
+Since memcached 1.3.3 doesn't implement binary UDP protocol,
+memslap does not support UDP. In addition, memcached 1.3.3 does not support
+multi-get. If you specify "--division=50" option, it just sends 50 get
+commands together as “mulit-get” to the server.
+
+
+
+******************
+Configuration file
+******************
+
+
+This section describes the format of the configuration file.  By default
+when no configuration file is specified memslap reads the default
+one located at ~/.memslap.cnf.
+
+Below is a sample configuration file:
+
+
+.. code-block:: perl
+
+  ***************************************************************************
+  #comments should start with '#'
+  #key 
+  #start_len end_len proportion
+  #
+  #key length range from start_len to end_len
+  #start_len must be equal to or greater than 16
+  #end_len must be equal to or less than 250
+  #start_len must be equal to or greater than end_len
+  #memslap will generate keys according to the key range
+  #proportion: indicates keys generated from one range accounts for the total
+  generated keys  
+  #
+  #example1: key range 16~100 accounts for 80%
+  #          key range 101~200 accounts for 10%
+  #          key range 201~250 accounts for 10%
+  #          total should be 1 (0.8+0.1+0.1 = 1)
+  #
+  #          16 100 0.8  
+  #          101 200 0.1
+  #          201 249 0.1
+  #
+  #example2: all keys length are 128 bytes
+  #
+  #          128 128 1 
+  key
+  128 128 1  
+  #value 
+  #start_len end_len proportion
+  #
+  #value length range from start_len to end_len
+  #start_len must be equal to or greater than 1
+  #end_len must be equal to or less than 1M
+  #start_len must be equal to or greater than end_len
+  #memslap will generate values according to the value range
+  #proportion: indicates values generated from one range accounts for the
+  total generated values  
+  #
+  #example1: value range 1~1000 accounts for 80%
+  #          value range 1001~10000 accounts for 10%
+  #          value range 10001~100000 accounts for 10%
+  #          total should be 1 (0.8+0.1+0.1 = 1)
+  #
+  #          1 1000 0.8  
+  #          1001 10000 0.1
+  #          10001 100000 0.1
+  #
+  #example2: all value length are 128 bytes
+  #
+  #          128 128 1 
+  value
+  2048 2048 1
+  #cmd
+  #cmd_type cmd_proportion
+  #
+  #currently memslap only supports get and set command.
+  #
+  #cmd_type
+  #set     0
+  #get     1
+  #
+  #example: set command accounts for 50%
+  #         get command accounts for 50%
+  #         total should be 1 (0.5+0.5 = 1)
+  #
+  #         cmd
+  #         0    0.5
+  #         1    0.5
+  cmd
+  0    0.1
+  1.0 0.9
+
+
+
+****************
+Format of output
+****************
+
+
+At the beginning, memslap displays some configuration information as follows:
+
+
+servers : 127.0.0.1:11211
+
+
+
+threads count: 1
+
+
+
+concurrency: 16
+
+
+
+run time: 20s
+
+
+
+windows size: 10k
+
+
+
+set proportion: set_prop=0.10
+
+
+
+get proportion: get_prop=0.90
+
+
+
+Where
+=====
+
+
+
+servers : "servers"
+ The servers used by memslap.
+
+
+threads count
+ The number of threads memslap runs with.
+
+
+concurrency
+ The number of concurrencies memslap runs with.
+
+
+run time
+ How long to run memslap.
+
+
+windows size
+ The task window size of each concurrency.
+
+
+set proportion
+ The proportion of set command.
+
+
+get proportion
+ The proportion of get command.
+
+
+The output of dynamic statistics is something like this:
+
+
+.. code-block:: perl
+
+  ---------------------------------------------------------------------------------------------------------------------------------
+  Get Statistics
+  Type  Time(s)  Ops   TPS(ops/s)  Net(M/s)  Get_miss  Min(us)  Max(us)
+  Avg(us)  Std_dev    Geo_dist  
+  Period   5   345826  69165     65.3      0         27      2198     203
+  95.43      177.29
+  Global  20  1257935  62896     71.8      0         26      3791     224
+  117.79     192.60
+  
+   
+  Set Statistics
+  Type  Time(s)  Ops   TPS(ops/s)  Net(M/s)  Get_miss  Min(us)  Max(us)
+  Avg(us)  Std_dev    Geo_dist  
+  Period   5    38425   7685      7.3       0         42      628     240
+  88.05      220.21
+  Global   20   139780  6989      8.0       0         37      3790    253
+  117.93     224.83
+  
+   
+  Total Statistics
+  Type  Time(s)  Ops   TPS(ops/s)  Net(M/s)  Get_miss  Min(us)  Max(us)
+  Avg(us)  Std_dev    Geo_dist 
+  Period   5   384252   76850     72.5      0        27      2198     207
+  94.72      181.18
+  Global  20  1397720   69886     79.7      0        26      3791     227
+  117.93     195.60
+  ---------------------------------------------------------------------------------------------------------------------------------
+
+
+
+Where
+=====
+
+
+
+Get Statistics
+ Statistics information of get command
+
+
+Set Statistics
+ Statistics information of set command
+
+
+Total Statistics
+ Statistics information of both get and set command
+
+
+Period
+ Result within a period
+
+
+Global
+ Accumulated results
+
+
+Ops
+ Total operations
+
+
+TPS
+ Throughput, operations/second
+
+
+Net
+ The rate of network
+
+
+Get_miss
+ How many objects can’t be gotten
+
+
+Min
+ The minimum response time
+
+
+Max
+ The maximum response time
+
+
+Avg:
+ The average response time
+
+
+Std_dev
+ Standard deviation of response time
+
+
+Geo_dist
+ Geometric distribution based on natural exponential function
+
+
+At the end, memslap will output something like this:
+
+
+.. code-block:: perl
+
+   ---------------------------------------------------------------------------------------------------------------------------------
+   Get Statistics (1257956 events)
+     Min:        26
+     Max:      3791
+     Avg:       224
+     Geo:    192.60
+     Std:    116.23
+                     Log2 Dist:
+                       4:        0       10    84490   215345
+                       8:   484890   459823    12543      824
+                      12:       31
+    Set Statistics (139782 events)
+       Min:        37
+       Max:      3790
+       Avg:       253
+       Geo:    224.84
+       Std:    116.83
+       Log2 Dist: 
+         4:        0        0     4200 16988
+         8:    50784    65574 2064      167
+         12:        5
+    
+     Total Statistics (1397738 events)
+         Min:        26
+         Max:      3791
+         Avg:       227
+         Geo:    195.60
+         Std:    116.60
+         Log2 Dist:
+           4:        0       10    88690   232333
+           8:   535674   525397    14607      991
+           12:       36
+   cmd_get: 1257969
+   cmd_set: 139785
+   get_misses: 0
+   verify_misses: 0
+   verify_failed: 0
+   expired_get: 0
+   unexpired_unget: 0
+   written_bytes: 242516030
+   read_bytes: 1003702556
+   object_bytes: 152086080
+   packet_disorder: 0
+   packet_drop: 0
+   udp_timeout: 0
+   Run time: 20.0s Ops: 1397754 TPS: 69817 Net_rate: 59.4M/s
+   ---------------------------------------------------------------------------------------------------------------------------------
+
+
+
+Where
+=====
+
+
+
+Get Statistics
+ Get statistics of response time
+
+
+Set Statistics
+ Set statistics of response time
+
+
+Total Statistics
+ Both get and set statistics of response time
+
+
+Min
+ The accumulated and minimum response time
+
+
+Max
+ The accumulated and maximum response time
+
+
+Avg
+ The accumulated and average response time
+
+
+Std
+ Standard deviation of response time
+
+
+Log2 Dist
+ Geometric distribution based on logarithm 2
+
+
+cmd_get
+ Total get commands done
+
+
+cmd_set
+ Total set commands done
+
+
+get_misses
+ How many objects can’t be gotten from server
+
+
+verify_misses
+ How many objects need to verify but can’t get them
+
+
+verify_failed
+ How many objects with insistent value
+
+
+expired_get
+ How many objects are expired but we get them
+
+
+unexpired_unget
+ How many objects are unexpired but we can’t get them
+
+
+written_bytes
+ Total written bytes
+
+
+read_bytes
+ Total read bytes
+
+
+object_bytes
+ Total object bytes
+
+
+packet_disorder
+ How many UDP packages are disorder
+
+
+packet_drop
+ How many UDP packages are lost
+
+
+udp_timeout
+ How many times UDP time out happen
+
+
+Run time
+ Total run time
+
+
+Ops
+ Total operations
+
+
+TPS
+ Throughput, operations/second
+
+
+Net_rate
+ The average rate of network
+
+
+
+
+*******
+OPTIONS
+*******
+
+
+-s, --servers=
+    List one or more servers to connect. Servers count must be less than
+    threads count. e.g.: --servers=localhost:1234,localhost:11211
+
+-T, --threads=
+    Number of threads to startup, better equal to CPU numbers. Default 8.
+
+-c, --concurrency=
+    Number of concurrency to simulate with load. Default 128.
+
+-n, --conn_sock=
+    Number of TCP socks per concurrency. Default 1.
+
+-x, --execute_number=
+    Number of operations(get and set) to execute for the
+    given test. Default 1000000.
+
+-t, --time=
+    How long the test to run, suffix: s-seconds, m-minutes, h-hours,
+    d-days e.g.: --time=2h.
+
+-F, --cfg_cmd=
+    Load the configure file to get command,key and value distribution list.
+
+-w, --win_size=
+    Task window size of each concurrency, suffix: K, M e.g.: --win_size=10k.
+    Default 10k.
+
+-X, --fixed_size=
+    Fixed length of value.
+
+-v, --verify=
+    The proportion of date verification, e.g.: --verify=0.01
+
+-d, --division=
+    Number of keys to multi-get once. Default 1, means single get.
+
+-S, --stat_freq=
+    Frequency of dumping statistic information. suffix: s-seconds,
+    m-minutes, e.g.: --resp_freq=10s.
+
+-e, --exp_verify=
+    The proportion of objects with expire time, e.g.: --exp_verify=0.01.
+    Default no object with expire time
+
+-o, --overwrite=
+    The proportion of objects need overwrite, e.g.: --overwrite=0.01.
+    Default never overwrite object.
+
+-R, --reconnect 
+    Reconnect support, when connection is closed it will be reconnected.
+
+-U, --udp 
+    UDP support, default memslap uses TCP, TCP port and UDP port of
+    server must be same.
+
+-a, --facebook 
+    Whether it enables facebook test feature, set with TCP and multi-get with UDP.
+
+-B, --binary 
+    Whether it enables binary protocol. Default with ASCII protocol.
+
+-P, --tps=
+    Expected throughput, suffix: K, e.g.: --tps=10k.
+
+-p, --rep_write=
+    The first nth servers can write data, e.g.: --rep_write=2.
+
+-b, --verbose 
+    Whether it outputs detailed information when verification fails.
+
+-h, --help 
+    Display this message and then exit.
+
+-V, --version 
+    Display the version of the application and then exit.
+
+
+********
+EXAMPLES
+********
+
+
+memslap -s 127.0.0.1:11211 -S 5s
+
+memslap -s 127.0.0.1:11211 -t 2m -v 0.2 -e 0.05 -b
+
+memslap -s 127.0.0.1:11211 -F config -t 2m -w 40k -S 20s -o 0.2
+
+memslap -s 127.0.0.1:11211 -F config -t 2m -T 4 -c 128 -d 20 -P 40k
+
+memslap -s 127.0.0.1:11211 -F config -t 2m -d 50 -a -n 40
+
+memslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m
+
+memslap -s 127.0.0.1:11211,127.0.0.1:11212 -F config -t 2m -p 2
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`http://launchpad.org/libmemcached <http://launchpad.org/libmemcached>`_
+
+
+*******
+AUTHORS
+*******
+
+
+Mingqiang Zhuang <mingqiangzhuang@hengtiansoft.com> (Schooner Technolgy)
+Brian Aker, <brian@tangent.org>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/docs/memstat.pod b/docs/memstat.pod
deleted file mode 100644 (file)
index a1079cc..0000000
+++ /dev/null
@@ -1,37 +0,0 @@
-=head1 NAME
-
-memstat - Display the operating status of a single or group of memcached servers
-
-=head1 SYNOPSIS
-
-  memstat [options]
-
-=head1 DESCRIPTION
-
-B<memstat> dumps the state of memcached(1) servers.
-It displays all data to stdout.
-
-You can specify servers via the B<--servers> option or via the
-environment variable C<MEMCACHED_SERVERS>. B<--args> can be used
-to specify the "argument" sent to the stats command (ie slab, size, items,
-etc..).
-
-For a full list of operations run the tool with the B<--help> option.
-
-=head1 HOME
-
-To find out more information please check:
-L<http://launchpad.org/libmemcached>
-
-=head1 AUTHOR
-
-Brian Aker, E<lt>brian@tangent.orgE<gt>
-
-Mark Atwood, E<lt>mark@fallenpegasus.comE<gt>
-
-=head1 SEE ALSO
-
-memcached(1) libmemcached(3)
-
-=cut
-
diff --git a/docs/memstat.rst b/docs/memstat.rst
new file mode 100644 (file)
index 0000000..8422943
--- /dev/null
@@ -0,0 +1,65 @@
+.. highlight:: perl
+
+
+****
+NAME
+****
+
+
+memstat - Display the operating status of a single or group of memcached servers
+
+
+********
+SYNOPSIS
+********
+
+
+
+.. code-block:: perl
+
+   memstat [options]
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+\ **memstat**\  dumps the state of memcached(1) servers.
+It displays all data to stdout.
+
+You can specify servers via the \ **--servers**\  option or via the
+environment variable \ ``MEMCACHED_SERVERS``\ . \ **--args**\  can be used
+to specify the "argument" sent to the stats command (ie slab, size, items,
+etc..).
+
+For a full list of operations run the tool with the \ **--help**\  option.
+
+
+****
+HOME
+****
+
+
+To find out more information please check:
+`http://launchpad.org/libmemcached <http://launchpad.org/libmemcached>`_
+
+
+******
+AUTHOR
+******
+
+
+Brian Aker, <brian@tangent.org>
+
+Mark Atwood, <mark@fallenpegasus.com>
+
+
+********
+SEE ALSO
+********
+
+
+memcached(1) libmemcached(3)
+
diff --git a/m4/pod2man.m4 b/m4/pod2man.m4
deleted file mode 100644 (file)
index 2658998..0000000
+++ /dev/null
@@ -1,7 +0,0 @@
-AC_DEFUN([REQUIRE_POD2MAN],[
-  AC_PATH_PROG([POD2MAN], [pod2man],
-    "no", [$PATH:/usr/bin:/usr/local/bin:/usr/perl5/bin])
-  AS_IF([test "x$POD2MAN" = "xno"],
-    AC_MSG_ERROR(["Could not find pod2man anywhere in path"]))
-  AC_SUBST(POD2MAN)
-])
diff --git a/m4/podchecker.m4 b/m4/podchecker.m4
deleted file mode 100644 (file)
index ae10a6b..0000000
+++ /dev/null
@@ -1,7 +0,0 @@
-AC_DEFUN([REQUIRE_PODCHECKER],[
-  AC_PATH_PROG([PODCHECKER], [podchecker],
-    "no", [$PATH:/usr/bin:/usr/local/bin:/usr/perl5/bin])
-  AS_IF([test "x$PODCHECKER" = "xno"],
-    AC_MSG_ERROR(["Could not find podchecker anywhere in path"]))
-  AC_SUBST(PODCHECKER)
-])