Gearman分佈式任務處理系統（八）開發講解

這篇重點介紹C-Lib庫及client和worker的開發，以0.14版libgearman for C來說解

Client API

 

client初始化&析構

gearman_client_st *gearman_client_create(gearman_client_st *client)

void gearman_client_free(gearman_client_st *client)

gearman_return_t gearman_client_add_server(gearman_client_st *client, const char *host, in_port_t port);

gearman_return_t gearman_client_add_servers(gearman_client_st *client, const char *servers); (一次添加多個gearman job-server)

 

同步操做

void * gearman_client_do(gearman_client_st *client, const char *function_name, const char *unique, const void *workload, size_t workload_size, size_t *result_size, gearman_return_t *ret_ptr);

其中：

i. unique: 的做用是client添加job給worker的時候的一個惟一標識，可選，默認是NULL

ii. workload & workload_size指代執行任務的詳細參數及其大小

iii. result_size [out]，指代返回數據的大小

iv. ret_ptr [out], 指代gearman的返回status，如下是官方對於返回status的一些說明：

In the case of GEARMAN_WORK_DATA, GEARMAN_WORK_WARNING, or GEARMAN_WORK_STATUS, the caller should take any actions to handle the event and then call this function again. This may happen multiple times until a GEARMAN_WORK_ERROR, GEARMAN_WORK_FAIL, or GEARMAN_SUCCESS (work complete) is returned. For GEARMAN_WORK_DATA or GEARMAN_WORK_WARNING, the result_size will be set to the intermediate data chunk being returned and an allocated data buffer will be returned. For GEARMAN_WORK_STATUS, the caller can use gearman_client_do_status() to get the current tasks status.

總而言之，只有GEARMAN_WORK_ERROR/GEARMAN_WORK_FAIL/GEARMAN_SUCCESS纔是三個最終的返回結果，其餘的只是臨時中間結果，須要進一步調用接受結果的函數(感受中間結果只有在異步調用過程當中纔會出現)

v. 輸出是返回數據的起始地址，一旦用戶用完以後，必須free，不然會出現內存泄露。

 

void gearman_set_timeout(gearman_universal_st *gearman, int timeout);

設置gearman_client_do多長時調用無返回則超時時間

 

異步callback操做

Gearman經過使用gearman_client_add_task()來望gearman_client_st中添加task，經過gearman_client_set_created_fn() / gearman_client_set_complete_fn()等來註冊callback function，經過gearman_client_run_tasks()來運行gearman_client_st中的task。

 

異步background操做

系統在background運行job，client按期得到job運行結果，若是成功則返回，反之則繼續等待。

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);

i. job_handle [out]: 一個job的標識符

ii. 輸出：返回狀態

* gearman_return_t gearman_client_job_status(gearman_client_st *client, gearman_job_handle_t job_handle, bool *is_known, bool * is_running, uint32_t *numerator, uint32_t *denominator);

* 用戶得到在background執行的job的狀態

i. is_known [out]: Optional parameter to store the known status in

ii. is_running [out]: Optional parameter to store the running status in

iii. numerator [out]: Optional parameter to store the numerator in

iv. denominator [out]: Optional parameter to store the denominator in

PS: 好像background操做不怎麼好使，不知道如何經過得到background的運行結果，這個是我一直困惑的

 

gearman_client_st的一些屬性

gearman_client_st一共有如下3種運行屬性：

i. GEARMAN_CLIENT_NON_BLOCKING: client運行在non-blocking mode

ii. GEARMAN_CLIENT_FREE_TASKS: 在task執行完成以後，自動的釋放task

iii. GEARMAN_CLIENT_UNBUFFERED_RESULT: Allow the client to read data in chunks rather than have the library buffer the entire data result and pass that back。

能夠經過函數gearman_client_add_options() / gearman_client_remove_options() / gearman_client_has_option() 等進行屬性添加/刪除/判斷等

 

Worker API

/**
 * Initialize a worker structure. Always check the return value even if passing
 * in a pre-allocated structure. Some other initialization may have failed. It
 * is not required to memset() a structure before providing it.
 *
 * @param[in] worker Caller allocated structure, or NULL to allocate one.
 * @return On success, a pointer to the (possibly allocated) structure. On
 *  failure this will be NULL.
 */
GEARMAN_API
gearman_worker_st *gearman_worker_create(gearman_worker_st *worker);


/**
 * Free resources used by a worker structure.
 *
 * @param[in] worker Structure previously initialized with
 *  gearman_worker_create() or gearman_worker_clone().
 */
GEARMAN_API
void gearman_worker_free(gearman_worker_st *worker);


/**
 * Add a job server to a worker. This goes into a list of servers that can be
 * used to run tasks. No socket I/O happens here, it is just added to a list.
 *
 * @param[in] worker Structure previously initialized with
 *  gearman_worker_create() or gearman_worker_clone().
 * @param[in] host Hostname or IP address (IPv4 or IPv6) of the server to add.
 * @param[in] port Port of the server to add.
 * @return Standard gearman return value.
 */
GEARMAN_API
gearman_return_t gearman_worker_add_server(gearman_worker_st *worker,
                                           const char *host, in_port_t port);


/**
 * Add a list of job servers to a worker. The format for the server list is:
 * SERVER[:PORT][,SERVER[:PORT]]...
 * Some examples are:
 * 10.0.0.1,10.0.0.2,10.0.0.3
 * localhost LIBGEARMAN_BITFIELD234,jobserver2.domain.com:7003,10.0.0.3
 *
 * @param[in] worker Structure previously initialized with
 *  gearman_worker_create() or gearman_worker_clone().
 * @param[in] servers Server list described above.
 * @return Standard gearman return value.
 */
GEARMAN_API
gearman_return_t gearman_worker_add_servers(gearman_worker_st *worker,
                                            const char *servers);
                                            
/**
 * Register and add callback function for worker. To remove functions that have
 * been added, call gearman_worker_unregister() or
 * gearman_worker_unregister_all().
 *
 * @param[in] worker Structure previously initialized with
 *  gearman_worker_create() or gearman_worker_clone().
 * @param[in] function_name Function name to register.
 * @param[in] timeout Optional timeout (in seconds) that specifies the maximum
 *  time a job should. This is enforced on the job server. A value of 0 means
 *  an infinite time.
 * @param[in] function Function to run when there is a job ready.
 * @param[in] context Argument to pass into the callback function.
 * @return Standard gearman return value.
 */
GEARMAN_API
gearman_return_t gearman_worker_add_function(gearman_worker_st *worker,
                                             const char *function_name,
                                             uint32_t timeout,
                                             gearman_worker_fn *function,
                                             void *context);


/**
 * Wait for a job and call the appropriate callback function when it gets one.
 *
 * @param[in] worker Structure previously initialized with
 *  gearman_worker_create() or gearman_worker_clone().
 * @return Standard gearman return value.
 */
GEARMAN_API
gearman_return_t gearman_worker_work(gearman_worker_st *worker);

 

/**
 * See gearman_universal_set_timeout() for details.
 */
GEARMAN_API
void gearman_worker_set_timeout(gearman_worker_st *worker, int timeout);

 

開發實例

下面這個實例程序是，jfy_client發送test，jfy_worker返回test->result

 

/*
  gearman client 測試程序
  gcc -o jfy_client jfy_client.c -I/usr/local/gearman/include -L/usr/local/gearman/lib -lgearman
  ./jfy_client "this is a test"
*/

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

#include <libgearman/gearman.h>

static void usage(char *name);

int main(int argc, char *argv[])
{
  int i;
  gearman_return_t ret;
  gearman_client_st client;
  char *result;
  size_t result_size;
  uint32_t numerator;
  uint32_t denominator;

  char *host = "localhost", *port = "4730";

  if (gearman_client_create(&client) == NULL)
  {
    fprintf(stderr, "Memory allocation failure on client creation\n");
    exit(1);
  }

  gearman_client_set_options(&client, GEARMAN_CLIENT_FREE_TASKS);
  gearman_client_set_timeout(&client, 15000);

  ret= gearman_client_add_server(&client, host, atoi(port));
  if (ret != GEARMAN_SUCCESS)
  {
    fprintf(stderr, "%s\n", gearman_client_error(&client));
    exit(1);
  }

  for (i=0;i<10;i++)
  {
    result= (char *)gearman_client_do(&client, "jfytest", NULL,
                                      (void *)argv[1],
                                      (size_t)strlen(argv[1]),
                                      &result_size, &ret);
    if (ret == GEARMAN_WORK_DATA)
    {
      printf("Data=%.*s\n", (int)result_size, result);
      free(result);
    }
    else if (ret == GEARMAN_WORK_STATUS)
    {
      gearman_client_do_status(&client, &numerator, &denominator);
      printf("Status: %u/%u\n", numerator, denominator);
    }
    else if (ret == GEARMAN_SUCCESS)
    {
      char result2[1024];
      strncpy(result2, result, result_size);
      result2[result_size] = 0;
      printf("result_size=%d,result=%s=\n", (int)result_size, result2);
      free(result);
    }
    else if (ret == GEARMAN_WORK_FAIL)
      fprintf(stderr, "Work failed\n");
    else if (ret == GEARMAN_TIMEOUT)
    {
      fprintf(stderr, "Work timeout\n");
    } else {
      fprintf(stderr, "%d,%s\n", gearman_client_errno(&client), gearman_client_error(&client));
    }
    printf("sleep 5s ...\n");
    sleep(5);
  }

  gearman_client_free(&client);

  return 0;
}

 

/*
  gearman worker 測試程序
  gcc -o jfy_worker jfy_worker2.c -I/usr/local/gearman/include -L/usr/local/gearman/lib -lgearman
  ./jfy_worker ./jfy_worker.tr
*/

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

#include <libgearman/gearman.h>

static void *jfytest(gearman_job_st *job, void *context, size_t *result_size,
                     gearman_return_t *ret_ptr);

int main(int argc, char *argv[])
{
  gearman_return_t ret;
  gearman_worker_st worker;

  char *host = "localhost", *port = "4730";

  if (gearman_worker_create(&worker) == NULL)
  {
    printf("%s\n", gearman_worker_error(&worker));
    exit(1);
  }

  ret= gearman_worker_add_server(&worker, host, atoi(port));
  if (ret != GEARMAN_SUCCESS)
  {
    printf("%s\n", gearman_worker_error(&worker));
    exit(1);
  }

  ret= gearman_worker_add_function(&worker, "jfytest", 0, jfytest, NULL);
  if (ret != GEARMAN_SUCCESS)
  {
    printf("%s\n", gearman_worker_error(&worker));
    exit(1);
  }

  printf("wait job ...\n");
  while (1)
  {
    ret= gearman_worker_work(&worker);
    if (ret != GEARMAN_SUCCESS)
    {
      printf("%s\n", gearman_worker_error(&worker));
      break;
    }
  }

  gearman_worker_free(&worker);

  return 0;
}

static void *jfytest(gearman_job_st *job, void *context, size_t *result_size,
                     gearman_return_t *ret_ptr)
{
  const uint8_t *workload;
  char *request,*result;

  workload= gearman_job_workload(job);
  *result_size= gearman_job_workload_size(job);

  request= malloc(1024);
  if (result == NULL)
  {
    printf("malloc request:%d\n", errno);
    *ret_ptr= GEARMAN_WORK_FAIL;
    return NULL;
  }

  snprintf((char *)request, *result_size+1, "%s", (char *)workload);
  printf("job=%s,result_size=%d,request=%s\n", gearman_job_handle(job),*result_size,request);

  result= malloc(1024);
  if (result == NULL)
  {
    printf("malloc result:%d\n", errno);
    *ret_ptr= GEARMAN_WORK_FAIL;
    return NULL;
  }

  *ret_ptr= GEARMAN_SUCCESS;

  sprintf((char *)result, "%s->result", (char *)request);
  *result_size= strlen((char *)result);

  printf("job=%s,result_size=%d,result=%s\n", gearman_job_handle(job),*result_size,result);

  return result;
}

 

 

下面的實例是PHP程序，客戶端發送"hello!"

worker端是兩個程序，一個是阻塞方式的，一個是非阻塞方式的

<?php
/*
 * send "Hello!"
 */

echo "Starting\n";

# Create our client object.
$gmclient= new GearmanClient();

# Add default server (localhost).
$gmclient->addServer();

echo "Sending job\n";

# Send reverse job
do
{
  $result= $gmclient->do("reverse", "Hello!");
  # Check for various return packets and errors.
  switch($gmclient->returnCode())
  {
    case GEARMAN_WORK_DATA:
      echo "Data: $result\n";
      break;
    case GEARMAN_WORK_STATUS:
      list($numerator, $denominator)= $gmclient->doStatus();
      echo "Status: $numerator/$denominator complete\n";
      break;
    case GEARMAN_SUCCESS:
      break;
    default:
      echo "RET: " . $gmclient->returnCode() . "\n";
      exit;
  }
}
while($gmclient->returnCode() != GEARMAN_SUCCESS);
echo "Success: $result\n";

?>

<?php
/*
 * 阻塞方式Worker，處理"Hello!"轉換爲"!olleH"
 */

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();
$gmworker->setTimeout(5000);

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";
while($gmworker->work())
{
  if ($gmworker->returnCode() != GEARMAN_SUCCESS)
  {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    break;
  }
  echo "receve and proced a job!";
}

function reverse_fn($job)
{
  echo "Received job: " . $job->handle() . "\n";

  $workload= $job->workload();
  $workload_size= $job->workloadSize();

  echo "Workload: $workload ($workload_size)\n";

  # This status loop is not needed, just showing how it works
  for ($x= 0; $x < $workload_size; $x++)
  {
    echo "Sending status: $x/$workload_size complete\n";
    /*
    $job->sendStatus($x, $workload_size);
    sleep(1);
    */
  }

  $result= strrev($workload);
  echo "Result: $result\n";

  # Return what we want to send back to the client.
  return $result;
}

# A much simpler and less verbose version of the above function would be:
function reverse_fn_fast($job)
{
  return strrev($job->workload());
}

?>

 

<?php
/*
 * 非阻塞方式Worker，處理"Hello!"轉換爲"!olleH"
 */

echo "Starting\n";

# Create our worker object.
$gmworker= new GearmanWorker();
$gmworker->setTimeout(1000);
$gmworker->addOptions(GEARMAN_WORKER_NON_BLOCKING); # Make the worker non-blocking

# Add default server (localhost).
$gmworker->addServer();

# Register function "reverse" with the server. Change the worker function to
# "reverse_fn_fast" for a faster worker with no output.
$gmworker->addFunction("reverse", "reverse_fn");

print "Waiting for job...\n";

while ( ($ret = $gmworker->work()) || $gmworker->returnCode() == GEARMAN_IO_WAIT || $gmworker->returnCode() == GEARMAN_NO_JOBS) {
  echo "return_code: " . $gmworker->returnCode() . "\n";
  if ($gmworker->returnCode() == GEARMAN_SUCCESS) {
    continue;
  }
  if ( !$gmworker->wait() ) {
    echo "return_code: " . $gmworker->returnCode() . "\n";
    if ($gmworker->returnCode() == GEARMAN_NO_ACTIVE_FDS) {
      # We are not connected to any servers, so wait a bit before
      # trying to reconnect. sleep(5);
      continue;
    }
    break;
  }
}

function reverse_fn($job)
{
  echo "Received job: " . $job->handle() . "\n";

  $workload= $job->workload();
  $workload_size= $job->workloadSize();

  echo "Workload: $workload ($workload_size)\n";

  # This status loop is not needed, just showing how it works
  for ($x= 0; $x < $workload_size; $x++)
  {
    echo "Sending status: $x/$workload_size complete\n";
    /*
    $job->sendStatus($x, $workload_size);
    sleep(1);
    */
  }

  $result= strrev($workload);
  echo "Result: $result\n";

  # Return what we want to send back to the client.
  return $result;
}

# A much simpler and less verbose version of the above function would be:
function reverse_fn_fast($job)
{
  return strrev($job->workload());
}

?>