=========================
Creating background tasks
=========================

-------- 
SYNOPSIS 
--------

#include <libgearman/gearman.h>

.. c:function:: 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)

.. c:function:: gearman_task_st *gearman_client_add_task_high_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)

.. c:function:: gearman_task_st *gearman_client_add_task_low_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)

Link with -lgearman

-----------
DESCRIPTION
-----------

:c:func:`gearman_client_add_task_background` creates a background task and adds it ito the given :c:type:`gearman_client_st`. Execution of the task does not begin until :c:func:`gearman_client_run_tasks` is called.

If the unique value is not set, then a unique will be assigned.

:c:func:`gearman_client_add_task_high_background` and :c:func:`gearman_client_add_task_low_background` are
identical to :c:func:`gearman_client_do`, only they set the priority to
either high or low. 

.. warning:: 

  You may wish to avoid using :c:func:`gearman_client_add_task_background` with a stack based allocated
  :c:type:`gearman_task_st`. The most common issues related to ABI safety involve stack allocated structures. If you use a stack based
  :c:type:`gearman_task_st` you must free it with :c:func:`gearman_task_free`.

------------
RETURN VALUE
------------

The :c:type:`gearman_task_st` is created and a pointer to it is returned. On error NULL is returned and ret_ptr is set with a :c:type:`gearman_return_t`.

----
HOME
----

To find out more information please check:
`https://gearman.org/gearmand/ <https://gearman.org/gearmand/>`_


.. seealso::

   :manpage:`gearmand(8)` :manpage:`libgearman(3)` :manpage:`gearman_task_st`