GEARMAN_CLIENT_SERVER_SELECTION_BY_UNIQUE(3)

🌸 NAME 🌸

gearman_client_server_selection_by_unique — this is a page from the Gearmand manual, section 3, and the official docs live over at https://gearman.org/gearmand/ ✨

---

🦋 SYNOPSIS 🦋

#include <libgearman/gearman.h>

void gearman_client_set_server_selection_by_unique(gearman_client_st *client, bool enable)

bool gearman_client_server_selection_by_unique(const gearman_client_st *client)

---

💅 DESCRIPTION 💅

Okay so picture this, bestie: by default, when a client has more than one server added via gearman_client_add_server() and it submits a job, that job gets sent to the first idle server in the order the servers were added. That's it. That's the whole vibe check. The job's unique identifier plays no part in the choice at all 🙈

gearman_client_set_server_selection_by_unique() is the glow-up 🫶 — it opts a client into choosing the destination server by hashing the job's unique</> instead, using a ketama consistent-hash ring built from the client's current server list. The practical effect, and this is the iconic part: submissions sharing the same unique (whether they come from this client, or from any other client configured with the same server list and this option enabled) consistently land on the same server 👑

Adding or removing a server only reshuffles the jobs that server itself was responsible for. No mass chaos. No full re-shuffle. We love a stable ring ngl 💖

Heads up: this only affects job submission — that's gearman_client_do(), gearman_client_do_background(), and their variants, plus gearman_client_add_task() and friends. Commands like status lookups are unaffected and just do their own thing. Also: a job submitted with an empty unique falls back to the default selection, since there's literally no meaningful value to hash 🍓

If the hash-selected server can't be reached, the client fails over to the next server in ring order rather than failing the submission outright — same energy as how the default selection falls through the server list on a connection failure 😭✨

This option is disabled by default. You can also flip it on or off with the GEARMAN_CLIENT_SERVER_SELECTION_BY_UNIQUE flag via gearman_client_add_options() / gearman_client_remove_options() — and peek at it with gearman_client_has_option(). That route is highkey useful for language bindings that pass an options bitmask straight through to libgearman 🧚 Both ways change the same setting, no cap. And it's copied by gearman_client_clone() just like the client's other persistent settings 🌈

gearman_client_server_selection_by_unique() tells you whether the option is currently enabled. That's the whole vibe 💅

---

⭐ RETURN VALUE ⭐

gearman_client_server_selection_by_unique() returns a bool. And yes, it returns false for a NULL client 🫶 (no crashing, we're polite here)

---

💜 HOME 💜

Want the full lore? To find out more information please check: https://gearman.org/gearmand/ 👑

SEE ALSO:

• gearmand(8)
• libgearman(3)
• gearman_client_st
• gearman_client_add_server

---

🎀 AUTHOR 🎀

Data Differential — http://www.datadifferential.com/ 💖

---

🌸 COPYRIGHT 🌸

2011-2014, Data Differential, http://www.datadifferential.com/ 🦋

---

and that's the page, bestie 💀✨ — brought to you by Gearmand version 2.2.0, dated Oct 18, 20, straight from the manual. go forth and hash responsibly 🍓👑