<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter  xml:id="ev.watcher-callbacks" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Watcher callbacks</title>
 <para>
  All watchers can be active(waiting for events) or inactive(paused). Only
  active watchers will have their callbacks invoked. All callbacks will be
  called with at least two arguments:
  <parameter>watcher</parameter>
  - the watcher, and
  <parameter>revents</parameter>
  a bitmask of received events.
 </para>
 <para>
  Watcher callbacks are passed to the watcher constructors (the classes derived
  from
  <classname>EvWatcher</classname>
  -
  <methodname>EvCheck::__construct</methodname>
  ,
  <methodname>EvChild::__construct</methodname>
  etc.). A watcher callback should match the following prototype:
 </para>
 <methodsynopsis>
  <type>void</type>
  <methodname>callback</methodname>
  <methodparam
   choice="opt">
   <type>object</type>
   <parameter>watcher</parameter>
   <initializer>NULL</initializer>
  </methodparam>
  <methodparam
   choice="opt">
   <type>int</type>
   <parameter>revents</parameter>
   <initializer>NULL</initializer>
  </methodparam>
 </methodsynopsis>
 <para>
  <variablelist>
   <varlistentry>
    <term>
     <parameter>watcher</parameter>
    </term>
    <listitem>
     <para>
      The watcher instance(of a class extending
      <classname>EvWatcher</classname>
      ).
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     <parameter>revents</parameter>
    </term>
    <listitem>
     <para>
      <link linkend="ev.constants.watcher-revents">Watcher received events</link>
      .
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
 <para>
  Each watcher type has its associated bit in
  <parameter>revents</parameter>
  , so one can use the same callback for multiple watchers. The event mask is
  named after the type, i.e.
  <classname>EvChild</classname>
  (or
  <methodname>EvLoop::child</methodname>
  ) sets
  <constant>EV::CHILD</constant>
  ,
  <classname>EvPrepare</classname>
  (or
  <methodname>EvLoop::prepare</methodname>
  ) sets
  <constant>Ev::PREPARE</constant>
  ,
  <classname>EvPeriodic</classname>
  (or
  <methodname>EvLoop::periodic</methodname>
  ) sets
  <constant>Ev::PERIODIC</constant>
  and so on, with the exception of I/O events (which can set both
  <constant>Ev::READ</constant>
  and
  <constant>Ev::WRITE</constant>
  bits).
 </para>
</chapter>
<!-- 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
-->
