<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Add a background task to be run in parallel</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="gearmanclient.addtask.html">GearmanClient::addTask</a></div>
<div class="next" style="text-align: right; float: right;"><a href="gearmanclient.addtaskhigh.html">GearmanClient::addTaskHigh</a></div>
<div class="up"><a href="class.gearmanclient.html">GearmanClient</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="gearmanclient.addtaskbackground" class="refentry">
<div class="refnamediv">
<h1 class="refname">GearmanClient::addTaskBackground</h1>
<p class="verinfo">(PECL gearman >= 0.5.0)</p><p class="refpurpose"><span class="refname">GearmanClient::addTaskBackground</span> — <span class="dc-title">Add a background task to be run in parallel</span></p>
</div>
<div class="refsect1 description" id="refsect1-gearmanclient.addtaskbackground-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type"><a href="class.gearmantask.html" class="type GearmanTask">GearmanTask</a></span> <span class="methodname"><strong>GearmanClient::addTaskBackground</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$function_name</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$workload</code></span>
[, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter reference">&$context</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$unique</code></span>
]] )</div>
<p class="para rdfs-comment">
Adds a background task to be run in parallel with other tasks. Call this method for all the tasks
to be run in parallel, then call <span class="methodname"><a href="gearmanclient.runtasks.html" class="methodname">GearmanClient::runTasks()</a></span> to
perform the work.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-gearmanclient.addtaskbackground-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">function_name</code></em></span>
<dd>
<p class="para">
A registered function the worker is to execute
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">workload</code></em></span>
<dd>
<p class="para">
Serialized data to be processed
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">context</code></em></span>
<dd>
<p class="para">
Application context to associate with a task
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">unique</code></em></span>
<dd>
<p class="para">
A unique ID used to identify a particular task
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-gearmanclient.addtaskbackground-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
A <a href="class.gearmantask.html" class="classname">GearmanTask</a> object or <strong><code>FALSE</code></strong> if the task could not be added.
</p>
</div>
<div class="refsect1 examples" id="refsect1-gearmanclient.addtaskbackground-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-4317">
<p><strong>Example #1 Two tasks, one background and one not</strong></p>
<div class="example-contents"><p>
This example illustrates the difference between running a background task
and a normal task. The client adds two tasks to execute the same function,
but one is added with <span class="methodname"><strong>addTaskBackground()</strong></span>. A callback is
set so that progress of the job can be tracked. A simple worker with an
artificial delay reports on the job progress and the client picks this up
through the callback. Two workers are run for this example. Note that the
background task does not show in the client output.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000"># The client script<br /><br /># create our gearman client<br /></span><span style="color: #0000BB">$gmc</span><span style="color: #007700">= new </span><span style="color: #0000BB">GearmanClient</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000"># add the default job server<br /></span><span style="color: #0000BB">$gmc</span><span style="color: #007700">-></span><span style="color: #0000BB">addServer</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000"># set a couple of callbacks so we can track progress<br /></span><span style="color: #0000BB">$gmc</span><span style="color: #007700">-></span><span style="color: #0000BB">setCompleteCallback</span><span style="color: #007700">(</span><span style="color: #DD0000">"reverse_complete"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$gmc</span><span style="color: #007700">-></span><span style="color: #0000BB">setStatusCallback</span><span style="color: #007700">(</span><span style="color: #DD0000">"reverse_status"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000"># add a task for the "reverse" function<br /></span><span style="color: #0000BB">$task</span><span style="color: #007700">= </span><span style="color: #0000BB">$gmc</span><span style="color: #007700">-></span><span style="color: #0000BB">addTask</span><span style="color: #007700">(</span><span style="color: #DD0000">"reverse"</span><span style="color: #007700">, </span><span style="color: #DD0000">"Hello World!"</span><span style="color: #007700">, </span><span style="color: #0000BB">null</span><span style="color: #007700">, </span><span style="color: #DD0000">"1"</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000"># add another task, but this one to run in the background<br /></span><span style="color: #0000BB">$task</span><span style="color: #007700">= </span><span style="color: #0000BB">$gmc</span><span style="color: #007700">-></span><span style="color: #0000BB">addTaskBackground</span><span style="color: #007700">(</span><span style="color: #DD0000">"reverse"</span><span style="color: #007700">, </span><span style="color: #DD0000">"!dlroW olleH"</span><span style="color: #007700">, </span><span style="color: #0000BB">null</span><span style="color: #007700">, </span><span style="color: #DD0000">"2"</span><span style="color: #007700">);<br /><br />if (! </span><span style="color: #0000BB">$gmc</span><span style="color: #007700">-></span><span style="color: #0000BB">runTasks</span><span style="color: #007700">())<br />{<br /> echo </span><span style="color: #DD0000">"ERROR " </span><span style="color: #007700">. </span><span style="color: #0000BB">$gmc</span><span style="color: #007700">-></span><span style="color: #0000BB">error</span><span style="color: #007700">() . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /> exit;<br />}<br /><br />echo </span><span style="color: #DD0000">"DONE\n"</span><span style="color: #007700">;<br /><br />function </span><span style="color: #0000BB">reverse_status</span><span style="color: #007700">(</span><span style="color: #0000BB">$task</span><span style="color: #007700">)<br />{<br /> echo </span><span style="color: #DD0000">"STATUS: " </span><span style="color: #007700">. </span><span style="color: #0000BB">$task</span><span style="color: #007700">-></span><span style="color: #0000BB">unique</span><span style="color: #007700">() . </span><span style="color: #DD0000">", " </span><span style="color: #007700">. </span><span style="color: #0000BB">$task</span><span style="color: #007700">-></span><span style="color: #0000BB">jobHandle</span><span style="color: #007700">() . </span><span style="color: #DD0000">" - " </span><span style="color: #007700">. </span><span style="color: #0000BB">$task</span><span style="color: #007700">-></span><span style="color: #0000BB">taskNumerator</span><span style="color: #007700">() . <br /> </span><span style="color: #DD0000">"/" </span><span style="color: #007700">. </span><span style="color: #0000BB">$task</span><span style="color: #007700">-></span><span style="color: #0000BB">taskDenominator</span><span style="color: #007700">() . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />}<br /><br />function </span><span style="color: #0000BB">reverse_complete</span><span style="color: #007700">(</span><span style="color: #0000BB">$task</span><span style="color: #007700">)<br />{<br /> echo </span><span style="color: #DD0000">"COMPLETE: " </span><span style="color: #007700">. </span><span style="color: #0000BB">$task</span><span style="color: #007700">-></span><span style="color: #0000BB">unique</span><span style="color: #007700">() . </span><span style="color: #DD0000">", " </span><span style="color: #007700">. </span><span style="color: #0000BB">$task</span><span style="color: #007700">-></span><span style="color: #0000BB">data</span><span style="color: #007700">() . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000"># The worker script<br /><br /></span><span style="color: #007700">echo </span><span style="color: #DD0000">"Starting\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000"># Create our worker object.<br /></span><span style="color: #0000BB">$gmworker</span><span style="color: #007700">= new </span><span style="color: #0000BB">GearmanWorker</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000"># Add default server (localhost).<br /></span><span style="color: #0000BB">$gmworker</span><span style="color: #007700">-></span><span style="color: #0000BB">addServer</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000"># Register function "reverse" with the server.<br /></span><span style="color: #0000BB">$gmworker</span><span style="color: #007700">-></span><span style="color: #0000BB">addFunction</span><span style="color: #007700">(</span><span style="color: #DD0000">"reverse"</span><span style="color: #007700">, </span><span style="color: #DD0000">"reverse_fn"</span><span style="color: #007700">);<br /><br />print </span><span style="color: #DD0000">"Waiting for job...\n"</span><span style="color: #007700">;<br />while(</span><span style="color: #0000BB">$gmworker</span><span style="color: #007700">-></span><span style="color: #0000BB">work</span><span style="color: #007700">())<br />{<br /> if (</span><span style="color: #0000BB">$gmworker</span><span style="color: #007700">-></span><span style="color: #0000BB">returnCode</span><span style="color: #007700">() != </span><span style="color: #0000BB">GEARMAN_SUCCESS</span><span style="color: #007700">)<br /> {<br /> echo </span><span style="color: #DD0000">"return_code: " </span><span style="color: #007700">. </span><span style="color: #0000BB">$gmworker</span><span style="color: #007700">-></span><span style="color: #0000BB">returnCode</span><span style="color: #007700">() . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /> break;<br /> }<br />}<br /><br />function </span><span style="color: #0000BB">reverse_fn</span><span style="color: #007700">(</span><span style="color: #0000BB">$job</span><span style="color: #007700">)<br />{<br /> echo </span><span style="color: #DD0000">"Received job: " </span><span style="color: #007700">. </span><span style="color: #0000BB">$job</span><span style="color: #007700">-></span><span style="color: #0000BB">handle</span><span style="color: #007700">() . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /><br /> </span><span style="color: #0000BB">$workload </span><span style="color: #007700">= </span><span style="color: #0000BB">$job</span><span style="color: #007700">-></span><span style="color: #0000BB">workload</span><span style="color: #007700">();<br /> </span><span style="color: #0000BB">$workload_size </span><span style="color: #007700">= </span><span style="color: #0000BB">$job</span><span style="color: #007700">-></span><span style="color: #0000BB">workloadSize</span><span style="color: #007700">();<br /><br /> echo </span><span style="color: #DD0000">"Workload: </span><span style="color: #0000BB">$workload</span><span style="color: #DD0000"> (</span><span style="color: #0000BB">$workload_size</span><span style="color: #DD0000">)\n"</span><span style="color: #007700">;<br /><br /> </span><span style="color: #FF8000"># This status loop is not needed, just showing how it works<br /> </span><span style="color: #007700">for (</span><span style="color: #0000BB">$x</span><span style="color: #007700">= </span><span style="color: #0000BB">0</span><span style="color: #007700">; </span><span style="color: #0000BB">$x </span><span style="color: #007700">< </span><span style="color: #0000BB">$workload_size</span><span style="color: #007700">; </span><span style="color: #0000BB">$x</span><span style="color: #007700">++)<br /> {<br /> echo </span><span style="color: #DD0000">"Sending status: " </span><span style="color: #007700">. (</span><span style="color: #0000BB">$x </span><span style="color: #007700">+ </span><span style="color: #0000BB">1</span><span style="color: #007700">) . </span><span style="color: #DD0000">"/</span><span style="color: #0000BB">$workload_size</span><span style="color: #DD0000"> complete\n"</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$job</span><span style="color: #007700">-></span><span style="color: #0000BB">sendStatus</span><span style="color: #007700">(</span><span style="color: #0000BB">$x</span><span style="color: #007700">+</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">$workload_size</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$job</span><span style="color: #007700">-></span><span style="color: #0000BB">sendData</span><span style="color: #007700">(</span><span style="color: #0000BB">substr</span><span style="color: #007700">(</span><span style="color: #0000BB">$workload</span><span style="color: #007700">, </span><span style="color: #0000BB">$x</span><span style="color: #007700">, </span><span style="color: #0000BB">1</span><span style="color: #007700">));<br /> </span><span style="color: #0000BB">sleep</span><span style="color: #007700">(</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /> }<br /><br /> </span><span style="color: #0000BB">$result</span><span style="color: #007700">= </span><span style="color: #0000BB">strrev</span><span style="color: #007700">(</span><span style="color: #0000BB">$workload</span><span style="color: #007700">);<br /> echo </span><span style="color: #DD0000">"Result: </span><span style="color: #0000BB">$result</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /><br /> </span><span style="color: #FF8000"># Return what we want to send back to the client.<br /> </span><span style="color: #007700">return </span><span style="color: #0000BB">$result</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
Worker output for two workers running:
</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Received job: H:foo.local:65
Workload: !dlroW olleH (12)
1/12 complete
Received job: H:foo.local:66
Workload: Hello World! (12)
1/12 complete
2/12 complete
2/12 complete
3/12 complete
3/12 complete
4/12 complete
4/12 complete
5/12 complete
5/12 complete
6/12 complete
6/12 complete
7/12 complete
7/12 complete
8/12 complete
8/12 complete
9/12 complete
9/12 complete
10/12 complete
10/12 complete
11/12 complete
11/12 complete
12/12 complete
12/12 complete
Result: !dlroW olleH
Result: Hello World!
</pre></div>
</div>
<div class="example-contents"><p>
Client output:
</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
STATUS: 1, H:foo.local:66 - 1/12
STATUS: 1, H:foo.local:66 - 2/12
STATUS: 1, H:foo.local:66 - 3/12
STATUS: 1, H:foo.local:66 - 4/12
STATUS: 1, H:foo.local:66 - 5/12
STATUS: 1, H:foo.local:66 - 6/12
STATUS: 1, H:foo.local:66 - 7/12
STATUS: 1, H:foo.local:66 - 8/12
STATUS: 1, H:foo.local:66 - 9/12
STATUS: 1, H:foo.local:66 - 10/12
STATUS: 1, H:foo.local:66 - 11/12
STATUS: 1, H:foo.local:66 - 12/12
COMPLETE: 1, !dlroW olleH
DONE
</pre></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-gearmanclient.addtaskbackground-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="methodname"><a href="gearmanclient.addtask.html" class="methodname" rel="rdfs-seeAlso">GearmanClient::addTask()</a> - Add a task to be run in parallel</span></li>
<li class="member"> <span class="methodname"><a href="gearmanclient.addtaskhigh.html" class="methodname" rel="rdfs-seeAlso">GearmanClient::addTaskHigh()</a> - Add a high priority task to run in parallel</span></li>
<li class="member"> <span class="methodname"><a href="gearmanclient.addtasklow.html" class="methodname" rel="rdfs-seeAlso">GearmanClient::addTaskLow()</a> - Add a low priority task to run in parallel</span></li>
<li class="member"> <span class="methodname"><a href="gearmanclient.addtaskhighbackground.html" class="methodname" rel="rdfs-seeAlso">GearmanClient::addTaskHighBackground()</a> - Add a high priority background task to be run in parallel</span></li>
<li class="member"> <span class="methodname"><a href="gearmanclient.addtasklowbackground.html" class="methodname" rel="rdfs-seeAlso">GearmanClient::addTaskLowBackground()</a> - Add a low priority background task to be run in parallel</span></li>
<li class="member"> <span class="methodname"><a href="gearmanclient.runtasks.html" class="methodname" rel="rdfs-seeAlso">GearmanClient::runTasks()</a> - Run a list of tasks in parallel</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="gearmanclient.addtask.html">GearmanClient::addTask</a></div>
<div class="next" style="text-align: right; float: right;"><a href="gearmanclient.addtaskhigh.html">GearmanClient::addTaskHigh</a></div>
<div class="up"><a href="class.gearmanclient.html">GearmanClient</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
