sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-17 17:38:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
php-doc-en/reference/ev/ev.xml
Ruslan Osmanov 8b82a7e762 Fix: svn:keywords 
Add: docs for evperiodic, evsignal, evstat
Fix: typos

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328901 c90b9560-bf6c-de11-be94-00142212c4b1
2012-12-27 06:41:57 +00:00

729 lines
24 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<phpdoc:classref xml:id="class.ev" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The Ev class</title>
<titleabbrev>Ev</titleabbrev>
<partintro>
<!-- {{{ Ev intro -->
<section xml:id="ev.intro">
&reftitle.intro;
<para>
Ev is a singleton providing access to the default loop and to some common
operations.
</para>
</section>
<!-- }}} -->
<section xml:id="ev.synopsis">
&reftitle.classsynopsis;
<!-- {{{ Synopsis -->
<classsynopsis>
<ooclass><classname>Ev</classname></ooclass>
<!-- {{{ Class synopsis -->
<classsynopsisinfo>
<ooclass>
<modifier>final</modifier>
<classname>Ev</classname>
</ooclass>
</classsynopsisinfo>
<!-- }}} -->
<classsynopsisinfo role="comment">Constants</classsynopsisinfo><!--{{{-->
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.flag-auto">Ev::FLAG_AUTO</varname>
<initializer>0</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.flag-noenv">Ev::FLAG_NOENV</varname>
<initializer>16777216</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.flag-forkcheck">Ev::FLAG_FORKCHECK</varname>
<initializer>33554432</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.flag-noinotify">Ev::FLAG_NOINOTIFY</varname>
<initializer>1048576</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.flag-signalfd">Ev::FLAG_SIGNALFD</varname>
<initializer>2097152</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.flag-nosigmask">Ev::FLAG_NOSIGMASK</varname>
<initializer>4194304</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.run-nowait">Ev::RUN_NOWAIT</varname>
<initializer>1</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.run-once">Ev::RUN_ONCE</varname>
<initializer>2</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.break-cancel">Ev::BREAK_CANCEL</varname>
<initializer>0</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.break-one">Ev::BREAK_ONE</varname>
<initializer>1</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.break-all">Ev::BREAK_ALL</varname>
<initializer>2</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.minpri">Ev::MINPRI</varname>
<initializer>-2</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.maxpri">Ev::MAXPRI</varname>
<initializer>2</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.read">Ev::READ</varname>
<initializer>1</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.write">Ev::WRITE</varname>
<initializer>2</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.timer">Ev::TIMER</varname>
<initializer>256</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.periodic">Ev::PERIODIC</varname>
<initializer>512</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.signal">Ev::SIGNAL</varname>
<initializer>1024</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.child">Ev::CHILD</varname>
<initializer>2048</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.stat">Ev::STAT</varname>
<initializer>4096</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.idle">Ev::IDLE</varname>
<initializer>8192</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.prepare">Ev::PREPARE</varname>
<initializer>16384</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.check">Ev::CHECK</varname>
<initializer>32768</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.embed">Ev::EMBED</varname>
<initializer>65536</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.custom">Ev::CUSTOM</varname>
<initializer>16777216</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.error">Ev::ERROR</varname>
<initializer>2147483648</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.backend-select">Ev::BACKEND_SELECT</varname>
<initializer>1</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.backend-poll">Ev::BACKEND_POLL</varname>
<initializer>2</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.backend-epoll">Ev::BACKEND_EPOLL</varname>
<initializer>4</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.backend-kqueue">Ev::BACKEND_KQUEUE</varname>
<initializer>8</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.backend-devpoll">Ev::BACKEND_DEVPOLL</varname>
<initializer>16</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.backend-port">Ev::BACKEND_PORT</varname>
<initializer>32</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.backend-all">Ev::BACKEND_ALL</varname>
<initializer>63</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>integer</type>
<varname linkend="ev.constants.backend-mask">Ev::BACKEND_MASK</varname>
<initializer>65535</initializer>
</fieldsynopsis>
<!--}}}-->
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.ev')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
</classsynopsis>
<!-- }}} -->
</section>
<!-- {{{ Ev constants -->
<section xml:id="ev.constants">
&reftitle.constants;
<para xml:id="ev.constants.loop-flags">Flags passed to create a loop:<!--{{{-->
<variablelist>
<varlistentry xml:id="ev.constants.flag-auto">
<term><constant>Ev::FLAG_AUTO</constant></term>
<listitem>
<para>The default flags value</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.flag-noenv">
<term><constant>Ev::FLAG_NOENV</constant></term>
<listitem>
<para>
If this flag used(or the program runs setuid or setgid),
<literal>libev</literal> won't look at the environment variable
<varname>LIBEV_FLAGS</varname>. Otherwise(by default),
<varname>LIBEV_FLAGS</varname> will override the flags completely if it
is found. Useful for performance tests and searching for bugs.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.flag-forkcheck">
<term><constant>Ev::FLAG_FORKCHECK</constant></term>
<listitem>
<para>
Makes libev check for a fork in each iteration, instead of calling
<methodname>EvLoop::fork</methodname> manually.
This works by calling <literal>getpid()</literal> on every iteration of
the loop, and thus this might slow down your event loop if you do a lot of
loop iterations, but usually is not noticeable.
This flag setting cannot be overridden or specified in the
<varname>LIBEV_FLAGS</varname> environment variable.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.flag-noinotify">
<term><constant>Ev::FLAG_NOINOTIFY</constant></term>
<listitem>
<para>
When this flag is specified, <literal>libev</literal> won't attempt to
use the <literal>inotify</literal> API for its <link
xlink:href="http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_stat_code_did_the_file_attri">ev_stat</link>
watchers. The flag can be useful to conserve inotify file descriptors, as
otherwise each loop using <literal>ev_stat</literal> watchers consumes
one <literal>inotify</literal> handle.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.flag-signalfd">
<term><constant>Ev::FLAG_SIGNALFD</constant></term>
<listitem>
<para>
When this flag is specified, <literal>libev</literal> will attempt to
use the <literal>signalfd</literal> API for its
<link
xlink:href="http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_signal_code_signal_me_when_a">ev_signal</link>
(and <link
xlink:href="http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_child_code_watch_out_for_pro">ev_child</link>)
watchers. This API delivers signals synchronously, which makes it both
faster and might make it possible to get the queued signal data. It can
also simplify signal handling with threads, as long as you properly block
signals in your threads that are not interested in handling them.
<literal>Signalfd</literal> will not be used by default.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.flag-nosigmask">
<term><constant>Ev::FLAG_NOSIGMASK</constant></term>
<listitem>
<para>
When this flag is specified, <literal>libev</literal> will avoid to
modify the signal mask. Specifically, this means you have to make sure
signals are unblocked when you want to receive them.
This behaviour is useful when you want to do your own signal handling, or
want to handle signals only in specific threads and want to avoid
<literal>libev</literal> unblocking the signals.
</para>
</listitem>
</varlistentry>
</variablelist>
</para><!--}}}-->
<para xml:id="ev.constants.run-flags">Flags passed to <methodname>Ev::run</methodname>, or <methodname>EvLoop::run</methodname><!--{{{-->
<variablelist>
<varlistentry xml:id="ev.constants.run-nowait">
<term><constant>Ev::RUN_NOWAIT</constant></term>
<listitem>
<para>
Means that event loop will look for new events, will handle those events
and any already outstanding ones, but will not wait and block your
process in case there are no events and will return after one iteration
of the loop. This is sometimes useful to poll and handle new events
while doing lengthy calculations, to keep the program responsive.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.run-once">
<term><constant>Ev::RUN_ONCE</constant></term>
<listitem>
<para>
Means that even loop will look for new events(waiting if
necessary) and will handle those and any already outstanding ones. It
will block your process until at least one new event arrives (which could
be an event internal to libev itself, so there is no guarantee that a
user-registered callback will be called), and will return after one
iteration of the loop.
</para>
</listitem>
</varlistentry>
</variablelist>
</para><!--}}}-->
<para xml:id="ev.constants.break-flags">Flags passed to <methodname>Ev::stop</methodname>, or
<methodname>EvLoop::stop</methodname><!--{{{-->
<variablelist>
<varlistentry xml:id="ev.constants.break-cancel">
<term><constant>Ev::BREAK_CANCEL</constant></term>
<listitem>
<para>
Cancel the break operation.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.break-one">
<term><constant>Ev::BREAK_ONE</constant></term>
<listitem>
<para>
Makes the innermost <methodname>Ev::run</methodname>(or
<methodname>EvLoop::run</methodname>) call return.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.break-all">
<term><constant>Ev::BREAK_ALL</constant></term>
<listitem>
<para>
Makes all nested <methodname>Ev::run</methodname>(or
<methodname>EvLoop::run</methodname>) calls return.
</para>
</listitem>
</varlistentry>
</variablelist>
</para><!--}}}-->
<para xml:id="ev.constants.watcher-pri">Watcher priorities:<!--{{{-->
<variablelist>
<varlistentry xml:id="ev.constants.minpri">
<term><constant>Ev::MINPRI</constant></term>
<listitem>
<para>
Minimum allowed watcher priority.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.maxpri">
<term><constant>Ev::MAXPRI</constant></term>
<listitem>
<para>
Maximum allowed watcher priority.
</para>
</listitem>
</varlistentry>
</variablelist>
</para><!--}}}-->
<para xml:id="ev.constants.watcher-revents">Bit masks of (received) events:<!--{{{-->
<variablelist>
<varlistentry xml:id="ev.constants.read">
<term><constant>Ev::READ</constant></term>
<listitem>
<para>
The file descriptor in the <classname>EvIo</classname> watcher has become
readable.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.write">
<term><constant>Ev::WRITE</constant></term>
<listitem>
<para>
The file descriptor in the <classname>EvIo</classname> watcher has become
writable.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.timer">
<term><constant>Ev::TIMER</constant></term>
<listitem>
<para>
<classname>EvTimer</classname> watcher has been timed out.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.periodic">
<term><constant>Ev::PERIODIC</constant></term>
<listitem>
<para>
<classname>EvPeriodic</classname> watcher has been timed out.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.signal">
<term><constant>Ev::SIGNAL</constant></term>
<listitem>
<para>
A signal specified in <methodname>EvSignal::__construct</methodname> has
been received.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.child">
<term><constant>Ev::CHILD</constant></term>
<listitem>
<para>
The <parameter>pid</parameter> specified in
<methodname>EvChild::__construct</methodname> has received a status
change.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.stat">
<term><constant>Ev::STAT</constant></term>
<listitem>
<para>
The path specified in <classname>EvStat</classname> watcher changed its
attributes.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.idle">
<term><constant>Ev::IDLE</constant></term>
<listitem>
<para>
<classname>EvIdle</classname> watcher works when there is nothing to do
with other watchers.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.prepare">
<term><constant>Ev::PREPARE</constant></term>
<listitem>
<para>
All <classname>EvPrepare</classname> watchers are invoked just before
<methodname>Ev::run</methodname> starts. Thus,
<classname>EvPrepare</classname> watchers are the last watchers invoked
before the event loop sleeps or polls for new events.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.check">
<term><constant>Ev::CHECK</constant></term>
<listitem>
<para>
All <classname>EvCheck</classname> watchers are queued just after
<methodname>Ev::run</methodname> has gathered the new events, but before it
queues any callbacks for any received events. Thus,
<classname>EvCheck</classname> watchers will be invoked before any other
watchers of the same or lower priority within an event loop iteration.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.embed">
<term><constant>Ev::EMBED</constant></term>
<listitem>
<para>
The embedded event loop specified in the <classname>EvEmbed</classname> watcher needs attention.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.custom">
<term><constant>Ev::CUSTOM</constant></term>
<listitem>
<para>
Not ever sent(or otherwise used) by <literal>libev</literal> itself,
but can be freely used by <literal>libev</literal> users to signal
watchers (e.g. via <methodname>EvWatcher::feed</methodname>).
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.error">
<term><constant>Ev::ERROR</constant></term>
<listitem>
<para>
An unspecified error has occurred, the watcher has been stopped. This
might happen because the watcher could not be properly started because
<literal>libev</literal> ran out of memory, a file descriptor was found
to be closed or any other problem. <literal>Libev</literal> considers
these application bugs.
See also <link
xlink:href="http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#ANATOMY_OF_A_WATCHER_CONTENT">ANATOMY
OF A WATCHER</link>
</para>
</listitem>
</varlistentry>
</variablelist>
</para><!--}}}-->
<para xml:id="ev.constants.watcher-backends">Backend flags:<!--{{{-->
<variablelist>
<varlistentry xml:id="ev.constants.backend-select">
<term><constant>Ev::BACKEND_SELECT</constant></term>
<listitem>
<para>
<literal>select(2) backend</literal>
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.backend-poll">
<term><constant>Ev::BACKEND_POLL</constant></term>
<listitem>
<para>
<literal>poll(2) backend</literal>
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.backend-epoll">
<term><constant>Ev::BACKEND_EPOLL</constant></term>
<listitem>
<para>
Linux-specific <literal>epoll(7)</literal> backend for both pre- and post-2.6.9 kernels
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.backend-kqueue">
<term><constant>Ev::BACKEND_KQUEUE</constant></term>
<listitem>
<para>
<literal>kqueue</literal> backend used on most BSD systems.
<classname>EvEmbed</classname> watcher could be used to embed one
loop(with kqueue backend) into another. For instance, you can try to
create an event loop with <literal>kqueue</literal> backend and use it
for sockets only.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.backend-devpoll">
<term><constant>Ev::BACKEND_DEVPOLL</constant></term>
<listitem>
<para>
Solaris 8 backend. This is not implemented yet.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.backend-port">
<term><constant>Ev::BACKEND_PORT</constant></term>
<listitem>
<para>
Solaris 10 event port mechanism with a good scaling.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.backend-all">
<term><constant>Ev::BACKEND_ALL</constant></term>
<listitem>
<para>
Try all backends(even currupted ones). It's not recommended to use it
explicitly. You should apply bitwise operators(e.g.
<constant>Ev::BACKEND_ALL</constant> &amp;
~<constant>Ev::BACKEND_KQUEUE</constant>)
Use <methodname>Ev::recommendedBackends</methodname>, or don't specify any
backends at all.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ev.constants.backend-mask">
<term><constant>Ev::BACKEND_MASK</constant></term>
<listitem>
<para>
Not a backend, but a mask to select all backend bits from a
<parameter>flags</parameter> value, in case you want to mask out any
backends from a flags value (e.g. when modifying the
<varname>LIBEV_FLAGS</varname> environment variable).
</para>
</listitem>
</varlistentry>
</variablelist>
</para><!--}}}-->
<note xmlns="http://docbook.org/ns/docbook">
<para>
For the default loop during module initialization phase <literal>Ev</literal> registers
<link
xlink:href="http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_EVENT_LOOPS_CO">ev_loop_fork</link>
call by means of <literal>pthread_atfork</literal>(if available).
</para>
</note>
<note xmlns="http://docbook.org/ns/docbook">
<para>
There are methods providing access to the <emphasis>default event
loop</emphasis> in <classname>Ev</classname> class(e.g.
<methodname>Ev::iteration</methodname>, <methodname>Ev::depth</methodname>
etc.) For <emphasis>custom loops</emphasis>(created with
<methodname>EvLoop::__construct</methodname>) you can access these values
via corresponding properties and methods of the <classname>EvLoop</classname>
class.
</para>
<para>
The instance of the default event loop itself can be fetched by means of
<methodname>Ev::defaultLoop</methodname> method.
</para>
</note>
</section>
<!-- }}} -->
</partintro>
&reference.ev.entities.ev;
</phpdoc:classref>
<!-- 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
-->
Reference in a new issue View git blame Copy permalink