/export/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/Event/blib/html/site/lib/Event.html

/export/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/Event/blib/html/site/lib/Event.html

PRIORITY</PRE>

PRIORITY</PRE> Priority is used to sort the event queue. Meaningful priorities range from -1 to 6 inclusive. Lower numbers mean higher priority (-1 is the highest priority and 6 is the lowest). If multiple events get queued, the ones with the highest priority are serviced first. Events with equal priority are serviced in first-in-first-out order. <PRE> use Event qw(PRIO_HIGH PRIO_NORMAL); # some constants</PRE> <PRE> LEVELS: -1 0 1 2 3 4 5 6 ----------------------+-------------+--------------- PRIO_HIGH PRIO_NORMA PRE A negative priority causes the callback to be invoked immediately upon event occurrence. Use this with caution. While it may seem advantageous to use negative priorities, they bypass the whole point of having an event queue. Each watcher has a default priority, assigned by its constructor: <PRE> io PRIO_NORMAL signal PRIO_HIGH timer PRIO_NORMAL var PRIO_NORMAPRE Default priorities are stored in ${``Event::${type}::DefaultPriority''}. If the default priority is not satisfactory for your purposes, the constructor options <CODE>nice</CODE>, <CODE>async</CODE>, or <CODE>prio</CODE> can be used to adjust it. <CODE>nice</CODE> specifies an offset from the default priority; <CODE>async</CODE> forces the priority to -1; and <CODE>prio</CODE> assigns a given priority of your choice. If more than one of these options are given then <CODE>prio</CODE> overrides <CODE>async</CODE> overrides <CODE>nice</CODE>. <H2><A NAME=``watcher constructor attributes''>WATCHER CONSTRUCTOR ATTRIBUTE/A</H2> These options are only supported as constructor arguments. <DL> <DT><A NAME=``item_after_%3D%3E_%24seconds''>after => $seconds</A> <DD> See the discussion of the timer watcher. <DT><A NAME=``item_async_%3D%3E_%24bool''>async => $bool</A> <DD> If $bool then the watcher priority is set to -1. <DT><A NAME=``item_nice_%3D%3E_%24offset''>nice => $offset</A> <DD> Offset from the default priority. <DT><A NAME=``item_parked_%3D%3E_%24yes''>parked => $yes</A> <DD> By default, watcher constructors automatically invoke the <A HREF=``#item_start''><CODE>start()</CODE></A> method. If you don't want the watcher started then request <CODE>parked=>1</CODE>. </DL> <H2><A NAME=``watcher attributes''>WATCHER ATTRIBUTE/A</H2> <DL> <DT><A NAME=``item_at_%3D%3E_%24time''>at => $time</A> <DD> The expiration time in the same units as the system clock. For a timer, <CODE>at</CODE> will usually be in the future. <DT><A NAME=``item_cb_%3D%3E_%5C%26code''>cb => \&code</A> <DD> <DT><A NAME=``item_cb_%3D%3E_%5B%24class_or_object%2C_%24method_name%''>cb => [$class_or_object, $method_name]</A> <DD> The function or method to call when an event is dispatched. The callback is invoked with <CODE>$event</CODE> as its only argument. Perhaps you are wondering what happens if something goes wrong and an untrapped <CODE>die</CODE> occurs within your callback? <A HREF=``#item_%24Event%3A%3ADIED''><CODE>$Event::DIED</CODE></A> is just for this purpose. See the full description of <CODE>DIED</CODE> below. <DT><A NAME=``item_cbtime_%3D%3E_%24time''>cbtime => $time</A> <DD> When the callback was invoked most recently. <DT><A NAME=``item_data_%3D%3E_%24anything''>data => $anything</A> <DD> The <CODE>data()</CODE> method associates arbitrary data with a watcher. This method is not intended for implementers of watchers. If you are subclassing or implementing a watcher, consider the <CODE>private()</CODE> method. <DT><A NAME=``item_debug_%3D%3E_%24bool''>debug => $bool</A> <DD> Debugging can be activated globally or per watcher. When debugging is enabled for a particular watcher, $Event::DebugLevel is treated as two levels higher. Levels of 1, 2, 3, or 4 give progressively more diagnostics on STDERR. <DT><A NAME=``item_desc_%3D%3E_%24string''>desc => $string</A> <DD> An identifying name. If this is not passed explicitly to the constructor, it will be initialized with a string that attempts to identify the location in the source code where the watcher was constructed. <DT><A NAME=``item_fd_%3D%3E_%24filehandle''>fd => $filehandle</A> <DD> This attribute can accept either a perl-esque filehandle or a system call derived file descriptor number. <DT><A NAME=``item_hard_%3D%3E_%24bool''>hard => $bool</A> <DD> Determines how repeating timers (or timeouts) are recalculated. The timer is restarted either before or after the callback depending on whether it is true or false, respectively. In long-running callbacks this can make a significant difference. <DT><A NAME=``item_interval_%3D%3E_%24seconds''>interval => $seconds</A> <DD> How long between repeating timeouts. The <CODE>at</CODE> attribute is recalculated using <CODE>interval</CODE> upon callback return. <DT><A NAME=``item_max_%3D%3E_%24seconds''>max => $seconds</A> <DD> The maximum number of seconds to wait before triggering the callback. Similar to a <CODE>timeout</CODE>. <DT><A NAME=``item_max_cb_tm_%3D%3E_%24seconds''>max_cb_tm => $seconds</A> <DD> The maximum number of seconds to spend in a callback. If a callback uses more time then it is aborted. Defaults to 1 sec. This feature is normally disabled. See Event::Stats. <DT><A NAME=``item_min_%3D%3E_%24seconds''>min => $seconds</A> <DD> Enforce a minimum number of seconds between triggering events. <DT><A NAME=``item_poll_%3D%3E_%24bits''>poll => $bits</A> <DD> Determines which kinds of events are of interest. This attribute can be set with either strings or bit constants. The bit constants are available via 'use Event::Watcher qw(R W E T);'. <PRE> string constant description ------ -------- --------------- 'r' R read 'w' W write 'e' E exception 't' T timeout</PRE> Thus, both of these statements enable interest in read: <PRE> $w->poll($w->poll . 'r'); $w->poll($w->poll | R);</PRE> A given type of watcher may support all or a subset of the available events. <DT><A NAME=``item_prio_%3D%3E_%24level''>prio => $level</A> <DD> Changes the watcher's priority to the given level. Events generated by a watcher usually inherit the priority of the watcher. <DT><A NAME=``item_private_%3D%3E_%24anything''>private => $anything</A> <DD> Use the <CODE>private()</CODE> method to associate arbitrary data with a watcher. This method is intended for implementers of watchers or watcher subclasses. Each caller's package accesses its own private attribute. <DT><A NAME=``item_reentrant_%3D%3E_%24bool''>reentrant => $bool</A> <DD> By default, callbacks are allowed to invoke <A HREF=``#item_sweep''><CODE>sweep</CODE></A> or <A HREF=``#item_loop''><CODE>loop</CODE></A> which in turn may invoke the same callback again recursively. This can be useful but can also be confusing. Moreover, if you keep reentering callbacks you will quickly run out of stack space. Disable this feature per watcher by setting reentrant to false. This will cause the watcher to be suspended during recursive calls to <A HREF=``#item_sweep''><CODE>sweep</CODE></A> or <A HREF=``#item_loop''><CODE>loop</CODE></A>. <DT><A NAME=``item_repeat_%3D%3E_%24bool''>repeat => $bool</A> <DD> The repeat flag controls whether the callback should either be one-shot or continue waiting for new events. The default setting depends on the type of watcher. io, signal, and var default to true. <DT><A NAME=``item_signal_%3D%3E_%24str''>signal => $str</A> <DD> The callback is invoked after the specified signal is received. The $str string should be something like 'INT' or 'QUIT'. Also see the documentation for <CODE>%SIG</CODE>. A given signal can be handled by <CODE>%SIG</CODE> or Event, but not both at the same time. Event handles the signal as long as there is at least one active watcher. If all watchers for the signal are cancelled or stopped then Event sets the signal handler to SIG_DFL. <DT><A NAME=``item_suspend_%3D%3E_%24bool''>suspend => $bool</A> <DD> Stop looking for events. Running events are allowed to complete, but queued events are cancelled. Suspend is for debugging. If you suspend all watchers in an application then you can examine the complete state unchanged for as long as you like without worrying about timer expirations. If you actually wish to stop a watcher then use the <A HREF=``#item_stop''><CODE>stop()</CODE></A> method. <DT><A NAME=``item_timeout_%3D%3E_%24seconds''>timeout => $seconds</A> <DD> The number of seconds before a watcher times out. <DT><A NAME=``item_timeout_cb_%3D%3E_%5C%26code''>timeout_cb => \&code</A> <DD> <DT><A NAME=``item_timeout_cb_%3D%3E_%5B%24class_or_object%2C_%24meth''>timeout_cb => [$class_or_object, $method_name]</A> <DD> This is an optional attribute for use when it is desired that timeouts be serviced in a separate code path than normal events. When this attribute is unset, timeouts are serviced by <CODE>cb</CODE>. <DT><A NAME=``item_var_%3D%3E_%24ref''>var => $ref</A> <DD> A reference to the variable being watched. </DL> <H2><A NAME=``event attributes''>EVENT ATTRIBUTE/A</H2> <DL> <DT><A NAME=``item_got_%3D%3E_%24bits''>got => $bits</A> <DD> <CODE>got</CODE> is available in the callback of watchers with <CODE>poll</CODE>. <CODE>got</CODE> is in the same format as <CODE>poll</CODE> except that it gives what kind of event actually happened. In contrast, <CODE>poll</CODE> is just an indication of interest. <DT><A NAME=``item_hits_%3D%3E_%24int''>hits => $int</A> <DD> Signals in quick succession can be clumped into a single event. The number of signals clumped together is indicated by this attribute. This is always one for event types which don't clump. <DT>prio => $level <DD> Be aware that this priority can differ from the watcher's priority. For instance, the watcher's priority may have changed since the event was generated. Moreover, the C extension API offers the freedom to queue events of arbitrary priority. <DT><A NAME=``item_w_%3D%3E_%24watcher''>w => $watcher</A> <DD> This method return the event's watcher. It is read-only. </DL> <H2><A NAME=``customization and exceptions''>Customization and Exceptions</A></H2> <UL> <LI><A NAME=``item_%24Event%3A%3ADebugLevel''>$Event::DebugLevel</A>

Enables progressively more debugging output. Meaningful levels range from 1 (least output) to 5 (most output). Also see <CODE>debug</CODE>. <LI><A NAME=``item_%24Event%3A%3ADIED''>$Event::DIED</A>

When <A HREF=``#item_loop''><CODE>loop</CODE></A> or <A HREF=``#item_sweep''><CODE>sweep</CODE></A> is called, an exception context is established for the duration of event processing. If an exception is detected then <A HREF=``#item_%24Event%3A%3ADIED''><CODE>$Event::DIED</CODE></A> is invoked. The default hook uses <CODE>warn</CODE> to output the exception. After the DIED handler completes, event processing continues as if nothing happened. If you'd like more detailed output you can install the verbose handler: <PRE> $Event::DIED = \&Event::verbose_exception_handler;</PRE> Or you can write your own. The handler is invoked like this: <PRE> $Event::DIED->($event, $@);</PRE> If you do not want to continue looping after an error, you can do something like this: <PRE> $Event::DIED = sub { Event::verbose_exception_handler(@_); Event::unloop_all(); };</PRE> <LI><A NAME=``item_add_hooks''>Event->add_hooks(key => sub { ... }, ...);</A>

The bulk of Event's implementation is in C for maximum performance. The <A HREF=``#item_add_hooks''><CODE>add_hooks</CODE></A> method allows insertion of perl code at key points in the optimized event processing core. While flexible, this can hurt performance *significantly*. If you want customization *and* performance, please see the C API. Currently support hooks are detailed as follows: <PRE> hook purpose ------------- ---------------------------------------------- prepare returns minimum time to block (timeable) check assess state after normal return from select/poll asynccheck check for signals, etc callback invoked before each event callback</PRE> </UL> <HR> <H1><A NAME=``c api''>C AP/A</H1> Event also has a direct API for callbacks written exclusively in C. See Event::MakeMaker. <HR> <H1><A NAME=``what about threads''>WHAT ABOUT THREADS?</A></H1> Event loops and threads are two different solutions to the same problem: asynchronous processing. Event loops have been around since the beginning of computing. They are well understood and proven to be a good solution for many applications. While event loops make use of basic operating system services, the bulk of their implementation is usually outside the kernel. While an event loop may appear to do many things in parallel, it does not, even on multiprocessor hardware. Actions are always dispatched sequentially. This implies that long running callbacks must be avoided because otherwise event processing is halted. Event loops work well when actions are short and to the point. Long-running tasks must be broken into short steps and scheduled for execution. Some sort of a state machine is usually required. While a big, complex application server is usually simpler to implement in a multithreaded fashion, a web browser can easily get by without threads. Consider a JPEG file download and render. When some new bytes are available they are sorted to the right place on the screen. Only a little state must be kept to keep track of how much has been rendered and to process subsequent incoming bytes. Threads can either substitute for an event loop or complement it. Threads are similar to processes in that the operating system manages task switching for you. However, the difference is that all threads share the same address space. This is good and bad. Higher performance can be achieved but since data is shared between threads, extreme care must be taken to access or modify global data. The operating system can switch threads at any moment or can execute multiple threads simultaneously. I hope this sounds dangerous! It is! Threads can introduce maddeningly complicated and hard to debug synchronization problems. Threads are like rocket fuel. They are essential when you really need them but most applications would be better off with a simple event loop. Even if threads are genuinely needed, consider confining them to the parts of an application where truly scalable performance is really worth the difficulty of a multithreaded implementation. For example, most GUIs applications do not need threads and most scientific compute intensive problems can be isolated from event dispatching. On the other hand, high performance transaction servers generally do mandate a truly multithreaded approach. Another consideration is that threads are not quite as widely available as event loops. While a few forward-thinking operating systems have offered threads since the beginning, their addition to many popular operating systems is much more recent and some still offer no threads support. If portability is a requirement, one must check that threads support is available and also carefully test a particular threads implementation to see whether it supports the features you need. It is likely that all platforms will have a solid implementation soon but at this point in history it is best to double check. Many suggestions by Mark Mielke <<A HREF=``mailto:Mark.Mielke.markm@nt.com''>Mark.Mielke.markm@nt.com> <HR> <H1><A NAME=``what about nonpreemptive threads''>WHAT ABOUT NON-PREEMPTIVE THREADS?</A></H1> The Java language is oriented to use non-preemptive threads, yet even Java uses an event-loop for Swing (AFAIK). That is one of the reasons I don't use Java for network-centric applications. My belief is that the benefit of multi-threading is the gain in performance on SMP hardware. In my view, non-preemptive threads (java green-threads) are usually poor design. I find them harder to work with, harder to debug, and slower for a rather marginal gain in readability. I really like working with a state machine. I find it leads to more stable and better code. It also has the benefit of abstracting away how concurrency is achieved. Contributed by <A HREF=``mailto:artur@vogon-solutions.com,''>artur@vogon-solutions.com, 12 Jul 1999. <HR> <H1><A NAME=``bugs''>BUG/A</H1> No support for epoll, or better, libevent. The scope of events is pretty strange compared to most other perl objects. I'm not sure if this is a bug or a feature (OK, probably it was a mistake). We'll probably want to re-work things for Perl6. The meaning of $io-><CODE>timeout(0)</CODE> might change. Use <CODE>undef</CODE> to unset the timeout. There seems to be some sort of bug in the global destruction phase: <PRE> Attempt to free unreferenced scalar during global destruction. Use of uninitialized value during global destruction. Explicit blessing to '' (assuming package main) during global destruction.</PRE> <HR> <H1><A NAME=``the future''>THE FUTUR&THE FUTUR;/A></H1> Even if this module does not end up being the One and True Event Loop, the author will insure that it is source compatible with its successor, or arrange for gradual migration. Back in the early days, the Event programming API was changing at every release. Care was taken to allow the old API to continue to work, and the transition was eased by printing out lots of warnings about the new usage. So you shouldn't sit on your hands in anticipation of the One and True Event Loop. Just start coding! <HR> <H1><A NAME=``also see''>ALSO SE&ALSO SE;/A></H1> <UL> <LI><A NAME=``item_Useful_and_Fun''>Useful and Fun</A>

Time::HiRes, NetServer::Portal, Time::Warp <LI><A NAME=``item_Message_Passing''>Message Passing</A>

COPE, IPC::LDT, Event-tcp <LI><A NAME=``item_GUI''>GU/A

While Tk does not yet support Event, PerlQt does. <LI><A NAME=``item_C_API''>C AP/A

Inline </UL> <HR> <H1><A NAME=``support''>SUPPORT</A></H1> If you have insights or complaints then please subscribe to the mailing list! Send email to: <PRE> perl-loop-subscribe@perl.org <HR> <H1><A NAME=``author''>AUTHOR</A></H1> Joshua N. Pritikin <<A HREF=``mailto:jpritikin@pobox.com''>jpritikin@pobox.com> <HR> <H1><A NAME=``acknowledgment''>ACKNOWLEDGMENT</A></H1> Initial 0.01 implementation by Graham Barr <<A HREF=``mailto:gbarr@pobox.com''>gbarr@pobox.com>. Other contributors include at least those lists below and folks mentioned in the ChangeLog. <PRE> Gisle Aas <gisle@aas.no> Uri Guttman <uri@sysarch.com> Nick Ing-Simmons <nick@ni-s.u-net.com> (Tk) Sarathy <gsar@engin.umich.edu> Jochen Stenzel <perl@jochen-stenzel.de> <HR> <H1><A NAME=``copyright''>COPYRIGHT</A></H1> Copyright � 1997 Joshua Nathaniel Pritikin & Graham Barr Copyright � 1998, 1999, 2000, 2001, 2002, 2003, 2004 Joshua Nathaniel Pritikin All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR=``#cccccc''>  Event - Event loop processing </TD></TR> </TABLE>

</BODY>

</HTML>

/export/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/Event/blib/html/site/lib/Event.html