---
name: "gearman_client_set_server_selection_by_unique"
section: "3"
platform: "linux"
package: "gearmand"
version: "2.2.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/gearman_client_set_server_selection_by_unique"
---

# gearman\_client\_set\_server\_selection\_by\_unique(3)

Gearmand Documentation, https://gearman.org/gearmand/

## NAME

gearman\_client\_set\_server\_selection\_by\_unique - Gearmand Documentation, 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

By default, when a client with more than one server added via *gearman\_client\_add\_server()* submits a job, it is sent to the first idle server in the order the servers were added -- the job's unique identifier plays no part in the choice.

*gearman\_client\_set\_server\_selection\_by\_unique()* 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 is that submissions sharing the same unique (from this client, or from any other client configured with the same server list and this option enabled) consistently land on the same server, and adding or removing a server only reshuffles the jobs that server itself was responsible for.

This only affects job submission (*gearman\_client\_do()*, *gearman\_client\_do\_background()*, and their variants, plus *gearman\_client\_add\_task()* and friends); commands such as status lookups are unaffected. A job submitted with an empty unique falls back to the default selection, since there is no meaningful value to hash.

If the hash-selected server cannot be reached, the client fails over to the next server in ring order rather than failing the submission outright, the same way the default selection falls through the server list on a connection failure.

This option is disabled by default. It can also be enabled or disabled with the *GEARMAN\_CLIENT\_SERVER\_SELECTION\_BY\_UNIQUE* flag via *gearman\_client\_add\_options()* / *gearman\_client\_remove\_options()* (and queried with *gearman\_client\_has\_option()*), which is useful for language bindings that pass an options bitmask through to libgearman. Both ways change the same setting. It is copied by *gearman\_client\_clone()* like the client's other persistent settings.

*gearman\_client\_server\_selection\_by\_unique()* returns whether the option is currently enabled.

## RETURN VALUE

*gearman\_client\_server\_selection\_by\_unique()* returns a **bool**; it returns **false** for a **NULL** client.

## HOME

To find out more information please check: *https://gearman.org/gearmand/*

**SEE ALSO:**

**[gearmand(8)](/gearmand/8.md)** **[libgearman(3)](/libgearman/3.md)** **gearman\_client\_st** **gearman\_client\_add\_server**

## AUTHOR

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

## COPYRIGHT

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