MEMCACHED_MGET_EXECUTE(3)

✨ NAME ✨

okay so bestie, welcome to memcached_mget_execute — this is the libmemcached-awesome page all about retrieving data from the server. yes that's the whole name, we're keeping it short and sweet. 💅

---

🎀 SYNOPSIS 🎀

first things first, you gotta bring the header in and link the lib, no cap:

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

and here's the whole squad of function signatures, verbatim, don't @ me:

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)

---

🦋 DESCRIPTION 🦋

okay so let's go one by one, i promise this is all gonna make sense. 🫶

memcached_get() is your girl for pulling one single value out of the server. you hand her a key and the key's length, and that's how you fetch the object. you also gotta pass in three pointer variables so she can tell you what state the returned object is in:

• a uint32_t pointer — this one holds whatever flags you stored alongside the value
• a size_t pointer — this gets filled in with the size of the object
• a memcached_return_t pointer — this one catches any error

on success you get the object back, on failure you get NULL. and listen — anything memcached_get() hands you must be released by the caller application. that's on you, bestie. 🫡

memcached_mget() is for when you wanna grab multiple keys at once. for multi-key operations this is always faster, like it's not even close. and heads up: this function always works asynchronously.

so after memcached_mget() runs successfully, how do you actually get the data? you call memcached_fetch_result(). keep calling it until it returns NULL (that's the "no more values, we're done here" signal). and if you need to bail out halfway through a memcached_mget() call, you can run a memcached_quit() — though honestly it's not required.

memcached_fetch_result() pulls an individual value from the server. rule of thumb: memcached_mget() must always be called before you use this method. you pass in a key and its length to fetch the object, and you supply those same three pointer variables for the state of the returned object:

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

object comes back on success, NULL comes back on failure. MEMCACHED_END is what you get in the *error value once all the objects that were found have been returned. and the final value at MEMCACHED_END is null.

also memcached_fetch_result() is what returns a memcached_result_st structure from a memcached server. that result object is forward compatible with changes to the server — for more info go peek at the memcached_result_st help. and if you don't pass a result structure in, this function will dynamically allocate one for you. generous queen. 👑

memcached_fetch_execute() is the callback version for result sets. instead of handing results back to you to process, it passes each result set straight to the list of functions you gave it. what does it hand your function?

• a memcached_st that can be cloned for use inside the called function — but it cannot be used directly
• a result set that does not need to be freed
• a "context" — which is just a pointer to a memory reference that you, the caller, supply

currently only one value gets passed to each function call. in the future there'll be an option to let that be an array. future tea, we love to see it. 🍵

memcached_mget_execute() and memcached_mget_execute_by_key() are basically memcached_mget() but with a glow-up: they may trigger the supplied callbacks with result sets while sending out the queries. why does that matter? because if you try to do a really large multiget with memcached_mget(), you might hit a deadlock in the OS kernel — it'll fail to write data to the socket because the input buffer is full. 😭 memcached_mget_execute() fixes this by processing some of the results before it keeps sending out requests. and important: this function is only available in the binary protocol. periodt.

memcached_get_by_key() and memcached_mget_by_key() behave in a similar nature to memcached_get() and memcached_mget(). the difference? they take a master key (the group_key), which is used for determining which server an object was stored on if key partitioning was used for storage. iykyk. 🧚

⚠️ and now for the important disclaimer, bestie: all of the above functions are not tested when MEMCACHED_BEHAVIOR_USE_UDP has been set. if you execute any of these with that behavior turned on, you'll get MEMCACHED_NOT_SUPPORTED returned — or, for those functions that don't return a memcached_return_t, the error function parameter will be set to MEMCACHED_NOT_SUPPORTED instead. don't say i didn't warn you. 💀

---

🌸 RETURN VALUE 🌸

• every single object you retrieve via memcached_get() or memcached_get_by_key() must be freed with free(3). no exceptions, free your memory, it's self care. 🫶
• memcached_get() returns NULL on error — and you must look at the value of error to figure out what the actual error was. don't just stare at the NULL, bestie.
• memcached_fetch_execute() returns MEMCACHED_SUCCESS if all keys were successful. MEMCACHED_NOTFOUND comes back if no keys at all were found.
• memcached_fetch_result() sets error to MEMCACHED_END upon successful conclusion. and again, MEMCACHED_NOTFOUND gets returned if no keys at all were found.

---

👑 SEE ALSO 👑

go read these next, they're all part of the lore:

• memcached(1)
• libmemcached(3)
• memcached_strerror(3)

---

that's the whole page, you absolutely ate it. this was libmemcached-awesome version 1.1, dated Jul 24, 2025 — love that for us. now go free your objects and hydrate. 💖✨🎀