Fix API around usage/how to extend gearman_execute().

docs/conf.py.in

@@ -279,7 +279,6 @@ man_pages = [
   ('libgearman/gearman_client_st', 'gearman_client_timeout', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_client_wait', 'gearman_client_wait', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_execute', 'gearman_execute', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
-  ('libgearman/gearman_execute_map_reduce', 'gearman_execute_map_reduce', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_job_handle_t', 'gearman_job_handle_t', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_job_st', 'gearman_job_free', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_job_st', 'gearman_job_free_all', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
@@ -335,6 +334,13 @@ man_pages = [
   ('libgearman/gearman_verbose_t', 'gearman_verbose_name', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_verbose_t', 'gearman_verbose_t', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_version', 'gearman_version', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
+  ('libgearman/gearman_work_t', 'gearman_work_t', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
+  ('libgearman/gearman_work_t', 'gearman_work', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
+  ('libgearman/gearman_work_t', 'gearman_work_epoch', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
+  ('libgearman/gearman_work_t', 'gearman_work_background', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
+  ('libgearman/gearman_work_t', 'gearman_work_reducer', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
+  ('libgearman/gearman_work_t', 'gearman_work_epoch_with_reducer', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
+  ('libgearman/gearman_work_t', 'gearman_work_background_with_reducer', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_worker_add_server', 'gearman_worker_add_server', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_worker_add_server', 'gearman_worker_add_servers', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),
   ('libgearman/gearman_worker_add_server', 'gearman_worker_remove_servers', u'Gearmand Documentation, http://gearman.info/', [u'Data Differential http://datadifferential.com/'], 3),

docs/glossary.rst

@@ -1,5 +1,6 @@
-========
-Glossary
+.. _glossary:
+
+Glossary 
 ========
 
 
@@ -17,3 +18,12 @@ Glossary
    job
       A job represents a task once it is sent to worker. It is represented as :c:type:`gearman_job_st`.
 
+   function 
+      A "subprogram" that takes a set of parameters and returns a result (or just just a status). Functions are defined for workers.
+  
+   reducer 
+      A function that takes a piece of data from mapper and returns a value that will be seent to an aggregator function.
+
+   aggregator 
+      A function which takes data and compiles it into a single return value. Aggregator functions are defined by :c:type:`gearman_aggregator_fn`.
+

docs/include.am

@@ -81,7 +81,6 @@ man3_MANS+= \
 	    docs/man/gearman_client_wait.3 \
 	    docs/man/gearman_continue.3 \
 	    docs/man/gearman_execute.3 \
-	    docs/man/gearman_execute_map_reduce.3 \
 	    docs/man/gearman_failed.3 \
 	    docs/man/gearman_job_free.3 \
 	    docs/man/gearman_job_free_all.3 \
@@ -166,6 +165,13 @@ man3_MANS+= \
 	    docs/man/gearman_worker_unregister_all.3 \
 	    docs/man/gearman_worker_wait.3 \
 	    docs/man/gearman_worker_work.3 \
+	    docs/man/gearman_work.3 \
+	    docs/man/gearman_work_background.3 \
+	    docs/man/gearman_work_background_with_reducer.3 \
+	    docs/man/gearman_work_epoch.3 \
+	    docs/man/gearman_work_epoch_with_reducer.3 \
+	    docs/man/gearman_work_reducer.3 \
+	    docs/man/gearman_work_t.3 \
 	    docs/man/libgearman.3
 
 if HAVE_SPHINX

docs/index.rst

@@ -119,9 +119,10 @@ Structures
    libgearman/gearman_task_st
    libgearman/gearman_worker_st 
    libgearman/gearman_job_handle_t
-   libgearman/gearman_argument_t
-   libgearman/gearman_string_t
-   libgearman/gearman_result_t
+   libgearman/gearman_argument_t 
+   libgearman/gearman_string_t 
+   libgearman/gearman_result_t 
+   libgearman/gearman_work_t
 
 
 *****

docs/libgearman/gearman_argument_t.rst

@@ -10,7 +10,7 @@ SYNOPSIS
 
 .. c:type:: gearman_argument_t
 
-.. c:function:: gearman_argument_t gearman_argument_make(const char *value, size_t value_size)
+.. c:function:: gearman_argument_t gearman_argument_make(const char *name, const size_t name_length, const char *value, const size_t value_size)
 
 Compile and link with -lgearman
 

docs/libgearman/gearman_execute.rst

@@ -11,8 +11,6 @@ SYNOPSIS
 
 .. c:function:: gearman_task_st *gearman_execute(gearman_client_st *client, const char *function_name, size_t function_name_length, const char *unique_str, size_t unique_length, gearman_work_t *workload, gearman_argument_t *arguments)
 
-.. c:type:: gearman_work_t
-
 Link with -lgearman
 
 -----------
@@ -21,9 +19,19 @@ DESCRIPTION
 
 :c:func:`gearman_execute()` is used to create a new :c:type:`gearman_task_st` that is executed against the function that is found via the function_name argument. 
 
-:c:type:`gearman_work_t` can be used to describe the work that will be executed. The argument unique_str is optional, but if supplied it is used for coalescence by :program:`gearmand`.
+:c:type:`gearman_work_t` can be used to describe the work that will be
+executed, it is built with :c:func:`gearman_argument_make()`.  The argument
+unique_str is optional, but if supplied it is used for coalescence by
+:program:`gearmand`.
+
+:c:type:`gearman_argument_t` is the work that the :term:`client` will send
+the to the server
+
+If :c:func:`gearman_execute()` is given a :c:type:`gearman_work_t` that has been built with a reducer, it takes the :c:type:`gearman_argument_t` and executs it against a :term:`function` as it normally would, but it tells the function to then process the results through a :term:`reducer` function that the :c:type:`gearman_work_t` was created with.
+
+What is happening is that the function is mappping work up into units, and then sending each of them to the reducer function. Once all work is completed, the mapper function will aggregate the work and return a result.
 
-:c:type:`gearman_argument_t` is the worked that the client will send the to the server
+If any of the units of work error, the job will be aborted. The resulting value will be stored in the :c:type:`gearman_task_st`.
 
 ------------
 RETURN VALUE

docs/libgearman/gearman_execute_map_reduce.rst

@@ -1,46 +0,0 @@
-==========================
-Executing a map/reduce job
-==========================
-
-
---------
-SYNOPSIS
---------
-
-#include <libgearman/gearman.h>
-
-.. c:function:: gearman_task_st *gearman_execute_map_reduce(gearman_client_st *client, const char *mapper_name, const size_t mapper_length, const char *reducer_name, const size_t reducer_length, const char *unique_str, const size_t unique_length, gearman_work_t *workload, gearman_argument_t *arguments);
-
-Link with -lgearman
-
------------
-DESCRIPTION
------------
-
-gearman_client_execute_reduce() takes a given :c:type:`gearman_argument_t` and executs it against a :c:type:`gearman_mapper_fn` function. This function is specified via the 
-mapper_name argument. The mapper function will then break the work up into units, and send each of them to the function named reducer function. Once all work is completed, the mapper function will aggregate the work and return a result.
-
-If any of the units of work error, the job will be aborted. The resulting value will be stored in the :c:type:`gearman_task_st`.
-
-
-------------
-RETURN VALUE
-------------
-
-:c:func:`gearman_client_execute_reduce()` returns a pointer to a :c:type:`gearman_task_st`. On error a NULL will be returned. The error can be examined with :c:func:`gearman_client_error()`.
-
-----
-HOME
-----
-
-
-To find out more information please check:
-`https://launchpad.net/gearmand <https://launchpad.net/gearmand>`_
-
-
---------
-SEE ALSO
---------
-
-:manpage:`gearmand(8)` :manpage:`libgearman(3)` :manpage:`gearman_strerror(3)` :manpage:`gearman_client_error`
-

docs/libgearman/gearman_work_t.rst

@@ -0,0 +1,47 @@
+====================================
+Describing Workload (gearman_work_t)
+====================================
+
+--------
+SYNOPSIS
+--------
+
+#include <libgearman/gearman.h>
+
+.. c:type:: gearman_work_t
+
+.. c:function:: gearman_work_t gearman_work(gearman_job_priority_t priority);
+
+.. c:function:: gearman_work_t gearman_work_epoch(time_t epoch, gearman_job_priority_t priority);
+
+.. c:function:: gearman_work_t gearman_work_background(gearman_job_priority_t priority);
+
+.. c:function:: gearman_work_t gearman_work_reducer(const char *name, size_t name_length, gearman_job_priority_t priority);
+
+.. c:function:: gearman_work_t gearman_work_epoch_with_reducer(time_t epoch, gearman_job_priority_t priority, const char *name, size_t name_length);
+
+.. c:function:: gearman_work_t gearman_work_background_with_reducer(gearman_job_priority_t priority, const char *name, size_t name_length);
+
+.. c:function:: void gearman_work_set_context(gearman_work_t *, void *);
+
+Compile and link with -lgearman
+
+-----------
+DESCRIPTION
+-----------
+
+:c:type:`gearman_work_t` describe work for :c:func:`gearman_execute()`.
+
+:c:func:`gearman_work()` creates a :c:type:`gearman_work_t` with a priority.
+
+:c:func:`gearman_work_epoch()` creates a :c:type:`gearman_work_t` which tells :c:func:`gearman_execute()` to execute the workload at the time specified by epoch.
+
+:c:func:`gearman_work_background()` creates a :c:type:`gearman_work_t` which tells :c:func:`gearman_execute()` to execute the workload as a background job.
+
+:c:func:`gearman_work_reducer()`, :c:func:`gearman_work_reducer()`, and :c:func:`gearman_work_reducer()`, do the same as there non-reducer counterparts but specify a reducer function that will be executed on the result of the function specified for :c:func:`gearman_execute()`.
+
+--------
+SEE ALSO
+--------
+
+:manpage:`gearmand(8)` :manpage:`libgearman(3)` :manpage:`gearman_execute()`

docs/man/gearadmin.1

@@ -1,4 +1,4 @@
-.TH "GEARADMIN" "1" "June 14, 2011" "0.21" "Gearmand"
+.TH "GEARADMIN" "1" "June 15, 2011" "0.21" "Gearmand"
 .SH NAME
 gearadmin \- Gearmand Documentation, http://gearman.info/
 .

docs/man/gearman.1

@@ -1,4 +1,4 @@
-.TH "GEARMAN" "1" "June 14, 2011" "0.21" "Gearmand"
+.TH "GEARMAN" "1" "June 15, 2011" "0.21" "Gearmand"
 .SH NAME
 gearman \- Gearmand Documentation, http://gearman.info/
 .