X-Git-Url: https://git.m6w6.name/?a=blobdiff_plain;f=docs%2Fmemcached_result_st.rst;h=9b60f1872fe908bfba56c7bad1d3b0acf16147ca;hb=1adc67d1609fd71308b822e153dcb08ad7fbf9c2;hp=058b743f7eb7496986854a8bb1e12df338710e70;hpb=281c398ba3a10af677494c4453cd09d85ca921e0;p=awesomized%2Flibmemcached diff --git a/docs/memcached_result_st.rst b/docs/memcached_result_st.rst index 058b743f..9b60f187 100644 --- a/docs/memcached_result_st.rst +++ b/docs/memcached_result_st.rst @@ -2,53 +2,39 @@ Working with result sets ======================== +-------- +SYNOPSIS +-------- -Work with memcached_result_st +#include +.. c:type:: memcached_result_st -******* -LIBRARY -******* +.. c:function:: memcached_result_st * memcached_result_create (memcached_st *ptr, memcached_result_st *result) +.. c:function:: void memcached_result_free (memcached_result_st *result) -C Client Library for memcached (libmemcached, -lmemcached) +.. c:function:: const char * memcached_result_key_value (memcached_result_st *result) +.. c:function:: size_t memcached_result_key_length (const memcached_result_st *result) --------- -SYNOPSIS --------- +.. c:function:: const char *memcached_result_value (memcached_result_st *ptr) + +.. c:function:: char *memcached_result_take_value (memcached_result_st *ptr) + +.. c:function:: size_t memcached_result_length (const memcached_result_st *ptr) + +.. c:function:: uint32_t memcached_result_flags (const memcached_result_st *result) +.. c:function:: uint64_t memcached_result_cas (const memcached_result_st *result) +.. c:function:: memcached_return_t memcached_result_set_value (memcached_result_st *ptr, const char *value, size_t length) -.. code-block:: perl - - #include - - 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) +.. c:function:: void memcached_result_set_flags (memcached_result_st *ptr, uint32_t flags) + +.. c:function:: void memcached_result_set_expiration (memcached_result_st *ptr, time_t) + +Compile and link with -lmemcachedutil -lmemcached @@ -57,49 +43,54 @@ 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. +libmemcached(3) can optionally return a :c:type:`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. +The structure of :c:type:`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. +:c:func:`memcached_result_create` will either allocate memory for a +:c:type:`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. +:c:func:`memcached_result_free` will deallocate any memory attached to the +structure. If the structure was also allocated, it will deallocate it. -memcached_result_key_value() returns the key value associated with the +:c:func:`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. +:c:func:`memcached_result_key_length` returns the key length associated with +the current result object. -memcached_result_value() returns the result value associated with the +:c:func:`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. +:c:func:`memcached_result_take_value` returns and hands over the result value +associated with the current result object. You must call free() to release this +value, unless you have made use of a custom allocator. Use of a custom +allocator requires that you create your own custom free() to release it. + +:c:func:`memcached_result_length` returns the result length associated with +the current result object. -memcached_result_flags() returns the flags associated with the +:c:func:`memcached_result_flags` returns the flags associated with the current result object. -memcached_result_cas() returns the cas associated with the +:c:func:`memcached_result_cas` returns the cas associated with the current result object. This value will only be available if the server -testss it. +tests it. -memcached_result_set_value() takes a byte array and a size and sets +:c:func:`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. +:c:func:`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 +:c:func:`memcached_result_set_expiration` takes a result structure and stores a new value for the expiration field (this is only used by read through triggers). @@ -108,31 +99,23 @@ 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. +:c:func:`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 `_ - - -****** -AUTHOR -****** - - -Brian Aker, +`http://libmemcached.org/ `_ --------