<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<refentry xml:id="pool.submitTo" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>Pool::submitTo</refname>
  <refpurpose>Submits a task to a specific worker for execution</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>public</modifier> <type>int</type><methodname>Pool::submitTo</methodname>
   <methodparam><type>int</type><parameter>worker</parameter></methodparam>
   <methodparam><type>Threaded</type><parameter>task</parameter></methodparam>
  </methodsynopsis>
  <para>
   Submit a task to the specified worker in the pool. The workers are indexed
   from 0, and will only exist if the pool has needed to create them (since
   threads are lazily spawned).
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>worker</parameter></term>
    <listitem>
     <para>
      The worker to stack the task onto, indexed from <literal>0</literal>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>task</parameter></term>
    <listitem>
     <para>
      The task for execution.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   The identifier of the worker that accepted the task.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Submitting tasks to a specific worker</title>
    <programlisting role="php">
<![CDATA[
<?php
class Task extends Threaded {
    public function run() {
        var_dump(Thread::getCurrentThreadID());
    }
}

$pool = new Pool(2);

$pool->submit(new Task());

for ($i = 0; $i < 5; ++$i) {
    $pool->submitTo(0, new Task()); // stack all tasks onto the first worker
}

$pool->submitTo(1, new Task()); // cannot stack the task onto the second worker due to it not existing yet

$pool->shutdown();
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
int(4475011072)
int(4475011072)
int(4475011072)
int(4475011072)
int(4475011072)
int(4475011072)

Fatal error: Uncaught Exception: The selected worker (1) does not exist in %s:%d
]]>
    </screen>
   </example>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
