1MEMCACHED_MGET_EXECUTE(3)        libmemcached        MEMCACHED_MGET_EXECUTE(3)
2
3
4

NAME

6       memcached_mget_execute - Retrieving data from the server
7

SYNOPSIS

9       #include <libmemcached/memcached.h>
10
11       memcached_result_st  *  memcached_fetch_result(memcached_st *ptr,  mem‐
12       cached_result_st *result, memcached_return_t *error)
13
14       char    *     memcached_get(memcached_st *ptr,     const     char *key,
15       size_t key_length,    size_t *value_length,    uint32_t *flags,    mem‐
16       cached_return_t *error)
17
18       memcached_return_t  memcached_mget(memcached_st *ptr,  const   char   *
19       const *keys, const size_t *key_length, size_t number_of_keys)
20
21       char  *  memcached_get_by_key(memcached_st *ptr, const char *group_key,
22       size_t group_key_length,    const     char *key,     size_t key_length,
23       size_t *value_length, uint32_t *flags, memcached_return_t *error)
24
25       memcached_return_t    memcached_mget_by_key(memcached_st *ptr,    const
26       char *group_key, size_t group_key_length,  const  char  *  const *keys,
27       const size_t *key_length, size_t number_of_keys)
28
29       memcached_return_t           memcached_fetch_execute(memcached_st *ptr,
30       memcached_execute_fn *callback, void *context, uint32_t number_of_call‐
31       backs)
32
33       memcached_return_t memcached_mget_execute(memcached_st *ptr, const char
34       *   const *keys,   const   size_t *key_length,   size_t number_of_keys,
35       memcached_execute_fn *callback, void *context, uint32_t number_of_call‐
36       backs)
37
38       memcached_return_t     memcached_mget_execute_by_key(memcached_st *ptr,
39       const    char *group_key,   size_t group_key_length,   const   char   *
40       const *keys,    const    size_t *key_length,     size_t number_of_keys,
41       memcached_execute_fn *callback, void *context, uint32_t number_of_call‐
42       backs)
43
44       memcached_return_t   (*memcached_execute_fn)(const   memcached_st *ptr,
45       memcached_result_st *result, void *context)
46
47       Compile and link with -lmemcached
48

DESCRIPTION

50       memcached_get()  is  used to fetch an individual value from the server.
51       You must pass in a key and its length to fetch  the  object.  You  must
52       supply  three  pointer  variables  which will give you the state of the
53       returned object.  A uint32_t pointer  to  contain  whatever  flags  you
54       stored  with the value, a size_t pointer which will be filled with size
55       of of the object, and a memcached_return_t pointer to hold  any  error.
56       The  object  will be returned upon success and NULL will be returned on
57       failure. Any object returned by memcached_get() must be released by the
58       caller application.
59
60       memcached_mget()  is used to select multiple keys at once. For multiple
61       key operations it is always faster to use this function. This  function
62       always works asynchronously.
63
64       To  retrieve data after a successful execution of memcached_mget(), you
65       will need to call memcached_fetch_result().   You  should  continue  to
66       call  this  function  until it returns a NULL (i.e. no more values). If
67       you need to quit in the middle of a memcached_mget() call, you can exe‐
68       cute a memcached_quit(), those this is not required.
69
70       memcached_fetch_result()  is used to fetch an individual value from the
71       server. memcached_mget()  must  always  be  called  before  using  this
72       method.  You must pass in a key and its length to fetch the object. You
73       must supply three pointer variables which will give you  the  state  of
74       the  returned object.  A uint32_t pointer to contain whatever flags you
75       stored with the value, a size_t pointer which will be filled with  size
76       of  of  the object, and a memcached_return_t pointer to hold any error.
77       The object will be returned upon success and NULL will be  returned  on
78       failure. MEMCACHED_END is returned by the *error value when all objects
79       that have been found are returned. The final value  upon  MEMCACHED_END
80       is null.
81
82       memcached_fetch_result() is used to return a memcached_result_st struc‐
83       ture from a memcached server. The result object is  forward  compatible
84       with  changes  to  the server. For more information please refer to the
85       memcached_result_st help. This function  will  dynamically  allocate  a
86       result structure for you if you do not pass one to the function.
87
88       memcached_fetch_execute()  is  a  callback  function  for  result sets.
89       Instead of returning the results to you for processing, it passes  each
90       of  the  result sets to the list of functions you provide. It passes to
91       the function a memcached_st that can be cloned for use  in  the  called
92       function  (it  can  not  be used directly). It also passes a result set
93       which does not need to be freed. Finally it passes a "context". This is
94       just  a  pointer to a memory reference you supply the calling function.
95       Currently only one value is being passed to each function call. In  the
96       future there will be an option to allow this to be an array.
97
98       memcached_mget_execute() and memcached_mget_execute_by_key() is similar
99       to memcached_mget(), but it may trigger  the  supplied  callbacks  with
100       result  sets  while  sending  out  the queries. If you try to perform a
101       really large multiget with memcached_mget() you may encounter  a  dead‐
102       lock in the OS kernel (it will fail to write data to the socket because
103       the input buffer is full). memcached_mget_execute() solves this problem
104       by  processing  some  of  the  results  before  continuing  sending out
105       requests. Please note that this  function  is  only  available  in  the
106       binary protocol.
107
108       memcached_get_by_key()  and memcached_mget_by_key() behave in a similar
109       nature as memcached_get() and memcached_mget().  The difference is that
110       they  take  a  master  key that is used for determining which server an
111       object was stored if key partitioning was used for storage.
112
113       All of the above functions are not  tested  when  the  MEMCACHED_BEHAV‐
114       IOR_USE_UDP  has  been  set. Executing any of these functions with this
115       behavior on will result in MEMCACHED_NOT_SUPPORTED being  returned,  or
116       for those functions which do not return a memcached_return_t, the error
117       function parameter will be set to MEMCACHED_NOT_SUPPORTED.
118

RETURN

120       All objects retrieved  via  memcached_get()  or  memcached_get_by_key()
121       must be freed with free(3).
122
123       memcached_get()  will  return NULL on error. You must look at the value
124       of error to determine what the actual error was.
125
126       memcached_fetch_execute() return MEMCACHED_SUCCESS  if  all  keys  were
127       successful.  MEMCACHED_NOTFOUND  will  be return if no keys at all were
128       found.
129
130       memcached_fetch_result() sets error to  MEMCACHED_END  upon  successful
131       conclusion.   MEMCACHED_NOTFOUND  will be return if no keys at all were
132       found.
133

HOME

135       To find out more information please check: http://libmemcached.org/
136

SEE ALSO

138       memcached(1) libmemcached(3) memcached_strerror(3)
139

AUTHOR

141       Brian Aker
142
144       2011-2013, Brian Aker DataDifferential, http://datadifferential.com/
145
146
147
148
1491.0.16                         January 31, 2013      MEMCACHED_MGET_EXECUTE(3)
Impressum