MEMCACHED_MGET_BY_KEY(3)

📦
version 1.1.4 · 13 versions
, in fedora 43

💖 MEMCACHED_MGET_BY_KEY 💖

okay bestie, this is a page from libmemcached-awesome — the MEMCACHED_MGET_BY_KEY(3) manual. yes it's named after one function but it's actually a whole girl-group of functions that fetch stuff off a memcached server. sit down, get comfy, we're doing multigets 🦋

✨ NAME ✨

memcached_mget_by_key — retrieving data from the server. that's the vibe. we get. we fetch. we slay.

🌸 SYNOPSIS 🌸

#include <libmemcached/memcached.h>
       Compile and link with -lmemcached

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 *group_key,
size_t group_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
*group_key, size_t group_key_length, const char *const *keys, const
size_t *key_length, size_t number_of_keys)

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 *group_key, size_t group_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)

typedef memcached_return_t (*memcached_execute_fn)(const memcached_st
*ptr, memcached_result_st *result, void *context)

like... look at that roster. iconic. 💅

👑 DESCRIPTION 👑

memcached_get() — the solo fetch 💖

memcached_get() is your girl for grabbing one individual value off the server. you gotta pass in a key and its length to fetch the object, no skipping that. and you must supply three pointer variables that'll hand you back the state of the returned object:

  • a uint32_t pointer that holds whatever flags you stored alongside the value
  • a size_t pointer that gets filled with the size of the object
  • a memcached_return_t pointer to hold any error

the object comes back on success, and NULL comes back on failure. and here's the part nobody tells you: any object returned by memcached_get() must be released by the caller application. that's on you, bestie. not the library. you. 🫶

memcached_mget() — the group chat 💬

memcached_mget() is how you select multiple keys at once. and fr fr, for multiple key operations it is always faster to use this function — no cap, always. it also always works asynchronously.

to retrieve data after a successful execution of memcached_mget(), you're gonna need to call memcached_fetch_result(). keep calling it until it returns a NULL (that means no more values, we're done, the party's over). and if you need to quit in the middle of a memcached_mget() call, you can execute a memcached_quit() — though this is not required. do it if you want, it's not a rule. ✨

memcached_fetch_result() — the individual handoff 🎀

memcached_fetch_result() fetches an individual value from the server. memcached_mget() must always be called before using this method. (yes, always. it's the pre-req. the prerequisite. the "you can't sit with us until—")

you must pass in a key and its length to fetch the object, and you must supply those same three pointer variables giving you the state of the returned object: a uint32_t pointer for whatever flags you stored with the value, a size_t pointer that gets filled with the size of the object, and a memcached_return_t pointer to hold any error. object returns on success, NULL on failure.

MEMCACHED_END is returned by the *error value when all objects that have been found have been returned. the final value upon MEMCACHED_END is null. that's the little "bye bestie" signal. 😭

memcached_fetch_result() again, but the struct edition 🧚

memcached_fetch_result() is also used to return a memcached_result_st structure from a memcached server. this result object is forward compatible with changes to the server. for more info, please refer to the memcached_result_st help. and get this — this function will dynamically allocate a result structure for you if you don't pass one to the function. so generous. so giving. 👑

memcached_fetch_execute() — the callback era 🌈

memcached_fetch_execute() is a callback function for result sets. instead of handing the results back to you for processing, it passes each of the result sets to the list of functions you provide. what it passes to the function:

  • a memcached_st that can be cloned for use in the called function — it can not be used directly, okay? clone it or nothing.
  • a result set that does not need to be freed 🎉
  • a "context" — which 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. future plans, bestie. manifesting it. ✨

memcached_mget_execute() and memcached_mget_execute_by_key() — the deadlock fixer 🚨

these two are similar to memcached_mget(), but they may trigger the supplied callbacks with result sets while sending out the queries. why do you care? because if you try to perform a really large multiget with memcached_mget(), you may encounter a deadlock in the OS kernel — it will 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 to send out requests. chef's kiss. the fix. 🔥

please note that this function is only available in the <b>binary protocol</b>. no binary protocol, no dice.

memcached_get_by_key() and memcached_mget_by_key() — the master key girls 🔑

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's used for determining which server an object was stored on, if key partitioning was used for storage. that's it. that's the whole twist. iykyk. 💅

⚠️ the UDP warning, and yes it's important ⚠️

all of the above functions are not tested 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.

so like... don't. just don't. turn that behavior off first. 🙈

💀 RETURN VALUE 💀

all objects retrieved via memcached_get() or memcached_get_by_key() must be freed with free(3). every single one. no leaks in this house. 🫶

memcached_get() will return NULL on error. you must look at the value of error to determine what the actual error was — NULL alone tells you nothing, bestie, it's giving mysterious. 😭

memcached_fetch_execute() returns MEMCACHED_SUCCESS if all keys were successful. MEMCACHED_NOTFOUND will be returned if no keys at all were found. all of them or none of them, apparently. dramatic. ✨

memcached_fetch_result() sets error to MEMCACHED_END upon successful conclusion. MEMCACHED_NOTFOUND will be returned if no keys at all were found.

🦋 SEE ALSO 🦋

and that's the page!! 🌸 this is version 1.1, dated Jul 24, 2025, from the libmemcached-awesome era. go forth, multiget responsibly, free your results, and never ever turn on MEMCACHED_BEHAVIOR_USE_UDP. mwah 💖✨🎀

📦 where this page comes from