Fix #513: preserve the first real failure across gearman_universal_st::flush()

gearman_universal_st::flush() loops over every registered connection and calls con->flush() on each, intentionally discarding the return value – the existing comment explains why: there’s no way to indicate to the caller which connection experienced the issue, and error detection is meant to happen later via gearman_wait().

But discarding the return value doesn’t stop con->flush()’s failures from mutating the single shared universal error buffer as a side effect. So with multiple configured servers, whichever connection happens to fail last in the loop silently overwrites whatever a genuinely more useful earlier failure had recorded – e.g. a specific GEARMAN_COULD_NOT_CONNECT from one server being replaced by a generic message (or masked entirely by a routine GEARMAN_IO_WAIT) from another server later in the list.

Fix: track the first connection in the loop whose flush() call is a real failure (gearman_failed() and not gearman_continue(), so routine GEARMAN_IO_WAIT/GEARMAN_IN_PROGRESS/etc. don’t count), snapshot its return code and message, and restore them after the loop so a later connection’s outcome can’t clobber it. The comment about not being able to tell the caller which connection failed still holds; this only stops the message for the connection that did fail first from being silently lost.

Added a white-box regression test in tests/libgearman-1.0/internals.cc that forces two connections directly into flush()’s address-exhausted branch (bypassing real sockets/timing entirely) and confirms the first-processed connection’s host:port survives in the final message rather than the second’s. Verified red/green: fails against the unfixed universal.cc, passes with the fix. Full t/internals (16), t/client (338), and t/worker (59) suites pass with no regressions.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com Claude-Session: https://claude.ai/code/session_0189Fmbj2QE1gjbs1nPaPxhi Signed-off-by: Alexei Pastuchov info@maximka.de

gearmand

The latest version of gearmand source code and versions 1.1.13 and later can be found at the GitHub Repository. Older versions released before 1.1.13 can be found at the Launchpad Repository.

You can grab the latest release distribution of Gearman from https://github.com/gearman/gearmand/releases. Unless otherwise specified, releases are GPG-signed by Clint Byrum (@SpamapS on GitHub), whose public key can be found at https://fewbar.com/clint-byrum-public-key/, or Edward Sabol (@esabol on GitHub), whose public key can be found at https://raw.githubusercontent.com/esabol/esabol/refs/heads/main/sabol-public-github-signing-key.asc.

What Is Gearman?

Gearman provides a generic application framework to farm out work to other machines or processes that are better suited to do the work. It allows you to do work in parallel, to load balance processing, and to call functions between languages. Gearman is the nervous system for how distributed processing communicates.

If you downloaded this package as a tar.gz distribution, you’ll want to read the Getting Started section below or visit the more detailed web page Getting Started.

If you are interested in developing or submitting patches to the project, read the Contributing section below and check out the CONTRIBUTING.md file for Coding Style and COPYING for details on licensing.

Getting Started

If you want to work on the latest code, please read the file CONTRIBUTING.md.

To build and install from a release tarball (.tar.gz or .tgz), follow these steps:

Change into the directory where you saved the tarball and run:

tar xzf gearmand-X.Y.tar.gz
cd gearmand-X.Y

Then run the usual autoconfigure style build (you may need to use sudo to install):

./configure
make
make install

There are various dependencies that may be satisfied on Ubuntu by installing these packages:

sudo apt install automake autoconf libtool make curl gcc g++ git gperf     \ 
    libssl-dev libboost-all-dev libevent-dev libhiredis-dev libpq-dev      \ 
    libtokyocabinet-dev python3-sphinx uuid-dev

You can also run make test before installing to make sure everything checks out OK. You can streamline the process of building and testing by executing:

./configure && make && make test
make install

Once you have it installed, you can start the Gearman job server with:

gearmand --verbose INFO

This will start it while printing some verbose messages. To try running a job through it, look in the examples/ directory of this source and run:

./reverse_worker

Once that is running, you can run your first job with:

./reverse_client "Hello, Gearman!"

If all goes well, the reverse_worker application should have output:

Job=H:lap:1 Workload=Hello, Gearman! Result=!namraeG ,olleH

While the reverse_client returned:

Result=!namraeG ,olleH

There are a lot more details about gearmand at Getting Started.

If you want to start writing your own client and workers, be sure to check out the Developer API documentation.

For using and configuring the gearmand server, please check out the latest documentation.

There are also many other useful resources to help you put gearmand to work for you!

Enjoy!

Contributing

The current versions of geamand are maintained on the GitHub repository for gearmand.

If you are not familiar with git, you can find more info at Getting Started with Git.

Please follow these instructions to clone, create a branch, and generate a pull request on that branch. More details on using GitHub can be found at GitHub Help.

Clone the GitHub repository to your local file system:
```
 git clone https://github.com/gearman/gearmand
```
If you do not have access to create branches in the gearmand GitHub repository, you should fork the repository and clone your fork instead. Refer to Contributing to Open Source on GitHub for details.
Next, think of a clear, descriptive branch name and then create a new branch and change to it:
```
 cd gearmand
 git checkout -b DESCRIPTIVE_BRANCH_NAME
```
Once the tree is branched you will need to generate the “configure” script for autoconfigure.
```
 ./bootstrap.sh -a
```
Finally, you are ready to run tests, make changes to the code, commit and push them to GitHub, and generate a pull request on your branch so we can consider your changes.

You can learn more about how to Create a Pull Request and Create a Pull Request from a Fork.

But Wait! There’s More!

Once you have made your changes there are two additional make targets to build release ready distributions:

To generate a tarball distribution of your code:

make dist

Or to generate an RPM distribution use:

make rpm

Thanks and keep hacking!

Cheers,
-Brian
Seattle, WA.

Releasing Gearmand

When it’s time to release the master branch, check the last release tag, and create a new one. Most releases are patch releases. Just increment the third number in the version if that’s the case with this release.

Checkout the master branch of this repository.
Ensure there are no changes staged or un-added. Anything not committed to the master branch will be removed by the next step!
$ git clean -xdf # This will remove all generated files
Review changes merged since the last release with git log $LAST_RELEASE_TAG..
$ git tag -s $NEW_RELEASE_TAG # Type in release notes
$ ./bootstrap.sh -a && ./configure # This is needed to make dist properly
$ make -C docs man # This step may or may not be necessary
$ make dist # This creates the tarball
$ cd .. && tar -zxvf $OLDPWD/gearmand-$NEW_RELEASE_TAG.tar.gz && cd gearmand-$NEW_RELEASE_TAG && ./configure && make test # Just to be sure that the tarball actually builds
$ gpg --sign --armor --detach gearmand-$NEW_RELEASE_TAG.tar.gz
THIS IS THE POINT OF NO RETURN, TO ABORT: git tag -d $NEW_RELEASE_TAG and start over.
$ git push --tags # Uploads the release tag to GitHub
Visit https://github.com/gearman/gearmand/releases and you should see the new tag without details. Create a release using that tag.
Upload gearmand-$NEW_RELEASE_TAG.tar.gz and the .asc signature file to the release.
Announce the release to the gearman Matrix channel and mailing list.