eio_write
Introduction
Process Control Extensions
PHP Manual

# Ev

Table of Contents

- Introduction
- Installing/Configuring
  - Requirements
  - Installation
  - Runtime Configuration
  - Resource Types
- Predefined Constants
- Examples
- Watchers
- Watcher callbacks
- Periodic watcher operation modes
- Ev — The Ev class
  - Ev::backend — Returns an integer describing the backend used by libev.
  - Ev::depth — Returns recursion depth
  - Ev::embeddableBackends — Returns the set of backends that are embeddable in other event loops.
  - Ev::feedSignal — Feed a signal event info Ev
  - Ev::feedSignalEvent — Feed signal event into the default loop
  - Ev::iteration — Return the number of times the default event loop has polled for new events.
  - Ev::now — Returns the time when the last iteration of the default event loop has started.
  - Ev::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by Ev::now in the progress.
  - Ev::recommendedBackends — Returns a bit mask of recommended backends for current platform.
  - Ev::resume — Resume previously suspended default event loop
  - Ev::run — Begin checking for events and calling callbacks for the default loop
  - Ev::sleep — Block the process for the given number of seconds.
  - Ev::stop — Stops the default event loop
  - Ev::supportedBackends — Returns the set of backends supported by current libev configuration.
  - Ev::suspend — Suspend the default event loop
  - Ev::time — Returns the current time in fractional seconds since the epoch.
  - Ev::verify — Performs internal consistency checks(for debugging)
- EvCheck — The EvCheck class
  - EvCheck::__construct — Constructs the EvCheck watcher object
  - EvCheck::createStopped — Create instance of a stopped EvCheck watcher
- EvChild — The EvChild class
  - EvChild::__construct — Constructs the EvChild watcher object
  - EvChild::createStopped — Create instance of a stopped EvCheck watcher
  - EvChild::set — Configures the watcher
- EvEmbed — The EvEmbed class
  - EvEmbed::__construct — Constructs the EvEmbed object
  - EvEmbed::createStopped — Create stopped EvEmbed watcher object
  - EvEmbed::set — Configures the watcher
  - EvEmbed::sweep — Make a single, non-blocking sweep over the embedded loop.
- EvFork — The EvFork class
  - EvFork::__construct — Constructs the EvFork watcher object
  - EvFork::createStopped — Creates a stopped instance of EvFork watcher class
- EvIdle — The EvIdle class
  - EvIdle::__construct — Constructs the EvIdle watcher object
  - EvIdle::createStopped — Creates instance of a stopped EvIdle watcher object
- EvIo — The EvIo class
  - EvIo::__construct — Constructs EvIo watcher object
  - EvIo::createStopped — Create stopped EvIo watcher object
  - EvIo::set — Configures the watcher
- EvLoop — The EvLoop class
  - EvLoop::backend — Returns an integer describing the backend used by libev.
  - EvLoop::check — Creates EvCheck object associated with the current event loop instance
  - EvLoop::child — Creates EvChild object associated with the current event loop
  - EvLoop::__construct — Constructs the event loop object
  - EvLoop::defaultLoop — Returns or creates the default event loop.
  - EvLoop::embed — Creates an instance of EvEmbed watcher associated with the current EvLoop object.
  - EvLoop::fork — Creates EvFork watcher object associated with the current event loop instance
  - EvLoop::idle — Creates EvIdle watcher object associated with the current event loop instance
  - EvLoop::invokePending — Invoke all pending watchers while resetting their pending state
  - EvLoop::io — Create EvIo watcher object associated with the current event loop instance
  - EvLoop::loopFork — Must be called after a fork
  - EvLoop::now — Returns the current "event loop time"
  - EvLoop::nowUpdate — Establishes the current time by querying the kernel, updating the time returned by EvLoop::now in the progress.
  - EvLoop::periodic — Creates EvPeriodic watcher object associated with the current event loop instance
  - EvLoop::prepare — Creates EvPrepare watcher object associated with the current event loop instance
  - EvLoop::resume — Resume previously suspended default event loop
  - EvLoop::run — Begin checking for events and calling callbacks for the loop
  - EvLoop::signal — Creates EvSignal watcher object associated with the current event loop instance
  - EvLoop::stat — Creates EvStat watcher object associated with the current event loop instance
  - EvLoop::stop — Stops the event loop
  - EvLoop::suspend — Suspend the loop
  - EvLoop::timer — Creates EvTimer watcher object associated with the current event loop instance
  - EvLoop::verify — Performs internal consistency checks(for debugging)
- EvPeriodic — The EvPeriodic class
  - EvPeriodic::again — Simply stops and restarts the periodic watcher again.
  - EvPeriodic::at — Returns the absolute time that this watcher is supposed to trigger next
  - EvPeriodic::__construct — Constructs EvPeriodic watcher object
  - EvPeriodic::createStopped — Create a stopped EvPeriodic watcher
  - EvPeriodic::set — Configures the watcher
- EvPrepare — The EvPrepare class
  - EvPrepare::__construct — Constructs EvPrepare watcher object
  - EvPrepare::createStopped — Creates a stopped instance of EvPrepare watcher
- EvSignal — The EvSignal class
  - EvSignal::__construct — Constructs EvPeriodic watcher object
  - EvSignal::createStopped — Create stopped EvSignal watcher object
  - EvSignal::set — Configures the watcher
- EvStat — The EvStat class
  - EvStat::attr — Returns the values most recently detected by Ev
  - EvStat::__construct — Constructs EvStat watcher object
  - EvStat::createStopped — Create a stopped EvStat watcher object
  - EvStat::prev — Returns the previous set of values returned by EvStat::attr
  - EvStat::set — Configures the watcher
  - EvStat::stat — Initiates the stat call
- EvTimer — The EvTimer class
  - EvTimer::again — Restarts the timer watcher
  - EvTimer::__construct — Constructs an EvTimer watcher object
  - EvTimer::createStopped — Creates EvTimer stopped watcher object
  - EvTimer::set — Configures the watcher
- EvWatcher — The EvWatcher class
  - EvWatcher::clear — Clear watcher pending status
  - EvWatcher::__construct — Abstract constructor of a watcher object
  - EvWatcher::feed — Feeds the given revents set into the event loop
  - EvWatcher::getLoop — Returns the loop responsible for the watcher
  - EvWatcher::invoke — Invokes the watcher callback with the given received events bit mask
  - EvWatcher::keepalive — Configures whether to keep the loop from returning
  - EvWatcher::setCallback — Sets new callback for the watcher
  - EvWatcher::start — Starts the watcher
  - EvWatcher::stop — Stops the watcher

# The Ev class

## Introduction

Ev is a singleton providing access to the default loop and to some common operations.

## Class synopsis

Ev
final class Ev {
/* Constants */
const integer Ev::FLAG_AUTO = 0 ;
const integer Ev::FLAG_NOENV = 16777216 ;
const integer Ev::FLAG_FORKCHECK = 33554432 ;
const integer Ev::FLAG_NOINOTIFY = 1048576 ;
const integer Ev::FLAG_SIGNALFD = 2097152 ;
const integer Ev::FLAG_NOSIGMASK = 4194304 ;
const integer Ev::RUN_NOWAIT = 1 ;
const integer Ev::RUN_ONCE = 2 ;
const integer Ev::BREAK_CANCEL = 0 ;
const integer Ev::BREAK_ONE = 1 ;
const integer Ev::BREAK_ALL = 2 ;
const integer Ev::MINPRI = -2 ;
const integer Ev::MAXPRI = 2 ;
const integer Ev::READ = 1 ;
const integer Ev::WRITE = 2 ;
const integer Ev::TIMER = 256 ;
const integer Ev::PERIODIC = 512 ;
const integer Ev::SIGNAL = 1024 ;
const integer Ev::CHILD = 2048 ;
const integer Ev::STAT = 4096 ;
const integer Ev::IDLE = 8192 ;
const integer Ev::PREPARE = 16384 ;
const integer Ev::CHECK = 32768 ;
const integer Ev::EMBED = 65536 ;
const integer Ev::CUSTOM = 16777216 ;
const integer Ev::ERROR = 2147483648 ;
const integer Ev::BACKEND_SELECT = 1 ;
const integer Ev::BACKEND_POLL = 2 ;
const integer Ev::BACKEND_EPOLL = 4 ;
const integer Ev::BACKEND_KQUEUE = 8 ;
const integer Ev::BACKEND_DEVPOLL = 16 ;
const integer Ev::BACKEND_PORT = 32 ;
const integer Ev::BACKEND_ALL = 63 ;
const integer Ev::BACKEND_MASK = 65535 ;
/* Methods */
final public static int backend ( void )
final public static int depth ( void )
final public static void embeddableBackends ( void )
final public static void feedSignal ( int `$signum` )
final public static void feedSignalEvent ( int `$signum` )
final public static int iteration ( void )
final public static double now ( void )
final public static void nowUpdate ( void )
final public static void recommendedBackends ( void )
final public static void resume ( void )
final public static void run ([ int `$flags` ] )
final public static void sleep ( double `$seconds` )
final public static void stop ([ int `$how` ] )
final public static void supportedBackends ( void )
final public static void suspend ( void )
final public static double time ( void )
final public static void verify ( void )
}

## Predefined Constants

Flags passed to create a loop:

`Ev::FLAG_AUTO`

  The default flags value

`Ev::FLAG_NOENV`

  If this flag used(or the program runs setuid or setgid), libev won't look at the environment variable LIBEV_FLAGS . Otherwise(by default), LIBEV_FLAGS will override the flags completely if it is found. Useful for performance tests and searching for bugs.

`Ev::FLAG_FORKCHECK`

  Makes libev check for a fork in each iteration, instead of calling EvLoop::fork manually. This works by calling getpid() 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 LIBEV_FLAGS environment variable.

`Ev::FLAG_NOINOTIFY`

  When this flag is specified, libev won't attempt to use the inotify API for its » ev_stat watchers. The flag can be useful to conserve inotify file descriptors, as otherwise each loop using ev_stat watchers consumes one inotify handle.

`Ev::FLAG_SIGNALFD`

  When this flag is specified, libev will attempt to use the signalfd API for its » ev_signal (and » ev_child ) 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. Signalfd will not be used by default.

`Ev::FLAG_NOSIGMASK`

  When this flag is specified, libev will avoid to modify the signal mask. Specifically, this means having to make sure signals are unblocked before receiving them.

  This behaviour is useful for custom signal handling, or handling signals only in specific threads.

Flags passed to Ev::run , or EvLoop::run

`Ev::RUN_NOWAIT`

  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.

`Ev::RUN_ONCE`

  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.

Flags passed to Ev::stop , or EvLoop::stop

`Ev::BREAK_CANCEL`

  Cancel the break operation.

`Ev::BREAK_ONE`

  Makes the innermost Ev::run (or EvLoop::run ) call return.

`Ev::BREAK_ALL`

  Makes all nested Ev::run (or EvLoop::run ) calls return.

Watcher priorities:

`Ev::MINPRI`

  Minimum allowed watcher priority.

`Ev::MAXPRI`

  Maximum allowed watcher priority.

Bit masks of (received) events:

`Ev::READ`

  The file descriptor in the EvIo watcher has become readable.

`Ev::WRITE`

  The file descriptor in the EvIo watcher has become writable.

`Ev::TIMER`

  EvTimer watcher has been timed out.

`Ev::PERIODIC`

  EvPeriodic watcher has been timed out.

`Ev::SIGNAL`

  A signal specified in EvSignal::__construct has been received.

`Ev::CHILD`

  The `pid` specified in EvChild::__construct has received a status change.

`Ev::STAT`

  The path specified in EvStat watcher changed its attributes.

`Ev::IDLE`

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

`Ev::PREPARE`

  All EvPrepare watchers are invoked just before Ev::run starts. Thus, EvPrepare watchers are the last watchers invoked before the event loop sleeps or polls for new events.

`Ev::CHECK`

  All EvCheck watchers are queued just after Ev::run has gathered the new events, but before it queues any callbacks for any received events. Thus, EvCheck watchers will be invoked before any other watchers of the same or lower priority within an event loop iteration.

`Ev::EMBED`

  The embedded event loop specified in the EvEmbed watcher needs attention.

`Ev::CUSTOM`

  Not ever sent(or otherwise used) by libev itself, but can be freely used by libev users to signal watchers (e.g. via EvWatcher::feed ).

`Ev::ERROR`

  An unspecified error has occurred, the watcher has been stopped. This might happen because the watcher could not be properly started because libev ran out of memory, a file descriptor was found to be closed or any other problem. Libev considers these application bugs. See also » ANATOMY OF A WATCHER

Backend flags:

`Ev::BACKEND_SELECT`

  select(2) backend

`Ev::BACKEND_POLL`

  poll(2) backend

`Ev::BACKEND_EPOLL`

  Linux-specific epoll(7) backend for both pre- and post-2.6.9 kernels

`Ev::BACKEND_KQUEUE`

  kqueue backend used on most BSD systems. EvEmbed watcher could be used to embed one loop(with kqueue backend) into another. For instance, one can try to create an event loop with kqueue backend and use it for sockets only.

`Ev::BACKEND_DEVPOLL`

  Solaris 8 backend. This is not implemented yet.

`Ev::BACKEND_PORT`

  Solaris 10 event port mechanism with a good scaling.

`Ev::BACKEND_ALL`

  Try all backends(even currupted ones). It's not recommended to use it explicitly. Bitwise operators should be applied here(e.g. `Ev::BACKEND_ALL` & ~ `Ev::BACKEND_KQUEUE` ) Use Ev::recommendedBackends , or don't specify any backends at all.

`Ev::BACKEND_MASK`

  Not a backend, but a mask to select all backend bits from `flags` value to mask out any backends(e.g. when modifying the LIBEV_FLAGS environment variable).

> Note:

> For the default loop during module initialization phase Ev registers » ev_loop_fork call by means of pthread_atfork (if available).

> Note:

> There are methods providing access to the default event loop in Ev class(e.g. Ev::iteration , Ev::depth etc.) For custom loops (created with EvLoop::__construct ) these values may be accessed via corresponding properties and methods of the EvLoop class.

> The instance of the default event loop itself can be fetched by means of EvLoop::defaultLoop method.

# The EvCheck class

## Introduction

EvPrepare and EvCheck watchers are usually used in pairs. EvPrepare watchers get invoked before the process blocks, EvCheck afterwards.

It is not allowed to call EvLoop::run or similar methods or functions that enter the current event loop from either EvPrepare or EvCheck watchers. Other loops than the current one are fine, however. The rationale behind this is that one don't need to check for recursion in those watchers, i.e. the sequence will always be: EvPrepare -> blocking -> EvCheck , so having a watcher of each kind they will always be called in pairs bracketing the blocking call.

The main purpose is to integrate other event mechanisms into libev and their use is somewhat advanced. They could be used, for example, to track variable changes, implement custom watchers, integrate net-snmp or a coroutine library and lots more. They are also occasionally useful to cache some data and want to flush it before blocking.

It is recommended to give EvCheck watchers highest( `Ev::MAXPRI` ) priority, to ensure that they are being run before any other watchers after the poll (this doesn’t matter for EvPrepare watchers).

Also, EvCheck watchers should not activate/feed events. While libev fully supports this, they might get executed before other EvCheck watchers did their job.

## Class synopsis

EvCheck
class EvCheck extends EvWatcher {
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public __construct ( callable `$callback` [, mixed `$data` [, int `$priority` ]] )
final public static object createStopped ( string `$callback` [, string `$data` [, string `$priority` ]] )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

# The EvChild class

## Introduction

EvChild watchers trigger when the process receives a `SIGCHLD` in response to some child status changes (most typically when a child dies or exits). It is permissible to install an `EvChild` watcher after the child has been forked(which implies it might have already exited), as long as the event loop isn't entered(or is continued from a watcher), i.e. forking and then immediately registering a watcher for the child is fine, but forking and registering a watcher a few event loop iterations later or in the next callback invocation is not.

It is allowed to register EvChild watchers in the default loop only.

## Class synopsis

EvChild
class EvChild extends EvWatcher {
/* Properties */
public $pid ;
public $rpid ;
public $rstatus ;
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public __construct ( int `$pid` , bool `$trace` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
final public static object createStopped ( int `$pid` , bool `$trace` , callable `$callback` [, mixed `$data` [, int `$priority` ]] )
public void set ( int `$pid` , bool `$trace` )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

## Properties

pid

  Readonly . The process ID this watcher watches out for, or `0` , meaning any process ID.

rpid

  Readonly .The process ID that detected a status change.

rstatus

  Readonly . The process exit status caused by rpid .

# The EvEmbed class

## Introduction

Used to embed one event loop into another.

## Class synopsis

EvEmbed
class EvEmbed extends EvWatcher {
/* Properties */
public $embed ;
/* Methods */
public __construct ( object `$other` [, callable `$callback` [, mixed `$data` [, int `$priority` ]]] )
final public static void createStopped ( object `$other` [, callable `$callback` [, mixed `$data` [, int `$priority` ]]] )
public void set ( object `$other` )
public void sweep ( void )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

## Properties

is_active

data

is_pending

priority

embed

# The EvFork class

## Introduction

Fork watchers are called when a fork() was detected (usually because whoever signalled libev about it by calling EvLoop::fork ). The invocation is done before the event loop blocks next and before EvCheck watchers are being called, and only in the child after the fork. Note, that if whoever calling EvLoop::fork calls it in the wrong process, the fork handlers will be invoked, too.

## Class synopsis

EvFork
class EvFork extends EvWatcher {
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public __construct ( callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
final public static object createStopped ( string `$callback` [, string `$data` [, string `$priority` ]] )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

# The EvIdle class

## Introduction

EvIdle watchers trigger events when no other events of the same or higher priority are pending ( EvPrepare , EvCheck and other EvIdle watchers do not count as receiving events ).

Thus, as long as the process is busy handling sockets or timeouts(or even signals) of the same or higher priority it will not be triggered. But when the process is in idle(or only lower-priority watchers are pending), the EvIdle watchers are being called once per event loop iteration - until stopped, that is, or the process receives more events and becomes busy again with higher priority stuff.

Apart from keeping the process non-blocking(which is a useful on its own sometimes), EvIdle watchers are a good place to do "pseudo-background processing" , or delay processing stuff to after the event loop has handled all outstanding events.

The most noticeable effect is that as long as any idle watchers are active, the process will not block when waiting for new events.

## Class synopsis

EvIdle
class EvIdle extends EvWatcher {
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public __construct ( callable `$callback` [, mixed `$data` [, int `$priority` ]] )
final public static object createStopped ( string `$callback` [, mixed `$data` [, int `$priority` ]] )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

# The EvIo class

## Introduction

EvIo watchers check whether a file descriptor(or socket, or a stream castable to numeric file descriptor) is readable or writable in each iteration of the event loop, or, more precisely, when reading would not block the process and writing would at least be able to write some data. This behaviour is called level-triggering because events are kept receiving as long as the condition persists. To stop receiving events just stop the watcher.

The number of read and/or write event watchers per `fd` is unlimited. Setting all file descriptors to non-blocking mode is also usually a good idea(but not required).

Another thing to watch out for is that it is quite easy to receive false readiness notifications, i.e. the callback might be called with `Ev::READ` but a subsequent read() will actually block because there is no data. It is very easy to get into this situation. Thus it is best to always use non-blocking I/O: An extra read() returning `EAGAIN` (or similar) is far preferable to a program hanging until some data arrives.

If for some reason it is impossible to run the `fd` in non-blocking mode, then separately re-test whether a file descriptor is really ready. Some people additionally use `SIGALRM` and an interval timer, just to be sure thry won't block infinitely.

Always consider using non-blocking mode.

## Class synopsis

EvIo
class EvIo extends EvWatcher {
/* Properties */
public $fd ;
public $events ;
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public __construct ( mixed `$fd` , int `$events` , callable `$callback` [, mixed `$data` [, int `$priority` ]] )
final public static EvIo createStopped ( mixed `$fd` , int `$events` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void set ( mixed `$fd` , int `$events` )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

## Properties

fd

events

# The EvLoop class

## Introduction

Represents an event loop that is always distinct from the default loop . Unlike the default loop , it cannot handle EvChild watchers.

Having threads we have to create a loop per thread, and use the the default loop in the parent thread.

The default event loop is initialized automatically by Ev . It is accessable via methods of the Ev class, or via EvLoop::defaultLoop method.

## Class synopsis

EvLoop
final class EvLoop {
/* Properties */
public $data ;
public $backend ;
public $is_default_loop ;
public $iteration ;
public $pending ;
public $io_interval ;
public $timeout_interval ;
public $depth ;
/* Methods */
public int backend ( void )
final public EvCheck check ( string `$callback` [, string `$data` [, string `$priority` ]] )
final public EvChild child ( string `$pid` , string `$trace` , string `$callback` [, string `$data` [, string `$priority` ]] )
public __construct ([ int `$flags` [, mixed `$data` = NULL [, double `$io_interval` = 0.0 [, double `$timeout_interval` = 0.0 ]]]] )
public static EvLoop defaultLoop ([ int `$flags` = Ev::FLAG_AUTO [, mixed `$data` = NULL [, double `$io_interval` = 0. [, double `$timeout_interval` = 0. ]]]] )
final public EvEmbed embed ( string `$other` [, string `$callback` [, string `$data` [, string `$priority` ]]] )
final public EvFork fork ( callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
final public EvIdle idle ( callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void invokePending ( void )
final public EvIo io ( mixed `$fd` , int `$events` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void loopFork ( void )
public double now ( void )
public void nowUpdate ( void )
final public EvPeriodic periodic ( double `$offset` , double `$interval` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
final public EvPrepare prepare ( callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void resume ( void )
public void run ([ int `$flags` = 0 ] )
final public EvSignal signal ( int `$signum` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
final public EvStat stat ( string `$path` , double `$interval` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void stop ([ int `$how` ] )
public void suspend ( void )
final public EvTimer timer ( double `$after` , double `$repeat` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void verify ( void )
}

## Properties

data

  Custom data attached to loop

backend

  Readonly . The backend flags indicating the event backend in use.

is_default_loop

  Readonly . `TRUE` if it is the default event loop.

iteration

  The current iteration count of the loop. See Ev::iteration

pending

  The number of pending watchers. `0` indicates that there are no watchers pending.

io_interval

  Higher io_interval allows libev to spend more time collecting EvIo events, so more events can be handled per iteration, at the cost of increasing latency. Timeouts (both EvPeriodic and EvTimer ) will not be affected. Setting this to a non-zero value will introduce an additional sleep() call into most loop iterations. The sleep time ensures that libev will not poll for EvIo events events more often than once per this interval, on average. Many programs can usually benefit by setting the io_interval to a value near `0.1` , which is often enough for interactive servers(not for games). It usually doesn't make much sense to set it to a lower value than `0.01` , as this approaches the timing granularity of most systems.

  See also » FUNCTIONS CONTROLLING EVENT LOOPS .

timeout_interval

  Higher timeout_interval allows libev to spend more time collecting timeouts, at the expense of increased latency/jitter/inexactness(the watcher callback will be called later). EvIo watchers will not be affected. Setting this to a non-null value will not introduce any overhead in libev . See also » FUNCTIONS CONTROLLING EVENT LOOPS .

depth

  The recursion depth. See Ev::depth .

# The EvPeriodic class

## Introduction

Periodic watchers are also timers of a kind, but they are very versatile.

Unlike EvTimer , EvPeriodic watchers are not based on real time(or relative time, the physical time that passes) but on wall clock time(absolute time, calendar or clock). The difference is that wall clock time can run faster or slower than real time, and time jumps are not uncommon(e.g. when adjusting it).

EvPeriodic watcher can be configured to trigger after some specific point in time. For example, if an EvPeriodic watcher is configured to trigger "in 10 seconds" (e.g. EvLoop::now + `10.0` , i.e. an absolute time, not a delay), and the system clock is reset to January of the previous year , then it will take a year or more to trigger the event (unlike an EvTimer , which would still trigger roughly `10` seconds after starting it as it uses a relative timeout).

As with timers, the callback is guaranteed to be invoked only when the point in time where it is supposed to trigger has passed. If multiple timers become ready during the same loop iteration then the ones with earlier time-out values are invoked before ones with later time-out values (but this is no longer true when a callback calls EvLoop::run recursively).

## Class synopsis

EvPeriodic
class EvPeriodic extends EvWatcher {
/* Properties */
public $offset ;
public $interval ;
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public void again ( void )
public double at ( void )
public __construct ( double `$offset` , string `$interval` , callable `$reschedule_cb` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
final public static EvPeriodic createStopped ( double `$offset` , double `$interval` , callable `$reschedule_cb` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void set ( double `$offset` , double `$interval` )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

## Properties

offset

  When repeating, this contains the offset value, otherwise this is the absolute point in time(the offset value passed to EvPeriodic::set , although libev might modify this value for better numerical stability).

interval

  The current interval value. Can be modified any time, but changes only take effect when the periodic timer fires or EvPeriodic::again is being called.

# The EvPrepare class

## Introduction

EvPrepare and EvCheck watchers are usually used in pairs. EvPrepare watchers get invoked before the process blocks, EvCheck afterwards.

It is not allowed to call EvLoop::run or similar methods or functions that enter the current event loop from either EvPrepare or EvCheck watchers. Other loops than the current one are fine, however. The rationale behind this is that one don't need to check for recursion in those watchers, i.e. the sequence will always be: EvPrepare -> blocking -> EvCheck , so having a watcher of each kind they will always be called in pairs bracketing the blocking call.

The main purpose is to integrate other event mechanisms into libev and their use is somewhat advanced. They could be used, for example, to track variable changes, implement custom watchers, integrate net-snmp or a coroutine library and lots more. They are also occasionally useful to cache some data and want to flush it before blocking.

It is recommended to give EvCheck watchers highest( `Ev::MAXPRI` ) priority, to ensure that they are being run before any other watchers after the poll (this doesn’t matter for EvPrepare watchers).

Also, EvCheck watchers should not activate/feed events. While libev fully supports this, they might get executed before other EvCheck watchers did their job.

## Class synopsis

EvPrepare
class EvPrepare extends EvWatcher {
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public __construct ( string `$callback` [, string `$data` [, string `$priority` ]] )
final public static EvPrepare createStopped ( callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

# The EvSignal class

## Introduction

EvSignal watchers will trigger an event when the process receives a specific signal one or more times. Even though signals are very asynchronous, libev will try its best to deliver signals synchronously, i.e. as part of the normal event processing, like any other event.

There is no limit for the number of watchers for the same signal, but only within the same loop, i.e. one can watch for `SIGINT` in the default loop and for `SIGIO` in another loop, but it is not allowed to watch for `SIGINT` in both the default loop and another loop at the same time. At the moment, `SIGCHLD` is permanently tied to the default loop.

If possible and supported, libev will install its handlers with SA_RESTART (or equivalent) behaviour enabled, so system calls should not be unduly interrupted. In case of a problem with system calls getting interrupted by signals, all the signals can be blocked in an EvCheck watcher and unblocked in a EvPrepare watcher.

## Class synopsis

EvSignal
class EvSignal extends EvWatcher {
/* Properties */
public $signum ;
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public __construct ( int `$signum` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
final public static EvSignal createStopped ( int `$signum` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void set ( int `$signum` )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

## Properties

signum

  Signal number. See the constants exported by pcntl extension. See also signal(7) man page.

# The EvStat class

## Introduction

EvStat monitors a file system path for attribute changes. It calls stat() on that path in regular intervals(or when the OS signals it changed) and sees if it changed compared to the last time, invoking the callback if it did.

The path does not need to exist: changing from "path exists" to "path does not exist" is a status change like any other. The condition "path does not exist" is signified by the `'nlink'` item being 0(returned by EvStat::attr method).

The path must not end in a slash or contain special components such as `'.'` or `..` . The path should be absolute: if it is relative and the working directory changes, then the behaviour is undefined.

Since there is no portable change notification interface available, the portable implementation simply calls stat() regularly on the path to see if it changed somehow. For this case a recommended polling interval can be specified. If one specifies a polling interval of `0.0` (highly recommended) then a suitable, unspecified default value will be used(which could be expected to be around 5 seconds, although this might change dynamically). libev will also impose a minimum interval which is currently around `0.1` , but that’s usually overkill.

This watcher type is not meant for massive numbers of EvStat watchers, as even with OS-supported change notifications, this can be resource-intensive.

## Class synopsis

EvStat
class EvStat extends EvWatcher {
/* Properties */
public $path ;
public $interval ;
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public array attr ( void )
public __construct ( string `$path` , double `$interval` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
final public static void createStopped ( string `$path` , double `$interval` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void prev ( void )
public void set ( string `$path` , double `$interval` )
public bool stat ( void )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

## Properties

interval

  Readonly . Hint on how quickly a change is expected to be detected and should normally be specified as `0.0` to let libev choose a suitable value.

path

  Readonly . The path to wait for status changes on.

# The EvTimer class

## Introduction

EvTimer watchers are simple relative timers that generate an event after a given time, and optionally repeating in regular intervals after that.

The timers are based on real time, that is, if one registers an event that times out after an hour and resets the system clock to January last year , it will still time out after(roughly) one hour. "Roughly" because detecting time jumps is hard, and some inaccuracies are unavoidable.

The callback is guaranteed to be invoked only after its timeout has passed (not at, so on systems with very low-resolution clocks this might introduce a small delay). If multiple timers become ready during the same loop iteration then the ones with earlier time-out values are invoked before ones of the same priority with later time-out values (but this is no longer true when a callback calls EvLoop::run recursively).

The timer itself will do a best-effort at avoiding drift, that is, if a timer is configured to trigger every `10` seconds, then it will normally trigger at exactly `10` second intervals. If, however, the script cannot keep up with the timer because it takes longer than those `10` seconds to do) the timer will not fire more than once per event loop iteration.

## Class synopsis

EvTimer
class EvTimer extends EvWatcher {
/* Properties */
public $repeat ;
public $remaining ;
/* Inherited properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public void again ( void )
public __construct ( double `$after` , double `$repeat` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
final public static EvTimer createStopped ( double `$after` , double `$repeat` , callable `$callback` [, mixed `$data` = `NULL` [, int `$priority` = 0 ]] )
public void set ( double `$after` , double `$repeat` )
/* Inherited methods */
public int EvWatcher::clear ( void )
abstract public EvWatcher::__construct ( void )
public void EvWatcher::feed ( int `$revents` )
public EvLoop EvWatcher::getLoop ( void )
public void EvWatcher::invoke ( int `$revents` )
public bool EvWatcher::keepalive ([ bool `$value` ] )
public void EvWatcher::setCallback ( callable `$callback` )
public void EvWatcher::start ( void )
public void EvWatcher::stop ( void )
}

## Properties

repeat

  If repeat is `0.0` , then it will automatically be stopped once the timeout is reached. If it is positive, then the timer will automatically be configured to trigger again every repeat seconds later, until stopped manually.

remaining

  Returns the remaining time until a timer fires. If the timer is active, then this time is relative to the current event loop time, otherwise it's the timeout value currently configured.

  That is, after instanciating an EvTimer with an `after` value of `5.0` and `repeat` value of `7.0` , remaining returns `5.0` . When the timer is started and one second passes, remaining will return `4.0` . When the timer expires and is restarted, it will return roughly `7.0` (likely slightly less as callback invocation takes some time too), and so on.

# The EvWatcher class

## Introduction

EvWatcher is a base class for all watchers( EvCheck , EvChild etc.). Since EvWatcher 's constructor is abstract , one can't(and don't need to) create EvWatcher objects directly.

## Class synopsis

EvWatcher
abstract class EvWatcher {
/* Properties */
public $is_active ;
public $data ;
public $is_pending ;
public $priority ;
/* Methods */
public int clear ( void )
abstract public __construct ( void )
public void feed ( int `$revents` )
public EvLoop getLoop ( void )
public void invoke ( int `$revents` )
public bool keepalive ([ bool `$value` ] )
public void setCallback ( callable `$callback` )
public void start ( void )
public void stop ( void )
}

## Properties

is_active

  Readonly . `TRUE` if the watcher is active. `FALSE` otherwise.

data

  User custom data associated with the watcher

is_pending

  Readonly .`TRUE` if the watcher is pending, i.e. it has outstanding events, but its callback has not yet been invoked. `FALSE` otherwise. As long, as a watcher is pending(but not active), one must not change its priority.

priority

  Integer between `Ev::MINPRI` and `Ev::MAXPRI` . Pending watchers with higher priority will be invoked before watchers with lower priority, but priority will not keep watchers from being executed(except for EvIdle watchers). EvIdle watchers provide functionality to suppress invocation when higher priority events are pending.