MEMCACHED_SERVER_CURSOR(3)

📦
version 1.1.4 · 13 versions
, in fedora 43

✨ MEMCACHED_SERVER_CURSOR ✨

okay bestie, buckle up 💖 this is the libmemcached-awesome page for memcached_server_cursor(3) — aka the libmemcached documentation on how to wrangle your server list. it's giving "many hands make light work" but the hands are callbacks 🫶

🌈 SYNOPSIS 🌈

first things first, you gotta pull in the header and link the library, no cap:

#include <libmemcached/memcached.h>

and compile + link with -lmemcached — don't forget it or nothing works and you'll be sad 😭

okay so here's every single function on this page, one by one, zero skips, periodt 💅

memcached_server_count

uint32_t memcached_server_count(memcached_st *ptr)

Parameters

  • ptr — pointer to initialized memcached_st struct

Returns

number of configured servers ✨

memcached_server_add

memcached_return_t memcached_server_add(memcached_st *ptr, const char *hostname, in_port_t port)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • hostname — hostname or IP address of the TCP server to add
  • port — port of the TCP server

Returns

memcached_return_t indicating success 💖

memcached_server_add_udp

memcached_return_t memcached_server_add_udp(memcached_st *ptr, const char *hostname, in_port_t port)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • hostname — hostname or IP address of the UDP server to add
  • port — port of the UDP server

Returns

memcached_return_t indicating success ✨

memcached_server_add_unix_socket

memcached_return_t memcached_server_add_unix_socket(memcached_st *ptr, const char *socket)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • socket — path to the UNIX socket of the server to add

Returns

memcached_return_t indicating success 🎀

memcached_server_push

memcached_return_t memcached_server_push(memcached_st *ptr, const memcached_server_st *list)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • list — pre-configured list of servers to push

Returns

memcached_return_t indicating success 🦋

memcached_server_by_key

const memcached_instance_st *memcached_server_by_key(memcached_st *ptr, const char *key, size_t key_length, memcached_return_t *error)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • key — key to hash and lookup a server
  • key_length — length of key without any terminating zero
  • error — pointer to memcached_return_t indicating success

Returns

the server instance to be used for storing/retrieving key 🔥

memcached_server_get_last_disconnect

const memcached_instance_st *memcached_server_get_last_disconnect(const memcached_st *ptr)

Parameters

  • ptr — pointer to initialized memcached_st struct

Returns

the instance of the last server for which there was a connection problem 💀

memcached_server_cursor (the main character 👑)

memcached_return_t memcached_server_cursor(const memcached_st *ptr, const memcached_server_fn *callback, void *context, uint32_t number_of_callbacks)

Parameters

  • ptr — pointer to initialized memcached_st struct
  • callback — list of memcached_server_fn to be called for each server instance
  • context — pointer to user supplied context for the callback
  • number_of_callbacks — number of callbacks supplied

Returns

memcached_return_t indicating success 🌸

the callback type itself

typedef memcached_return_t (*memcached_server_fn)(const memcached_st *ptr, const memcached_instance_st *server, void *context)

Param ptr

pointer to the memcached_st struct

Param server

pointer to memcached_instance_st

Param context

pointer to user supplied context

Returns

memcached_return_t indicating success 💜

🌟 DESCRIPTION 🌟

ngl, libmemcached does its thing on a list of hosts, and the order of those hosts is literally what determines routing to keys. iconic. functions are provided so you can add keys to memcached_st structures. and if you wanna manipulate lists of servers, go look at memcached_server_st 👀

memcached_server_count() hands you a count of how many servers your memcached_st structure is currently using. simple, slay.

memcached_server_add() pushes a single TCP server into the memcached_st structure. this server goes at the end. duplicate servers are allowed, so duplication is not checked — the library is not your mom, bestie 🙈 but here's the tea: if you execute this function with the MEMCACHED_BEHAVIOR_USE_UDP behavior set, you get a MEMCACHED_INVALID_HOST_PROTOCOL. not the vibe.

memcached_server_add_udp() pushes a single UDP server into the memcached_st structure. also placed at the end, also no duplicate checking because duplicates are allowed. and the flip side of the above: executing this one without setting the MEMCACHED_BEHAVIOR_USE_UDP behavior will result in a MEMCACHED_INVALID_HOST_PROTOCOL. symmetry, we love her 💅

memcached_server_add_unix_socket() pushes a single UNIX socket into the memcached_st structure. yep, at the end. yep, duplicates allowed, not checked. ⚠️ but heads up: the length of the filename must be one character less than MEMCACHED_MAX_HOST_LENGTH — that's a hard limit, no negotiating.

memcached_server_push() pushes an array of memcached_server_st into the memcached_st structure. these servers get placed at the end too, duplicates allowed, not checked. and a copy is made of the structure, so the list you provided — and any operations you do on that list — are not saved 🫶 your list stays yours.

memcached_server_by_key() lets you hand over a key and get back the server that would be used for assignment. lowkey handy.

memcached_server_get_last_disconnect() returns a pointer to the last server for which there was a connection problem. > important nuance, bestie: it does not mean this particular server is currently dead. but if the library is reporting that a server is dead, the returned server is a very good candidate 👑 so like, strong suspect energy.

memcached_server_cursor() takes a memcached_st and loops through the list of hosts currently in the cursor, calling the list of callback functions provided. you can optionally pass in a value via context which gets provided to each callback function. and if any callback returns an error, the loop terminates — one bad callback ends the whole party 😭 also: memcached_server_cursor() is passed the original caller memcached_st in its current state.

💫 RETURN VALUE 💫

varies, see particular functions. (yes that's really it, each function above told you its own deal 💖)

🦋 SEE ALSO 🦋

that's the whole page, fr fr 🌈 you now know everything about server cursors and adding servers and not being weird about duplicates. go forth and route those keys, main character 🎀

this was the libmemcached-awesome glow-up of the page, version 1.1, dated Jul 24, 2025 — tysm for reading, ily, bye bestie 💜🌸

📦 where this page comes from