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

<reference xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="class.ev" role="class">

<title>The Ev class</title>

<titleabbrev>Ev</titleabbrev>

<partintro>

<section xml:id="ev.intro">

&reftitle.intro;

<simpara>

Ev is a static class providing access to the default loop and to some common

operations.

</simpara>

</section>

<section xml:id="ev.synopsis">

&reftitle.classsynopsis;

<classsynopsis>

<ooclass>

<classname>Ev</classname>

</ooclass>

<classsynopsisinfo>

<ooclass>

<modifier>final</modifier>

<classname>Ev</classname>

</ooclass>

</classsynopsisinfo>

<classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.flag-auto">Ev::FLAG_AUTO</varname>

<initializer>0</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.flag-noenv">Ev::FLAG_NOENV</varname>

<initializer>16777216</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.flag-forkcheck">Ev::FLAG_FORKCHECK</varname>

<initializer>33554432</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.flag-noinotify">Ev::FLAG_NOINOTIFY</varname>

<initializer>1048576</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.flag-signalfd">Ev::FLAG_SIGNALFD</varname>

<initializer>2097152</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.flag-nosigmask">Ev::FLAG_NOSIGMASK</varname>

<initializer>4194304</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.run-nowait">Ev::RUN_NOWAIT</varname>

<initializer>1</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.run-once">Ev::RUN_ONCE</varname>

<initializer>2</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.break-cancel">Ev::BREAK_CANCEL</varname>

<initializer>0</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.break-one">Ev::BREAK_ONE</varname>

<initializer>1</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.break-all">Ev::BREAK_ALL</varname>

<initializer>2</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.minpri">Ev::MINPRI</varname>

<initializer>-2</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.maxpri">Ev::MAXPRI</varname>

<initializer>2</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.read">Ev::READ</varname>

<initializer>1</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.write">Ev::WRITE</varname>

<initializer>2</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.timer">Ev::TIMER</varname>

<initializer>256</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.periodic">Ev::PERIODIC</varname>

<initializer>512</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.signal">Ev::SIGNAL</varname>

<initializer>1024</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.child">Ev::CHILD</varname>

<initializer>2048</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.stat">Ev::STAT</varname>

<initializer>4096</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.idle">Ev::IDLE</varname>

<initializer>8192</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.prepare">Ev::PREPARE</varname>

<initializer>16384</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.check">Ev::CHECK</varname>

<initializer>32768</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.embed">Ev::EMBED</varname>

<initializer>65536</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.custom">Ev::CUSTOM</varname>

<initializer>16777216</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.error">Ev::ERROR</varname>

<initializer>2147483648</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.backend-select">Ev::BACKEND_SELECT</varname>

<initializer>1</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.backend-poll">Ev::BACKEND_POLL</varname>

<initializer>2</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.backend-epoll">Ev::BACKEND_EPOLL</varname>

<initializer>4</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.backend-kqueue">Ev::BACKEND_KQUEUE</varname>

<initializer>8</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.backend-devpoll">Ev::BACKEND_DEVPOLL</varname>

<initializer>16</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.backend-port">Ev::BACKEND_PORT</varname>

<initializer>32</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</type>

<varname linkend="ev.constants.backend-all">Ev::BACKEND_ALL</varname>

<initializer>63</initializer>

</fieldsynopsis>

<fieldsynopsis>

<modifier>const</modifier>

<type>int</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>

<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>

<simpara>

The default flags value

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.flag-noenv">

<term>

<constant>Ev::FLAG_NOENV</constant>

</term>

<listitem>

<simpara>

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.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.flag-forkcheck">

<term>

<constant>Ev::FLAG_FORKCHECK</constant>

</term>

<listitem>

<simpara>

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 the

event loop with lots of loop iterations, but usually is not

noticeable. This flag setting cannot be overridden or specified in the

<varname>LIBEV_FLAGS</varname>

environment variable.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.flag-noinotify">

<term>

<constant>Ev::FLAG_NOINOTIFY</constant>

</term>

<listitem>

<simpara>

When this flag is specified,

<literal>libev</literal>

won't attempt to use the

<literal>inotify</literal>

API for its

<link xlink:href="&url.ev.stat;">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.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.flag-signalfd">

<term>

<constant>Ev::FLAG_SIGNALFD</constant>

</term>

<listitem>

<simpara>

When this flag is specified,

<literal>libev</literal>

will attempt to use the

<literal>signalfd</literal>

API for its

<link xlink:href="&url.ev.signal;">ev_signal</link>

(and

<link xlink:href="&url.ev.child;">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 signals

are properly blocked in threads.

<literal>Signalfd</literal>

will not be used by default.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.flag-nosigmask">

<term>

<constant>Ev::FLAG_NOSIGMASK</constant>

</term>

<listitem>

<simpara>

When this flag is specified,

<literal>libev</literal>

will avoid to modify the signal mask. Specifically, this means having

to make sure signals are unblocked before receiving them.

</simpara>

<simpara>

This behaviour is useful for custom signal handling, or handling

signals only in specific threads.

</simpara>

</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>

<simpara>

Means that event loop will look for new events, will handle those

events and any already outstanding ones, but will not wait and block

the 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.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.run-once">

<term>

<constant>Ev::RUN_ONCE</constant>

</term>

<listitem>

<simpara>

Means that event loop will look for new events (waiting if necessary)

and will handle those and any already outstanding ones. It will block

the 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.

</simpara>

</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>

<simpara>

Cancel the break operation.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.break-one">

<term>

<constant>Ev::BREAK_ONE</constant>

</term>

<listitem>

<simpara>

Makes the innermost

<methodname>Ev::run</methodname>

(or

<methodname>EvLoop::run</methodname>)

call return.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.break-all">

<term>

<constant>Ev::BREAK_ALL</constant>

</term>

<listitem>

<simpara>

Makes all nested

<methodname>Ev::run</methodname>

(or

<methodname>EvLoop::run</methodname>)

calls return.

</simpara>

</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>

<simpara>

Minimum allowed watcher priority.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.maxpri">

<term>

<constant>Ev::MAXPRI</constant>

</term>

<listitem>

<simpara>

Maximum allowed watcher priority.

</simpara>

</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>

<simpara>

The file descriptor in the

<classname>EvIo</classname>

watcher has become readable.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.write">

<term>

<constant>Ev::WRITE</constant>

</term>

<listitem>

<simpara>

The file descriptor in the

<classname>EvIo</classname>

watcher has become writable.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.timer">

<term>

<constant>Ev::TIMER</constant>

</term>

<listitem>

<simpara>

<classname>EvTimer</classname>

watcher has been timed out.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.periodic">

<term>

<constant>Ev::PERIODIC</constant>

</term>

<listitem>

<simpara>

<classname>EvPeriodic</classname>

watcher has been timed out.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.signal">

<term>

<constant>Ev::SIGNAL</constant>

</term>

<listitem>

<simpara>

A signal specified in

<methodname>EvSignal::__construct</methodname>

has been received.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.child">

<term>

<constant>Ev::CHILD</constant>

</term>

<listitem>

<simpara>

The

<parameter>pid</parameter>

specified in

<methodname>EvChild::__construct</methodname>

has received a status change.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.stat">

<term>

<constant>Ev::STAT</constant>

</term>

<listitem>

<simpara>

The path specified in

<classname>EvStat</classname>

watcher changed its attributes.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.idle">

<term>

<constant>Ev::IDLE</constant>

</term>

<listitem>

<simpara>

<classname>EvIdle</classname>

watcher works when there is nothing to do with other watchers.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.prepare">

<term>

<constant>Ev::PREPARE</constant>

</term>

<listitem>

<simpara>

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.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.check">

<term>

<constant>Ev::CHECK</constant>

</term>

<listitem>

<simpara>

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.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.embed">

<term>

<constant>Ev::EMBED</constant>

</term>

<listitem>

<simpara>

The embedded event loop specified in the

<classname>EvEmbed</classname>

watcher needs attention.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.custom">

<term>

<constant>Ev::CUSTOM</constant>

</term>

<listitem>

<simpara>

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>

).

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.error">

<term>

<constant>Ev::ERROR</constant>

</term>

<listitem>

<simpara>

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>

</simpara>

</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>

<simpara>

<literal>select(2) backend</literal>

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.backend-poll">

<term>

<constant>Ev::BACKEND_POLL</constant>

</term>

<listitem>

<simpara>

<literal>poll(2) backend</literal>

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.backend-epoll">

<term>

<constant>Ev::BACKEND_EPOLL</constant>

</term>

<listitem>

<simpara>

Linux-specific

<literal>epoll(7)</literal>

backend for both pre- and post-2.6.9 kernels

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.backend-kqueue">

<term>

<constant>Ev::BACKEND_KQUEUE</constant>

</term>

<listitem>

<simpara>

<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, one can try to create an event loop with

<literal>kqueue</literal>

backend and use it for sockets only.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.backend-devpoll">

<term>

<constant>Ev::BACKEND_DEVPOLL</constant>

</term>

<listitem>

<simpara>

Solaris 8 backend. This is not implemented yet.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.backend-port">

<term>

<constant>Ev::BACKEND_PORT</constant>

</term>

<listitem>

<simpara>

Solaris 10 event port mechanism with a good scaling.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.backend-all">

<term>

<constant>Ev::BACKEND_ALL</constant>

</term>

<listitem>

<simpara>

Try all backends(even currupted ones). It's not recommended to use it

explicitly. Bitwise operators should be applied here(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.

</simpara>

</listitem>

</varlistentry>

<varlistentry xml:id="ev.constants.backend-mask">

<term>

<constant>Ev::BACKEND_MASK</constant>

</term>

<listitem>

<simpara>

Not a backend, but a mask to select all backend bits from

<parameter>flags</parameter>

value to mask out any backends(e.g. when modifying the

<varname>LIBEV_FLAGS</varname>

environment variable).

</simpara>

</listitem>

</varlistentry>

</variablelist>

</para>

<note xmlns="http://docbook.org/ns/docbook">

<simpara>

For the default loop during module initialization phase

<literal>Ev</literal>

registers

<link xlink:href="&url.ev.loop;">ev_loop_fork</link>

call by means of

<literal>pthread_atfork</literal>

(if available).

</simpara>

</note>

<note xmlns="http://docbook.org/ns/docbook">

<simpara>

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>)

these values may be accessed via corresponding properties and methods

of the

<classname>EvLoop</classname>

class.

</simpara>

<simpara>

The instance of the default event loop itself can be fetched by means of

<methodname>EvLoop::defaultLoop</methodname>

method.

</simpara>

</note>

</section>

</partintro>

&reference.ev.entities.ev;

</reference>