Gearman

https://gearman.org
Admin
Gearman is an open-source application framework designed to distribute work across multiple machines...
Tokens:42,093
Snippets:492
Trust Score:9.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Compile and install Gearmand

Source: https://gearman.org/gearmand/build/centos5-8

Standard build commands to compile and install the software.

```bash
./configure
make
sudo make install
```

--------------------------------

### Install Gearman from Source Repository

Source: https://gearman.org/getting-started

Commands to clone the latest development source from Git and install it.

```bash
git clone https://github.com/gearman/gearmand
cd gearmand
./bootstrap.sh
make install
```

--------------------------------

### Install build dependencies on Ubuntu

Source: https://gearman.org/gearmand/build/ubuntu

Run these commands to install the required compilers, libraries, and development headers.

```bash
sudo apt-get install –yes gcc
sudo apt-get install –yes autoconf
sudo apt-get install –yes bison
sudo apt-get install –yes flex
sudo apt-get install –yes libtool
sudo apt-get install –yes make
sudo apt-get install –yes libboost-all-dev
sudo apt-get install –yes libcurl4-openssl-dev curl
sudo apt-get install –yes libevent-dev
sudo apt-get install –yes memcached
sudo apt-get install –yes uuid-dev
sudo apt-get install –yes libsqlite3-dev
sudo apt-get install –yes libmysqlclient-dev
```

--------------------------------

### Install Gearman PHP Extension

Source: https://gearman.org/getting-started

Commands to build and install the extension from a PECL tarball.

```bash
tar xzf gearman-X.Y.tgz
cd gearman-X.Y
phpize
./configure
make
make install
```

--------------------------------

### Server List Format Examples

Source: https://gearman.org/gearmand/libgearman/gearman_worker_add_server

Examples of the string format accepted by gearman_worker_add_servers for defining multiple gearmand servers.

```text
10.0.0.1,10.0.0.2,10.0.0.3
localhost234,jobserver2.domain.com:7003,10.0.0.3
```

--------------------------------

### Compile and install from tarball

Source: https://gearman.org/gearmand/install

Extracts the source code from a tarball and executes the standard build and installation sequence.

```bash
tar xzf gearmand-X.Y.tar.gz ./configure make make install
```

--------------------------------

### Install Gearman from Tarball

Source: https://gearman.org/getting-started

Commands to compile and install the latest stable Gearman release from a downloaded tarball.

```bash
tar xzf gearmand-X.Y.tar.gz
cd gearmand-X.Y
./configure
make
make install
```

--------------------------------

### Compile and install from source repository

Source: https://gearman.org/gearmand/install

Checks out the latest development source using Bazaar and runs the configuration and build process.

```bash
bzr branch lp:gearmand cd gearmand ./config/autorun.sh ./configure make make install
```

--------------------------------

### Implement a Simple GearmanWorker

Source: https://gearman.org/java-gearman-service

A complete example demonstrating the creation of a GearmanWorker, registration of a GearmanFunction, and connection to a job server.

```java
import org.gearman.Gearman;
import org.gearman.GearmanFunction;
import org.gearman.GearmanWorker;

/**
 * An example showing how to setup a simple gearman worker
 * @author isaiah.v
 */
public class SingleWorker {

    /** The gearman system */
    final Gearman gearman;

    /**
     * Creates a new SingleWorker. A SingleWorker will setup a worker with only one function and one job server
     * @param host
     *     The job server's host address
     * @param port
     *     The port number the server is listening on.
     * @param functionName
     *     The name of the function to register
     * @param function
     *     The GearmanFunction who will execute 'functionName'
     */
    public SingleWorker(String host, int port, String functionName, GearmanFunction function) throws IOException {

        if (host==null || functionName==null || function==null)
            throw new IllegalArgumentException("parameter is null");

        // Create a new gearman system
        this.gearman = new Gearman();

        // Create a GearmanWorker
        final GearmanWorker worker = gearman.createGearmanWorker();

        // Register function
        worker.addFunction(functionName, function);

        try {

            // Adds a job server, may throw IOException
            worker.addServer(host, port);

        } catch (IOException ioe) {

            // Close gearman system if an I/O exception occurs
            gearman.close();

            // Forward exception to caller
            throw ioe;
        }

    }

    /**
     * Closes the SingleWorker
     */
    public void close() {
        this.gearman.shutdown();
    }

    /**
     * Close if no reference to this object exists
     */
    @Override
    protected void finalize() throws Throwable {
        this.close();
    }
}
```

--------------------------------

### Start Gearman with libmysqlclient queue

Source: https://gearman.org/manual/job_server

Initializes the Gearman job server using the MySQL binary protocol for queue storage.

```bash
gearmand --queue-type=mysql --mysql-host=hostname
```

--------------------------------

### Verify Gearman Version

Source: https://gearman.org/getting-started

Script to verify the installation by printing the Gearman version.

```php
<?php
print gearman_version() . "\n";
?>
```

```bash
$ php gearman_version.php
0.8
```

--------------------------------

### Start Gearman Server in Debug Mode

Source: https://gearman.org/manual/job_server

Initializes the Gearman server with the libdrizzle module for persistent queuing.

```bash
> gearmand -q libdrizzle -vvv
INFO Initializing libdrizzle module
INFO libdrizzle module using table 'test.queue'
...
INFO Entering main event loop
```

--------------------------------

### Install Gearmand build dependencies on Fedora

Source: https://gearman.org/gearmand/build/fedora

Use these commands to install the required compilers, build tools, and development libraries via yum.

```bash
sudo yum install -y gcc gcc-c++
sudo yum install -y make
sudo yum install -y bison
sudo yum install -y flex
sudo yum install -y autoconf
sudo yum install -y libtool
sudo yum install -y memcached
sudo yum install -y libevent libevent-devel
sudo yum install -y uuidd libuuid libuuid-devel
sudo yum install -y boost boost-devel
sudo yum install -y libcurl-dev libcurl curl
```

--------------------------------

### Start Gearman Job Server

Source: https://gearman.org/getting-started

Commands to launch the Gearman job server in background or debug modes.

```bash
$ gearmand -d
```

```bash
$ gearmand -vvv
 INFO Starting up
 INFO Listening on :::4730 (6)
 INFO Creating wakeup pipe
 INFO Creating IO thread wakeup pipe
 INFO Adding event for listening socket (6)
 INFO Adding event for wakeup pipe
 INFO Entering main event loop
```

--------------------------------

### Enable server exceptions

Source: https://gearman.org/gearmand/libgearman/gearman_actions_t

Example of enabling exception handling on the server side.

```c
const char *EXCEPTIONS="exceptions";
gearman_client_set_server_option(client, EXCEPTIONS, strlen(EXCEPTIONS));
```

--------------------------------

### Configure Gearman with SQLite3 persistent queue

Source: https://gearman.org/manual/job_server

Command to start the Gearman daemon using the libsqlite3 module with a specified database file.

```bash
gearmand -vvv -q libsqlite3 --libsqlite3-db=/tmp/xx.sqlite
```

--------------------------------

### Execution Output Examples

Source: https://gearman.org/examples/multi-query

Shows the output of the client script when run with insufficient workers (serial execution) versus sufficient workers (parallel execution).

```text
# ./run/client/here
Fetching...
Got user info in: 9.00 seconds:
string(59) "The user requested (joe@joe.com) is 7 feet tall and awesome"
string(56) "The user (joe@joe.com) is 1 degree away from Kevin Bacon"
string(43) "The user (joe@joe.com) has no posts, sorry!"
```

```text
# ./run/client/here
Fetching...
Got user info in: 3.00 seconds:
string(59) "The user requested (joe@joe.com) is 7 feet tall and awesome"
string(56) "The user (joe@joe.com) is 1 degree away from Kevin Bacon"
string(43) "The user (joe@joe.com) has no posts, sorry!"
```

--------------------------------

### Configure Boost dependencies for CentOS 5.8

Source: https://gearman.org/gearmand/build/centos5-8

Commands to install and link the required Boost 1.41 development libraries.

```bash
rpm -Uvh epel-release-5-4.noarch.rpm
yum install boost141-devel
ln -s /usr/include/boost141/boost/ /usr/include/boost
export LDFLAGS=”-L/usr/lib64/boost141”
export LD_LIBRARY_PATH=/usr/lib64/boost141:$LD_LIBRARY_PATH
sudo yum install e2fsprogs-devel e2fsprogs
```

--------------------------------

### Configure Gearman with PostgreSQL persistent queue

Source: https://gearman.org/manual/job_server

Command to start the Gearman daemon using the Postgres module with specific connection information and table name.

```bash
gearmand -L 127.0.0.1 --libpq-conninfo 'hostaddr=127.0.0.1 port=5432 dbname=gearman user=postgres' --libpq-table=queue123 --verbose DEBUG -q Postgres
```

--------------------------------

### Start a Gearman Worker

Source: https://gearman.org/getting-started

Registers a function with the job server and executes a shell command for each incoming job.

```bash
$ gearman -w -f wc -- wc -l
```

--------------------------------

### Start Gearman with libdrizzle queue

Source: https://gearman.org/manual/job_server

Configures the Gearman job server to use a Drizzle or MySQL table for persistent storage.

```bash
gearmand -q libdrizzle --libdrizzle-db=some_db --libdrizzle-table=gearman_queue
```

```bash
gearmand -q libdrizzle --libdrizzle-host=10.0.0.1 --libdrizzle-user=gearman \
                       --libdrizzle-password=secret --libdrizzle-db=some_db \
                       --libdrizzle-table=gearman_queue --libdrizzle-mysql
```

--------------------------------

### HTTP POST Request for Job Submission

Source: https://gearman.org/gearmand/gearmand

Example of a POST request to the /reverse endpoint to submit a job with a workload.

```http
POST /reverse HTTP/1.1
Content-Length: 12

Hello world!

```

--------------------------------

### Submit a low priority background job via HTTP

Source: https://gearman.org/manual/job_server

Example of using custom X-Gearman headers to configure job priority and background execution.

```http
POST /reverse HTTP/1.1
Content-Length: 12
X-Gearman-Background: true
X-Gearman-Priority: low

Hello world!
```

--------------------------------

### Low Priority Background Job Request

Source: https://gearman.org/gearmand/gearmand

Example of submitting a low priority background job using HTTP headers.

```http
POST /reverse HTTP/1.1
Content-Length: 12
X-Gearman-Background: true
X-Gearman-Priority: low

Hello world!

```

--------------------------------

### Issuing a background task in C

Source: https://gearman.org/gearmand/libgearman/gearman_client_do_background

Demonstrates creating a client, adding a server, and executing a background task with a unique identifier.

```c
/*
# Gearman server and library
# Copyright (C) 2012 Data Differential, http://datadifferential.com/
# All rights reserved.
#
# Use and distribution licensed under the BSD license.  See
# the COPYING file in this directory for full text.
*/

#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <libgearman-1.0/gearman.h>

int main(void)
{
  gearman_client_st *client= gearman_client_create(NULL);

  gearman_return_t ret= gearman_client_add_server(client, "localhost", 0);
  if (gearman_failed(ret))
  {
    return EXIT_FAILURE;
  }

  gearman_job_handle_t job_handle;
  gearman_return_t rc= gearman_client_do_background(client,
                                                    "reverse_function",
                                                    "unique_value",
                                                    "my string to reverse", strlen("my string to reverse"),
                                                    job_handle);

  if (gearman_success(rc))
  {
    // Make use of value
    printf("%s\n", job_handle);
  }

  gearman_client_free(client);

  return 0;
}
```

--------------------------------

### Implement a Gearman Client in PHP

Source: https://gearman.org/

Initializes a Gearman client and sends a job to the server for processing.

```php
<?php
// Reverse Client Code
$client = new GearmanClient();
$client->addServer();
print $client->doNormal("reverse", "Hello World!");
```

--------------------------------

### Initialize Gearman System and Services

Source: https://gearman.org/java-gearman-service

Create a Gearman system with a specified thread count and instantiate worker, client, and server services.

```java
// Create a new gearman system using 8 threads
final Gearman gearman = new Gearman(8);

// Create a GearmanWorker object
final GearmanWorker worker = gearman.createGearmanWorker();

// Create a GearmanClient object
final GearmanClient client = gearman.createGearmanClient();

// Create a GearmanServer object
final GearmanServer server = gearman.createGearmanServer();
```

--------------------------------

### Run Worker

Source: https://gearman.org/manual/job_server

Starts a worker process to consume jobs for the specified function.

```bash
gearman -f testq -w
```

--------------------------------

### gearman_worker_context / gearman_worker_set_context

Source: https://gearman.org/gearmand/libgearman/gearman_worker_st

Get or set an arbitrary user-defined context object for the worker.

```APIDOC
void *gearman_worker_context(const gearman_worker_st *worker);
void gearman_worker_set_context(gearman_worker_st *worker, void *context);
```

--------------------------------

### gearman_worker_timeout / gearman_worker_set_timeout

Source: https://gearman.org/gearmand/libgearman/gearman_worker_st

Get or set the current timeout value in milliseconds for the worker.

```APIDOC
int gearman_worker_timeout(gearman_worker_st *worker);
void gearman_worker_set_timeout(gearman_worker_st *worker, int timeout);
```

--------------------------------

### Launch Gearmand with MySQL Support

Source: https://gearman.org/gearmand/gearmand/queues/mysql

Command-line arguments to configure Gearmand to use a MySQL database for queue persistence.

```bash
gearmand  --queue-type=MySQL \
          --mysql-host=localhost \
          --mysql-port=3306 \
          --mysql-user=gearman \
          --mysql-password=your_pw \
          --mysql-db=gearman \
          --mysql-table=gearman_queue
```

--------------------------------

### Execute a task with gearman_client_do()

Source: https://gearman.org/gearmand/libgearman/examples

Demonstrates a simple synchronous task execution using gearman_client_do().

```c
/*
# Gearman server and library
# Copyright (C) 2012 Data Differential, http://datadifferential.com/
# All rights reserved.
#
# Use and distribution licensed under the BSD license.  See
# the COPYING file in this directory for full text.
*/

#include <string.h>
#include <stdlib.h>
#include <libgearman/gearman.h>

int main(void)
{
  gearman_client_st *client= gearman_client_create(NULL);

  gearman_return_t ret= gearman_client_add_server(client, "localhost", 0);
  if (gearman_failed(ret))
  {
    return EXIT_FAILURE;
  }

  size_t result_size;
  gearman_return_t rc;
  void *value= gearman_client_do(client, "reverse_function", "unique_value", 
                                 "my string to reverse", strlen("my string to reverse"), 
                                 &result_size, &rc);

  if (gearman_success(rc))
  {
    // Make use of value
  }
  free(value);

  gearman_client_free(client);

  return 0;
}
```

--------------------------------

### Generate Server Certificate

Source: https://gearman.org/gearmand/gearmand/ssl

Create the server private key, certificate signing request, and sign it using the CA certificate and extension file.

```bash
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out gearmand.key

openssl req -new -key gearmand.key -subj "/CN=gearmand-server.local" -out gearmand.req

openssl x509 -req -in gearmand.req -CA gearmand-ca.pem -CAkey gearmand-ca.key -CAcreateserial -out gearmand.pem -days 730 -sha256 -extfile gearmand_server_ext.cnf
```

--------------------------------

### Configure PHP Extension

Source: https://gearman.org/getting-started

Add this line to php.ini files to enable the extension.

```ini
extension="gearman.so"
```

--------------------------------

### Execute a task with gearman_execute()

Source: https://gearman.org/gearmand/libgearman/examples

Demonstrates sending a string to a 'reverse' function and printing the result.

```c
/*
  Example code to show how to send a string to a function called "reverse" and print the results.
*/

/*
# Gearman server and library
# Copyright (C) 2012 Data Differential, http://datadifferential.com/
# All rights reserved.
#
# Use and distribution licensed under the BSD license.  See
# the COPYING file in this directory for full text.
*/

#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <libgearman/gearman.h>

int main(void)
{
  gearman_client_st *client= gearman_client_create(NULL);

  gearman_return_t ret= gearman_client_add_server(client, "localhost", 0);
  if (gearman_failed(ret))
  {
    return EXIT_FAILURE;
  }

  gearman_argument_t value= gearman_argument_make(0, 0, "Reverse Me", strlen("Reverse Me"));

  gearman_task_st *task= gearman_execute(client, 
                                         "reverse", strlen("reverse"),  // function
                                         NULL, 0,  // no unique value provided
                                         NULL, 
                                         &value, 0);

  if (task == NULL) // If gearman_execute() can return NULL on error
  {
    fprintf(stderr, "Error: %s\n", gearman_client_error(client));
    gearman_client_free(client);
    return EXIT_FAILURE;
  }

  // Make sure the task was run successfully
  if (gearman_success(gearman_task_return(task)))
  {
    // Make use of value
    gearman_result_st *result= gearman_task_result(task);
    printf("%.*s\n", (int)gearman_result_size(result), gearman_result_value(result));
  }

  gearman_client_free(client);

  return EXIT_SUCCESS;
}
```

--------------------------------

### Submit a job via HTTP POST

Source: https://gearman.org/manual/job_server

Example of a standard HTTP POST request translated into a Gearman job submission for the 'reverse' function.

```http
POST /reverse HTTP/1.1
Content-Length: 12

Hello world!
```

--------------------------------

### Local Shell Command Equivalent

Source: https://gearman.org/getting-started

Demonstrates the local shell equivalent of the Gearman job processing task.

```bash
$ wc -l < /etc/passwd
```

--------------------------------

### HTTP Protocol Options

Source: https://gearman.org/manual/job_server

Configuration flags for enabling and configuring the HTTP protocol module.

```bash
 --protocol=http
 --http-port=PORT Port to listen on.
```

--------------------------------

### Create Server Extension Configuration

Source: https://gearman.org/gearmand/gearmand/ssl

Define the extension file required for Subject Alternative Names (SAN) support in server certificates.

```ini
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = gearmand-server.local
DNS.2 = localhost
IP.1 = 127.0.0.1
# Add your internal server IP if clients connect directly via IP
# IP.2 = 10.x.x.x
```

--------------------------------

### Gearmand Configuration for PostgreSQL

Source: https://gearman.org/gearmand/gearmand/queues/postgres

Environment variables and command-line parameters for connecting Gearmand to a PostgreSQL database on Debian systems.

```bash
export PGHOST=TheHostname
export PGPORT=5432
export PGUSER=gearman
export PGPASSWORD=ThePassword
export PGDATABASE=gearman
PARAMS="--verbose -q libpq --libpq-table=gearmanqueue1 --verbose"
```

--------------------------------

### libsqlite3 Persistent Queue Options

Source: https://gearman.org/manual/job_server

Configuration flags for using libsqlite3 as a persistent queue backend.

```bash
 --libsqlite3-db=DB       Database file to use.
 --libsqlite3-table=TABLE Table to use.
```

--------------------------------

### libpq Persistent Queue Options

Source: https://gearman.org/manual/job_server

Configuration flags for using libpq (PostgreSQL) as a persistent queue backend.

```bash
 --libpq-conninfo=STRING PostgreSQL connection information string.
 --libpq-table=TABLE     Table to use.
```

--------------------------------

### Test Resize Worker via Command Line

Source: https://gearman.org/getting-started

Use the gearman utility to send an image file to the worker and save the processed output.

```bash
$ gearman -f resize < full.jpg > thumb.jpg
$ ls -l full.jpg thumb.jpg
-rw-r--r-- 1 eday eday 3220493 2009-06-24 12:14 full.jpg
-rw-r--r-- 1 eday eday  328421 2009-06-24 12:21 thumb.jpg
```

--------------------------------

### gearman_version() Synopsis

Source: https://gearman.org/gearmand/libgearman/gearman_version

Include the libgearman header and link with -lgearman to use this function.

```c
#include <libgearman/gearman.h> 

const char *gearman_version(gearman_verbose_t verbose)
```

--------------------------------

### gearman_client_clone

Source: https://gearman.org/gearmand/libgearman/gearman_client

Creates a new gearman_client_st by copying defaults and server lists from an existing client.

```APIDOC
## gearman_client_clone

### Description
Copies the defaults and list of servers from a source gearman_client_st to a new or provided destination structure.

### Signature
gearman_client_st *gearman_client_clone(gearman_client_st *client, const gearman_client_st *from)

### Parameters
- **client** (gearman_client_st*) - Optional - Destination structure or NULL for allocation.
- **from** (const gearman_client_st*) - Required - Source structure to clone from.

### Return Value
Returns a pointer to the cloned gearman_client_st, or NULL on allocation failure.
```

--------------------------------

### Create a Basic Gearman Worker in PHP

Source: https://gearman.org/manual/workers

Initializes a GearmanWorker object, connects to a local server, and enters a loop to wait for tasks. This implementation requires registered functions to avoid runtime errors.

```php
<?php
// ---------------------------------------------
// START Basic Worker Creation

// Create Worker Object
$worker = new GearmanWorker();
// Add Gearman Job Servers to Worker
$worker -> addServer("127.0.0.1","4703");

// END Basic Worker Creation
// ---------------------------------------------

// Add Gearman Functions

// Gearman Worker Main Loop
while (1)
{
  $worker->work();
  if($worker->returnCode() != GEARMAN_SUCCESS)
    break;
}
?>
```

--------------------------------

### Core Gearman Job Server Options

Source: https://gearman.org/manual/job_server

Standard command-line arguments for configuring the gearmand process, including networking, logging, and threading settings.

```bash
 -b, --backlog=BACKLOG      Number of backlog connections for listen.
 -d, --daemon               Daemon, detach and run in the background.
 -f, --file-descriptors=FDS Number of file descriptors to allow for the process
                            (total connections will be slightly less). Default
                            is max allowed for user.
 -h, --help                 Print this help menu.
 -j, --job-retries=RETRIES  Number of attempts to run the job before the job
                            server removes it. Thisis helpful to ensure a bad
                            job does not crash all available workers. Default is
                            no limit.
 -l, --log-file=FILE        Log file to write errors and information to. Turning
                            this option on also forces the first verbose level
                            to be enabled.
 -L, --listen=ADDRESS       Address the server should listen on. Default is
                            INADDR_ANY.
 -p, --port=PORT            Port the server should listen on.
 -P, --pid-file=FILE        File to write process ID out to.
 -r, --protocol=PROTOCOL    Load protocol module.
 -q, --queue-type=QUEUE     Persistent queue type to use.
 -t, --threads=THREADS      Number of I/O threads to use. Default=0.
 -u, --user=USER            Switch to given user after startup.
 -v, --verbose              Increase verbosity level by one.
 -V, --version              Display the version of gearmand and exit.
```

--------------------------------

### Gearman Client Implementations for String Reversal

Source: https://gearman.org/examples/reverse

Client-side implementations for submitting a 'reverse' job to a Gearman server. Requires a running gearmand instance on localhost:4730.

```php
<?php

// Create our client object
$client = new GearmanClient();

// Add a server
$client->addServer(); // by default host/port will be "localhost" & 4730

echo "Sending job\n";

// Send reverse job
$result = $client->doNormal("reverse", "Hello!");
if ($result) {
  echo "Success: $result\n";
}
```

```go
package main

import (
    "log"
    "sync"
    "time"
    "github.com/mikespook/gearman-go/client"
)

func main() {
    var wg sync.WaitGroup
    // Set the autoinc id generator
    // You can write your own id generator
    // by implementing IdGenerator interface.
    // client.IdGen = client.NewAutoIncId()

    c, err := client.New("127.0.0.1:4730")
    if err != nil {
        log.Fatalln(err)
    }
    defer c.Close()
    c.ErrHandler = func(e error) {
        log.Println(e)
    }
    echo := []byte("Hello\x00 world")
    wg.Add(1)
    echomsg, err := c.Echo(echo, time.Second)
    if err != nil {
        log.Fatalln(err)
    }
    log.Println(string(echomsg))
    wg.Done()
    jobHandler := func(job *client.Job) {
        log.Printf("%s", job.Data)
        wg.Done()
    }
    handle := c.Do("reverse", echo, client.JOB_NORMAL, jobHandler)
    wg.Add(1)
    status, err := c.Status(handle, time.Second)
    if err != nil {
        log.Fatalln(err)
    }
    log.Printf("%t", status)

    wg.Wait()
}
```

```python
import gearman

def check_request_status(job_request):
    if job_request.complete:
        print "Job %s finished!  Result: %s - %s" % (job_request.job.unique, job_request.state, job_request.result)
    elif job_request.timed_out:
        print "Job %s timed out!" % job_request.unique
    elif job_request.state == JOB_UNKNOWN:
        print "Job %s connection failed!" % job_request.unique

gm_client = gearman.GearmanClient(['localhost:4730'])

completed_job_request = gm_client.submit_job("reverse", "Hello World!")
check_request_status(completed_job_request)
```

```javascript
var Gearman, client;

Gearman = require('gearman').Gearman;

client = new Gearman("localhost", 4730);

client.on('WORK_COMPLETE', function (job) {
    console.log('job completed, result:', job.payload.toString());
    return client.close();
});

client.connect(function () {
    return client.submitJob('reverse', 'Hello, World!');
});
```

--------------------------------

### Generate Client and Worker Certificate

Source: https://gearman.org/gearmand/gearmand/ssl

Create a private key and certificate for Gearman clients and workers.

```bash
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out gearman.key

openssl req -new -key gearman.key -subj "/CN=gearman-client" -out gearman.req

openssl x509 -req -in gearman.req -CA gearmand-ca.pem -CAkey gearmand-ca.key -CAcreateserial -out gearman.pem -days 730 -sha256
```

--------------------------------

### gearman_client_add_task

Source: https://gearman.org/gearmand/libgearman/gearman_client_add_task

Creates a task and adds it to the gearman_client_st. Execution begins upon calling gearman_client_run_tasks.

```APIDOC
## gearman_client_add_task

### Description
Creates a task and adds it to the given gearman_client_st. Execution of the task does not begin until gearman_client_run_tasks() is called.

### Signature
gearman_task_st *gearman_client_add_task(gearman_client_st *client, gearman_task_st *task, void *context, const char *function_name, const char *unique, const void *workload, size_t workload_size, gearman_return_t *ret_ptr)

### Parameters
- **client** (gearman_client_st *) - The client object.
- **task** (gearman_task_st *) - The task object.
- **context** (void *) - User-defined context.
- **function_name** (const char *) - The name of the function to execute.
- **unique** (const char *) - Unique identifier for the task.
- **workload** (const void *) - Data to be processed.
- **workload_size** (size_t) - Size of the workload.
- **ret_ptr** (gearman_return_t *) - Pointer to store return status.

### Return Value
Returns a pointer to the created gearman_task_st. Returns NULL on error and sets ret_ptr.
```

--------------------------------

### Implement a Gearman Resize Worker in PHP

Source: https://gearman.org/getting-started

This worker listens for 'resize' tasks, processes image blobs using Imagick, and returns the resized result.

```php
<?php
$worker= new GearmanWorker();
$worker->addServer();
$worker->addFunction("resize", "my_resize_function");
while ($worker->work());

function my_resize_function($job)
{
  $thumb = new Imagick();
  $thumb->readImageBlob($job->workload());

  if ($thumb->getImageHeight() > 600)
    $thumb->scaleImage(0, 600);
  else if ($thumb->getImageWidth() > 800)
    $thumb->scaleImage(800, 0);

  return $thumb->getImageBlob();
}
?>
```

--------------------------------

### gearman_client_create

Source: https://gearman.org/gearmand/libgearman/gearman_client

Initializes a gearman_client_st structure for use with libgearman client functions.

```APIDOC
## gearman_client_create

### Description
Creates or initializes a gearman_client_st structure. If a NULL pointer is passed, a structure is allocated.

### Signature
gearman_client_st *gearman_client_create(gearman_client_st *client)

### Parameters
- **client** (gearman_client_st*) - Optional - A pointer to a statically declared structure or NULL.

### Return Value
Returns a pointer to the initialized gearman_client_st, or NULL on allocation failure.
```

--------------------------------

### gearman_client_add_task_background

Source: https://gearman.org/gearmand/libgearman/gearman_client_add_task_background

Creates a background task and adds it to the gearman_client_st. Execution begins when gearman_client_run_tasks() is called.

```APIDOC
## gearman_task_st *gearman_client_add_task_background(gearman_client_st *client, gearman_task_st *task, void *context, const char *function_name, const char *unique, const void *workload, size_t workload_size, gearman_return_t *ret_ptr)

### Description
Creates a background task and adds it to the given gearman_client_st. Execution of the task does not begin until gearman_client_run_tasks() is called. If the unique value is not set, a unique identifier will be assigned.

### Parameters
- **client** (gearman_client_st *) - The client object to add the task to.
- **task** (gearman_task_st *) - The task structure to use.
- **context** (void *) - Application context for the task.
- **function_name** (const char *) - The name of the function to execute.
- **unique** (const char *) - A unique identifier for the task.
- **workload** (const void *) - The data to be processed.
- **workload_size** (size_t) - The size of the workload.
- **ret_ptr** (gearman_return_t *) - Pointer to store the return status.

### Return Value
Returns a pointer to the created gearman_task_st. On error, returns NULL and sets ret_ptr.
```

--------------------------------

### Submit a Gearman Client Job

Source: https://gearman.org/getting-started

Submits a foreground job to the job server using the contents of a file as the workload.

```bash
$ gearman -f wc < /etc/passwd
26
```

--------------------------------

### Client Job Submission Binary Protocol

Source: https://gearman.org/protocol

Illustrates the byte sequence for submitting a job and receiving a job handle.

```text
Client -> Job Server
00 52 45 51                \0REQ        (Magic)
00 00 00 07                7            (Packet type: SUBMIT_JOB)
00 00 00 0d                13           (Packet length)
72 65 76 65 72 73 65 00    reverse\0    (Function)
00                         \0           (Unique ID)
74 65 73 74                test         (Workload)

Job Server -> Client
00 52 45 53                \0RES        (Magic)
00 00 00 08                8            (Packet type: JOB_CREATED)
00 00 00 07                7            (Packet length)
48 3a 6c 61 70 3a 31       H:lap:1      (Job handle)
```

--------------------------------

### Include libgearman header

Source: https://gearman.org/gearmand/libgearman/gearman_actions_t

Required header for using libgearman functionality.

```c
#include <libgearman/gearman.h>
```

--------------------------------

### OPTION_REQ

Source: https://gearman.org/protocol

Sets an option for the connection in the job server.

```APIDOC
## OPTION_REQ

### Description
A client issues this to set an option for the connection. Returns OPTION_RES on success or ERROR on failure.

### Arguments
- Option name (e.g., "exceptions")
```

--------------------------------

### gearman_client_add_servers

Source: https://gearman.org/gearmand/libgearman/gearman_client_add_server

Adds a list of gearmand servers to the client.

```APIDOC
## gearman_client_add_servers

### Description
Parses a comma-separated list of servers and adds them to the client. The format is SERVER[:PORT][,SERVER[:PORT]]...

### Signature
gearman_return_t gearman_client_add_servers(gearman_client_st *client, const char *servers)

### Parameters
- **client** (gearman_client_st *) - The client structure to modify.
- **servers** (const char *) - A string containing one or more server addresses.
```

--------------------------------

### Implement a Gearman Client Logger in PHP

Source: https://gearman.org/examples/logging

A PHP class that wraps GearmanClient to send structured log messages to a background queue.

```php
<?php

/**
 * An extremely rudimentary logger that passes log messages through gearman
 */
class GearmanLogger {

    static $instances = array();

    /**
     * Fetch (and create if needed) an instance of this logger.
     *
     * @param string $server
     * @param int $port
     * @param string $queue
     * @return self
     */
    public static function getInstance($server = '127.0.0.1', $port = 4730, $queue = 'log') {
        $hash = $queue . $server . $port;
        if (!array_key_exists($hash, self::$instances)) {
            self::$instances[$hash] = new self($queue, $server, $port);
        }

        return self::$instances[$hash];
    }

    /** @var GearmanClient */
    private $gmc;
    /** @var string */
    private $queue;

    public function __construct($queue, $server, $port) {
        $this->gmc   = new GearmanClient();
        $this->queue = $queue;
        $this->gmc->addServer($server, $port);
    }

    /**
     * Log a message
     *
     * @param mixed $message
     * @param string $level
     */
    public function log($message, $level = 'DEBUG') {
        $this->gmc->doBackground($this->queue, json_encode(array(
            'level'   => $level,
            'message' => $message,
            'ts'      => time(),
            'host'    => gethostname(),
        )));
    }

    /**
     * Log a warning
     * @param mixed $message
     */
    public function warn($message) {
        $this->log($message, 'WARN');
    }

    /**
     * Log an error
     * @param mixed $message
     */
    public function error($message) {
        $this->log($message, 'ERROR');
    }

}

GearmanLogger::getInstance()->log('A debug message');
GearmanLogger::getInstance()->warn('A warning');
GearmanLogger::getInstance()->error('A serious problem');
GearmanLogger::getInstance()->error(array('an array?', 'interesting...', 'structured log messages!'));
```

```java
// todo
```

```perl
// todo
```

--------------------------------

### libmemcached Persistent Queue Options

Source: https://gearman.org/manual/job_server

Configuration flag for using libmemcached as a persistent queue backend.

```bash
 --libmemcached-servers=SERVER_LIST List of Memcached servers to use.
```

--------------------------------

### Execute a task with a reducer function

Source: https://gearman.org/gearmand/libgearman/examples

Uses gearman_execute_by_partition to map values using 'word_split' and reduce them with 'count'.

```c
/*
  Example code to show how to send a string to a function called "word_split", reduce
  each chunk with the function count, and then print the results.
*/

#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <libgearman/gearman.h>

int main(void)
{
  gearman_client_st *client= gearman_client_create(NULL);

  gearman_return_t ret= gearman_client_add_server(client, "localhost", 0);
  if (gearman_failed(ret))
  {
    return EXIT_FAILURE;
  }

  gearman_argument_t value= gearman_argument_make(0, 0, "this dog does not hunt", strlen("this dog does not hunt"));

  gearman_task_st *task= gearman_execute_by_partition(client, 
                                                      "word_split", strlen("word_split"),
                                                      "count", strlen("count"),  // function
                                                      NULL, 0,  // no unique value provided
                                                      NULL,
                                                      &value, 0);

  if (task == NULL) // If gearman_execute() can return NULL on error
  {
    fprintf(stderr, "Error: %s\n", gearman_client_error(client));
    gearman_client_free(client);
    return EXIT_FAILURE;
  }

  // Make sure the task was run successfully
  if (gearman_success(gearman_task_return(task)))
  {
    // Make use of value
    gearman_result_st *result= gearman_task_result(task);
    printf("%.*s\n", (int)gearman_result_size(result), gearman_result_value(result));
  }

  gearman_client_free(client);

  return EXIT_SUCCESS;
}
```

--------------------------------

### Gearman Protocol Overview

Source: https://gearman.org/protocol

Basic definition of the Gearman protocol structure and default port configuration.

```text
Gearman Protocol
----------------

The Gearman protocol operates over TCP, port 4730 by default. It
previously operated on port 7003, but this conflicted with the AFS
port range and the new port (4730) was assigned by IANA. Communication
happens between either a client and job server, or between a worker
and job server. In either case, the protocol consists of packets
containing requests and responses. All packets sent to a job server
are considered requests, and all packets sent from a job server are
considered responses. A simple configuration may look like:

----------     ----------     ----------     ----------
| Client |     | Client |     | Client |     | Client |
----------     ----------     ----------     ----------
     \             /              \             /
      \           /                \           /
      --------------               --------------
      | Job Server |               | Job Server |
      --------------               --------------
            |                            |
    ----------------------------------------------
    |              |              |              |
----------     ----------     ----------     ----------
| Worker |     | Worker |     | Worker |     | Worker |
----------     ----------     ----------     ----------

Initially, the workers register functions they can perform with each
job server. Clients will then connect to a job server and issue a
request to a job to be run. The job server then notifies each worker
that can perform that job (based on the function it registered) that
a new job is ready. The first worker to wake up and retrieve the job
will then execute it.

All communication between workers or clients and the job server
are binary. There is also a line-based text protocol used by
administrative clients. This part of the protocol is text based so a
custom administrative utility is not required (instead, 'telnet' or
'nc' can be used). This is documented under "Administrative Protocol".
```

--------------------------------

### Worker Registration Binary Protocol

Source: https://gearman.org/protocol

Demonstrates the byte sequence for a worker to register for the 'reverse' function.

```text
Worker -> Job Server
00 52 45 51                \0REQ        (Magic)
00 00 00 01                1            (Packet type: CAN_DO)
00 00 00 07                7            (Packet length)
72 65 76 65 72 73 65       reverse      (Function)
```

--------------------------------

### gearman_client_do_background

Source: https://gearman.org/gearmand/libgearman/gearman_client_do_background

Executes a single background request to the gearmand server.

```APIDOC
## gearman_client_do_background

### Description
Executes a single request to the gearmand server in the background. If job_handle is provided, it will be populated with the job handle of the created task.

### Signature
gearman_return_t gearman_client_do_background(gearman_client_st *client, const char *function_name, const char *unique, const void *workload, size_t workload_size, char *job_handle)

### Parameters
- **client** (gearman_client_st *) - The client structure.
- **function_name** (const char *) - The name of the function to execute.
- **unique** (const char *) - A unique identifier for the job.
- **workload** (const void *) - The data to be processed.
- **workload_size** (size_t) - The size of the workload.
- **job_handle** (char *) - Buffer to store the job handle (must be size GEARMAN_JOB_HANDLE_SIZE).

### Return Value
- **gearman_return_t** - Returns the status of the operation.
```

--------------------------------

### version

Source: https://gearman.org/protocol

Retrieves the version of the Gearman server.

```APIDOC
## version

### Description
Sends back the version string of the server.
```

--------------------------------

### Inspect Gearman Extension with Reflection

Source: https://gearman.org/php-client-libraries/extension/reflection

Uses the ReflectionExtension class to iterate through all classes and methods provided by the Gearman extension.

```php
<?php
$e = new ReflectionExtension('gearman');
print "<?php\n\n// Gearman Version: " . $e->getVersion() . "\n\n";
foreach ($e->getClasses() as $c) {
  print 'class ' . $c->name . " {\n";
  foreach ($c->getMethods() as $m) {
    print '  ';
    if ($m->isPublic()) {
        print 'public';
    } elseif ($m->isProtected()) {
        print 'protected';
    } elseif ($m->isPrivate()) {
        print 'private';
    }
    print ' function ' . $m->name . '(';
    $sep = '';
    foreach ($m->getParameters() as $p) {
      print $sep;
      $sep = ', ';
      if ($p->isOptional())
        print '$' . $p->name . ' = null' ;
      else
        print '$' . $p->name;
    }
    print "){}\n";
  }
  print "}\n\n";
}
```

--------------------------------

### Implement a Gearman worker in Python

Source: https://gearman.org/examples/reverse

Uses the python-gearman library to register a task and enter a work loop.

```python
import gearman

gm_worker = gearman.GearmanWorker(['localhost:4730'])

def task_listener_reverse(gearman_worker, gearman_job):
    print 'Reversing string: ' + gearman_job.data
    return gearman_job.data[::-1]

# gm_worker.set_client_id is optional
gm_worker.set_client_id('python-worker')
gm_worker.register_task('reverse', task_listener_reverse)

# Enter our work loop and call gm_worker.after_poll() after each time we timeout/see socket activity
gm_worker.work()
```

--------------------------------

### Monitor Queue Table in Drizzle

Source: https://gearman.org/manual/job_server

Connects to the Drizzle database to inspect the state of the job queue.

```sql
> drizzle
Welcome to the Drizzle client..  Commands end with ; or \g.
Your Drizzle connection id is 6
Server version: 2009.06.1014-eday-dev Source distribution

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

drizzle> SELECT * FROM test.queue;
Empty set (0 sec)
```

--------------------------------

### Administrative Commands

Source: https://gearman.org/gearmand/protocol/text

A list of commands supported by the Gearmand TEXT protocol for server administration.

```APIDOC
## Gearmand TEXT Protocol Commands

### workers
Return the status of all attached workers.

### status
Return the status of all current jobs.

### cancel job
Cancel a job that has been queued.

### show jobs
Show all current job ids.

### show unique jobs
List all of the unique job ids that the server currently is processing or waiting to process.

### create
Create a function (i.e. queue).

### drop
Drop a function (i.e. queue).

### maxqueue
Set maxqueue.

### getpid
Return the process id of the server.

### verbose
Return the verbose level of the server.

### version
Version number of server.

### prioritystatus
Queued jobs status by priority. Counts are reported per function.
```

--------------------------------

### Client callback setter functions

Source: https://gearman.org/gearmand/libgearman/gearman_actions_t

Functions to register callbacks for specific client task execution states.

```c
void gearman_client_set_workload_fn(gearman_client_st *client, gearman_workload_fn *function)
void gearman_client_set_created_fn(gearman_client_st *client, gearman_created_fn *function)
void gearman_client_set_data_fn(gearman_client_st *client, gearman_data_fn *function)
void gearman_client_set_warning_fn(gearman_client_st *client, gearman_warning_fn *function)
void gearman_client_set_status_fn(gearman_client_st *client, gearman_universal_status_fn *function)
void gearman_client_set_complete_fn(gearman_client_st *client, gearman_complete_fn *function)
void gearman_client_set_exception_fn(gearman_client_st *client, gearman_exception_fn *function)
void gearman_client_set_fail_fn(gearman_client_st *client, gearman_fail_fn *function)
void gearman_client_clear_fn(gearman_client_st *client)
const char *gearman_client_do_job_handle(gearman_client_st *client)
```

--------------------------------

### libdrizzle Persistent Queue Options

Source: https://gearman.org/manual/job_server

Configuration flags for using libdrizzle as a persistent queue backend.

```bash
 --libdrizzle-host=HOST         Host of server.
 --libdrizzle-port=PORT         Port of server.
 --libdrizzle-uds=UDS           Unix domain socket for server.
 --libdrizzle-user=USER         User name for authentication.
 --libdrizzle-password=PASSWORD Password for authentication.
 --libdrizzle-db=DB             Database to use.
 --libdrizzle-table=TABLE       Table to use.
 --libdrizzle-mysql             Use MySQL protocol.
```

--------------------------------

### Configure compiler environment

Source: https://gearman.org/gearmand/build/centos5-8

Set the environment variables to use GCC 4.4 for the build process.

```bash
yum install gcc44 gcc-c++
export CC=”gcc44”
export CXX=”g++44”
```
Tokens:
Raw