view release on metacpan or  search on metacpan

lib/Event.pod  view on Meta::CPAN

triggering an idle watcher then set C<max> to C<undef> or C<stop()> it.)

=item one_event([$timeout])

If any events are outstanding then invoke the corresponding callback
of the highest priority event.  If there are no events available,
block forever or until $timeout.  Use of this API is not recommended
because it is not efficient and does not trap exceptions.  However,
you might wish to understand how it works:

=over 4

=item 1

Queue asyncronous events (signals, etc).  That is, previously recorded
events are reified.

=item 2

If there are any events with priority 5 or less (see StarvePrio) then
service the next one and return.

=item 3

Calculate the maximum wait time (minimum time till the next timer
expiration) and pass control to the poll/select system call.  Upon
return, queue all pending events.

=item 4

Queue asyncronous events again.

=item 5

If there are any events then service the next one and return.

=item 6

Service the next idle watcher.

=back

StarvePrio is the priority level for which events are dispatched
during step 2.  It cannot be changed without a recompile.  In the rare
case that an event is always pending at step 2 then I/O watchers will
starve.  However, this is highly unlikely since async watchers should
never queue events so rapidly.

=item all_watchers()

Returns a list of all watchers (including stopped watchers).

=item all_running()

Returns a list of all watchers with actively running callbacks.
Watchers are returned in order of most recent to least recent.

=item all_idle()

Returns a list of all the idle watchers.
If the event queue is very busy, all the idle watchers will sit on the
idle queue waiting to run.  However, be aware that if an idle watcher
has the C<max> attribute set then it will queue a normal event when
its C<max> wait time is exceeded.

=item queue_pending()

Examines asynchronous source events (timers & signals) and reifies
them as target events. C<queue_pending()> is only called implicitly by
C<sweep()> and C<one_event()>.  Otherwise, C<queue_pending()> is not
called implicitly.

NOTE: Signal watchers generate target events according to which
watchers are active at the time that C<queue_pending()> is called
rather than according to the time the signal is received.  This is
best explained by example.  See the file C<demo/queue_pending.t>.

=back

=head2 Event Watcher Constructors

All watchers are constructed in one of the following ways:

  $w = Event->flavor( [attr1 => $value,]... );
 
  $w = Event::flavor($Class, [attr1 => $value,]...);

  $w = Event::flavor->new([attr1 => $value,]...);

Where I<flavor> is substituted with the kind of watcher.  Built-in
types include idle, io, signal, timer, and var.

New watchers (hopefully) have reasonable defaults and can also be
customized by passing extra attributes to the constructor.  When
created, watcher objects are "started" and are waiting for events
(see C<$event-E<gt>start> below).

NetServer::Portal can display watchers in real-time, formatted
similarly to the popular C<top> program.  You may find this a useful
aide for debugging.

=head2 Shared Watcher Attributes

Watchers are configured with attributes (also known as properties).
For example:

   $watcher->cb(\&some_code);   # set callback

   warn $event->w->desc.": ".$event->hits." events happened; Wow!";

All watchers support the following attributes: cb, cbtime, debug,
desc, prio, max_cb_tm, reentrant, and repeat.  Watcher constructors
accept the preceding and additionally: async and nice.
Moreover, watchers also offer extra
attributes according to their specialty.

=head2 Shared Watcher Methods

The following methods are available for all watchers:

=over 4