X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Fsource%2Flibmemcached.rst;h=f630a391fc8456e2746df90053ef5c28e4332886;hb=77fc9c3ba95eb502d1a66146251acfcfd5606df8;hp=af5ef416a7629b0008c8a6fdc0b602ee7516a30e;hpb=f2a59b728c20f7fe78874dd41187ab3fb2db6c7e;p=awesomized%2Flibmemcached diff --git a/docs/source/libmemcached.rst b/docs/source/libmemcached.rst index af5ef416..f630a391 100644 --- a/docs/source/libmemcached.rst +++ b/docs/source/libmemcached.rst @@ -1,20 +1,20 @@ -============================================== -Introducing the C Client Library for memcached -============================================== +C/C++ Client Library for memcached +================================== --------- SYNOPSIS -------- #include - -Compile and link with -lmemcached + Compile and link with -lmemcached ======= -libMemcached is an open source C/C++ client library and tools for the memcached server (http://memcached.org/). It has been designed to be light on memory usage, thread safe, and provide full access to server side methods. +`libmemcached` is an open source C/C++ client library and tools for the +memcached server (http://memcached.org/). It has been designed to be light on +memory usage, thread safe, and provide full access to server side methods. -libMemcached was designed to provide the greatest number of options to use Memcached. Some of the features provided: +`libmemcached` was designed to provide the greatest number of options to use +Memcached. Some of the features provided: 1. Asynchronous and Synchronous Transport Support. 2. Consistent Hashing and Distribution. @@ -24,162 +24,161 @@ libMemcached was designed to provide the greatest number of options to use Memca 6. A complete reference guide and documentation to the API. 7. Tools to Manage your Memcached networks. ------------ 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://memcached.org/ `_ -"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://memcached.org/ `_ - -:program:`libmemcached` is a small, thread-safe client library for the -memcached protocol. The code has all been written to allow -for both web and embedded usage. It handles the work behind routing -individual keys to specific servers specified by the developer (and values are -matched based on server order as supplied by the user). It implements -a modular and consistent method of object distribution. +`libmemcached` is a small, thread-safe client library for the memcached +protocol. The code has all been written to allow for both web and embedded +usage. It handles the work behind routing individual keys to specific servers +specified by the developer (and values are matched based on server order as +supplied by the user). It implements a modular and consistent method of object +distribution. There are multiple implemented routing and hashing methods. See the -:c:func:`memcached_behavior_set` manpage for more information. - -All operations are performed against a :c:type:`memcached_st` structure. -These structures can either be dynamically allocated or statically -allocated and then initialized by :c:func:`memcached_create`. Functions have -been written in order to encapsulate the :c:type:`memcached_st`. It is not -recommended that you operate directly against the structure. - -Nearly all functions return a :c:type:`memcached_return_t` value. -This value can be translated to a printable string with -:c:type:`memcached_strerror`. +`memcached_behavior_set` manpage for more information. -Objects are stored on servers by hashing keys. The hash value maps the key to a particular server. All clients understand how this hashing works, so it is possibly to reliably both push data to a server and retrieve data from a server. +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. -Group keys can be optionally used to group sets of objects with servers. +Nearly all functions return a `memcached_return_t` value. This value can be +translated to a printable string with `memcached_strerror`. -Namespaces are supported, and can be used to partition caches so that multiple applications can use the same memcached servers. +Objects are stored on servers by hashing keys. The hash value maps the key to a +particular server. All clients understand how this hashing works, so it is +possibly to reliably both push data to a server and retrieve data from a server. -:c:type:`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. +Group keys can be optionally used to group sets of objects with servers. -If you are working with GNU autotools you will want to add the following to -your COPYING to properly include libmemcached in your application. +Namespaces are supported, and can be used to partition caches so that multiple +applications can use the same memcached servers. -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`. -Some features of the library must be enabled through :c:func:`memcached_behavior_set`. +THREADS AND PROCESSES +--------------------- -Hope you enjoy it! +No global variables are used in this library. +`memcached_st` structures are thread-safe, but when using threads or forked +processes it is important to keep one instance of `memcached_st` per process or +thread. Without creating your own locking structures you can not share a single +`memcached_st`. However, you can call `memcached_quit` on a `memcached_st` and +then use the resulting cloned structure. ---------- -CONSTANTS +SYSTEMTAP --------- +`libmemcached` can be built to support Systemtap on Linux when enabled at +compile time. -A number of constants have been provided for in the library. +Please see :manpage:`stap(1)` and :manpage:`dtrace(1)` for more information +about Systemtap. +CLIENT PROGRAMS +--------------- -.. c:macro:: MEMCACHED_DEFAULT_PORT - - The default port used by memcached(3). - +`libmemcached` comes with a few useful client programs: -.. c:macro:: 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. - +.. only:: man -.. c:macro:: MEMCACHED_MAX_KEY - - Default size of key (which includes the null pointer). - + :manpage:`memaslap(1)` + :manpage:`memcapable(1)` + :manpage:`memcat(1)` + :manpage:`memcp(1)` + :manpage:`memdump(1)` + :manpage:`memerror(1)` + :manpage:`memexist(1)` + :manpage:`memflush(1)` + :manpage:`memparse(1)` + :manpage:`memping(1)` + :manpage:`memrm(1)` + :manpage:`memslap(1)` + :manpage:`memstat(1)` + :manpage:`memtouch(1)` -.. c:macro:: MEMCACHED_STRIDE - - This is the "stride" used in the consistent hash used between replicas. - +.. only:: html -.. c:macro:: MEMCACHED_MAX_HOST_LENGTH - - Maximum allowed size of the hostname. - + * :doc:`bin/memaslap` + * :doc:`bin/memcapable` + * :doc:`bin/memcat` + * :doc:`bin/memcp` + * :doc:`bin/memdump` + * :doc:`bin/memerror` + * :doc:`bin/memexist` + * :doc:`bin/memflush` + * :doc:`bin/memparse` + * :doc:`bin/memping` + * :doc:`bin/memrm` + * :doc:`bin/memslap` + * :doc:`bin/memstat` + * :doc:`bin/memtouch` -.. c:macro:: LIBMEMCACHED_VERSION_STRING - - String value of libmemcached version such as "1.23.4" +UTILITY LIBRARIES +----------------- +.. only:: man -.. c:macro:: LIBMEMCACHED_VERSION_HEX - - Hex value of the version number. "0x00048000" This can be used for comparing versions based on number. - + :manpage:`libhashkit(3)` + :manpage:`libmemcachedutil(3)` -.. c:macro:: MEMCACHED_PREFIX_KEY_MAX_SIZE +.. only:: html - Maximum length allowed for namespacing of a key. + * :doc:`libhashkit/index` + * :doc:`libmemcachedutil/index` - - ---------------------- -THREADS AND PROCESSES ---------------------- - - -When using threads or forked processes it is important to keep one instance -of :c:type:`memcached_st` per process or thread. Without creating your own -locking structures you can not share a single :c:type:`memcached_st`. However, -you can call :c:func:`memcached_quit` on a :c:type:`memcached_st` and then use the resulting cloned structure. - - ----- -HOME ----- - - -To find out more information please check: -`http://libmemcached.org/ `_ - - --------- SEE ALSO -------- +.. only:: man + + :manpage:`memcached(1)` + :manpage:`libmemcached_configuration(3)` + :manpage:`libmemcached_examples(3)` + + :manpage:`memcached_analyze(3)` + :manpage:`memcached_append(3)` + :manpage:`memcached_auto(3)` + :manpage:`memcached_behavior(3)` + :manpage:`memcached_callback(3)` + :manpage:`memcached_cas(3)` + :manpage:`memcached_create(3)` + :manpage:`memcached_delete(3)` + :manpage:`memcached_dump(3)` + :manpage:`memcached_exist(3)` + :manpage:`memcached_fetch(3)` + :manpage:`memcached_flush(3)` + :manpage:`memcached_flush_buffers(3)` + :manpage:`memcached_generate_hash_value(3)` + :manpage:`memcached_get(3)` + :manpage:`memcached_last_error_message(3)` + :manpage:`memcached_memory_allocators(3)` + :manpage:`memcached_pool(3)` + :manpage:`memcached_quit(3)` + :manpage:`memcached_result_st(3)` + :manpage:`memcached_return_t(3)` + :manpage:`memcached_sasl(3)` + :manpage:`memcached_servers(3)` + :manpage:`memcached_server_st(3)` + :manpage:`memcached_set(3)` + :manpage:`memcached_set_encoding_key(3)` + :manpage:`memcached_stats(3)` + :manpage:`memcached_strerror(3)` + :manpage:`memcached_touch(3)` + :manpage:`memcached_user_data(3)` + :manpage:`memcached_verbosity(3)` + :manpage:`memcached_version(3)` + +.. only:: html + + * :manpage:`memcached(1)` + + * :doc:`libmemcached/configuration` + * :doc:`libmemcached/examples` -:manpage:`memcached(1)` :manpage:`libmemcached_examples(3)` -:manpage:`libmemcached(1)` :manpage:`memcat(1)` :manpage:`memcp(1)` -:manpage:`memflush(1)` :manpage:`memrm(1)` :manpage:`memslap(1)` -:manpage:`memstat(1)` :manpage:`memcached_fetch(3)` -:manpage:`memcached_replace(3)` :manpage:`memcached_server_list_free(3)` -:manpage:`libmemcached_examples(3)` :manpage:`memcached_clone(3)` -:manpage:`memcached_free(3)` :manpage:`memcached_server_add(3)` -:manpage:`memcached_server_push(3)` :manpage:`memcached_add(3)` -:manpage:`memcached_get(3)` :manpage:`memcached_server_count(3)` -:manpage:`memcached_create(3)` :manpage:`memcached_increment(3)` -:manpage:`memcached_server_list(3)` :manpage:`memcached_set(3)` -:manpage:`memcached_decrement(3)` :manpage:`memcached_mget(3)` -:manpage:`memcached_server_list_append(3)` :manpage:`memcached_strerror(3)` -:manpage:`memcached_delete(3)` :manpage:`memcached_quit(3)` -:manpage:`memcached_server_list_count(3)` :manpage:`memcached_verbosity(3)` -:manpage:`memcached_server_add_unix_socket(3)` -:manpage:`memcached_result_create(3)` :manpage:`memcached_result_free(3)` -:manpage:`memcached_result_key_value(3)` -:manpage:`memcached_result_key_length(3)` -:manpage:`memcached_result_value(3)` :manpage:`memcached_result_length(3)` -:manpage:`memcached_result_flags(3)` :manpage:`memcached_result_cas(3)` -:manpage:`memcached_result_st(3)` :manpage:`memcached_append(3)` -:manpage:`memcached_prepend(3)` :manpage:`memcached_fetch_result(3)` -:manpage:`memerror(1)` :manpage:`memcached_get_by_key(3)` -:manpage:`memcached_mget_by_key(3)` :manpage:`memcached_delete_by_key(3)` -:manpage:`memcached_fetch_execute(3)` :manpage:`memcached_callback_get(3)` -:manpage:`memcached_callback_set(3)` :manpage:`memcached_version(3)` -:manpage:`memcached_lib_version(3)` :manpage:`memcached_result_set_value(3)` -:manpage:`memcached_dump(3)` :manpage:`memdump(1)` -:manpage:`memcached_set_memory_allocators(3)` -:manpage:`memcached_get_memory_allocators(3)` -:manpage:`memcached_get_user_data(3)` :manpage:`memcached_set_user_data(3)`