1Event::Lib(3) User Contributed Perl Documentation Event::Lib(3)
2
6 Event::Lib - Perl extentions for event-based programming
7
9 use Event::Lib;
10 use POSIX qw/SIGINT/;
11 my $seconds;
13 sub timer {
14 my $event = shift;
15 print "\r", ++$seconds;
16 $event->add(1);
17 }
18 sub reader {
20 my $event = shift;
21 my $fh = $event->fh;
22 print <$fh>;
23 $event->add;
24 }
25 sub signal {
27 my $event = shift;
28 print "Caught SIGINT\n";
29 }
30 my $timer = timer_new(\&timer);
32 my $reader = event_new(\*STDIN, EV_READ, \&reader);
33 my $signal = signal_new(SIGINT, \&signal);
34 $timer->add(1); # triggered every second
36 $reader->add;
37 $signal->add;
38 event_mainloop;
40
42 This module is a Perl wrapper around libevent(3) as available from
43 <http://www.monkey.org/~provos/libevent/>. It allows to execute a
44 function whenever a given event on a filehandle happens, a timeout
45 occurs or a signal is received.
46 Under the hood, one of the available mechanisms for asynchronously
48 dealing with events is used. This could be "select", "poll", "epoll",
49 "devpoll" or "kqueue". The idea is that you don't have to worry about
50 those details and the various interfaces they offer. Event::Lib offers
51 a unified interface to all of them (but see "CONFIGURATION" further
52 below).
53 Once you've skimmed through the next two sections (or maybe even now),
55 you should have a look at "EXAMPLE: A SIMPLE TCP SERVER" to get a
56 feeling about how it all fits together.
57 There's also a section briefly mentioning other event modules on the
59 CPAN and how they differ from Event::Lib further below ("OTHER EVENT
60 MODULES").
61
63 This happens via loading the module via use() or require():
64 use Event::Lib;
66 No further work is ever required.
68 Additionally, you may use the following two functions to retrieve some
70 information regarding the underlying libevent. These functions are
71 neither exported nor exportable so you have to call them fully package-
72 qualified:
73 * Event::Lib::get_version()
75 This returns the version of libevent this module was compiled against.
76 * Event::Lib::get_method()
78 This returns the kernel notification method used by libevent. This will
79 be one of "select", "poll", "epoll", "devpoll" and "kqueue".
80
82 The standard procedure is to create a few events and afterwards enter
83 the loop (using event_mainloop()) to wait for and handle the pending
84 events. This loop is truely global and shared even between forked
85 processes. The same is true for events that you register. They will all
86 be processed by the same loop, no matter where or how you create them.
87 Each event has a Perl function associated with itself that gets
89 triggered when the event is due. Further event handling is delayed
90 until the currently executing event handler is done. If you want an
91 event to be handled as soon as it becomes imminent, it has to run in
92 its own process so that it cannot be disturbed by other event handlers.
93 This is particularly important for timer-based events when you expect
94 those events to fire steadily every few seconds.
95 There's one more little thing to be aware of: Sometimes it may apear
97 that your events aren't triggered because they produce no output in
98 spite of your precious print() statements you put in. If you see no
99 output, then you're a victim of buffering. The solution is to turn on
100 autoflushing, so put
101 $| = 1;
103 at the top of your program if no output appears on your screen or
105 filehandles.
106 Event::Lib knows three different kind of events: a filehandle becomes
108 readable/writeable, timeouts and signals.
109
111 Most often you will have a set of filehandles that you want to watch
112 and handle simultaneously. Think of a webserver handling multiple
113 client requests. Such an event is created with event_new():
114 * event_new($fh, $flags, $function, [@args])
116 $fh is the filehandle you want to watch. $flags may be the bit-wise
117 ORing of "EV_READ", "EV_WRITE" and "EV_PERSIST". "EV_PERSIST" will make
118 the event persistent, that is: Once the event is triggered, it is not
119 removed from the event-loop. If you do not pass this flag, you have to
120 re-schedule the event in the event-handler $function.
121 $function is the callback that is executed when the given event
123 happened. This function is always called with at least two arguments,
124 namely the event object itself which was created by the above
125 event_new() and an integer being the event-type that occured (which
126 could be "EV_WRITE", "EV_READ" or "EV_TIMEOUT"). @args is an optional
127 list of additional arguments your callback will receive.
128 NOTE: $fh really ought to be a socket or a pipe. Regular files can't be
130 handled by at least epoll(2). If, for some reason, you want to put an
131 event on a regular file, you have to make sure that a kernel
132 notification method is used that can deal with such file-handles.
133 select(2) and poll(2) are good candidates as they don't have this
134 limitation. So in order to prevent this limitation, you have to do:
135 BEGIN {
137 $ENV{ $_ } = 1 for qw/EVENT_NOEPOLL EVENT_NODEVPOLL EVENT_NOKQUEUE/;
138 }
139 use Event::Lib;
140 See "CONFIGURATION" further below for more details.
142 The function returns an event object (the very object that is later
144 passed to the callback function).
145 Here's an example how to create a listening socket that can accept
147 connections from multiple clients:
148 use IO::Socket::INET;
150 use Event::Lib;
151 sub accept_connection {
153 my $event = shift;
154 my $sock = $event->fh;
155 my $client = $sock->accept;
156 ...
157 }
158 my $server = IO::Socket::INET->new(
160 LocalAddr => 'localhost',
161 LocalPort => 9000,
162 Proto => 'tcp',
163 ReuseAddr => SO_REUSEADDR,
164 Listen => 1,
165 Blocking => 0,
166 ) or die $@;
167 my $main = event_new($server, EV_READ|EV_PERSIST, \&accept_connection);
169 # add the event to the event loop
171 $main->add;
172 event_mainloop();
174 The above can be done without the "EV_PERSIST" flag as well:
176 sub accept_connection {
178 my $event = shift;
179 my $sock = $event->fh;
180 my $client = $sock->accept;
181 ...
182 # re-schedule event
183 $event->add;
184 }
185 ...
186 my $main = event_new($server, EV_READ, \&accept_connection);
187 $main->add;
188 event_mainloop();
189 * $event->add( [$timeout] )
191 Alias: event_add( $event, [$timeout] )
192 This adds the event previously created with event_new() to the event-
194 loop. $timeout is an optional argument specifying a timeout given as
195 floating-point number. It means that the event handler is triggered
196 either when the event happens or when $timeout seconds have passed,
197 whichever comes first.
198 Consider this snippet:
200 use Event::Lib;
202 sub handler {
204 my ($ev, $type) = @_;
205 if ($type == EV_READ) {
206 ...
207 }
208 elsif ($type == EV_TIMEOUT) {
209 ...
210 }
211 }
212 # wait at most for 1.5 seconds
214 event_new(\*STDIN, EV_READ, \&handler)->add(1.5);
215 event_one_loop;
216 If "STDIN" becomes readable within 1.5 seconds, handler() will be
218 called with $type set to "EV_READ". If nothing happens within these 1.5
219 seconds, it'll be called with $type set to "EV_TIMEOUT".
220 When $timeout is 0 it behaves as if no timeout has been given, that is:
222 An infinite timeout is assumed. Any other timeout is taken literally,
223 so 0.0 is not the same! In such a case, the event handler will be
224 called immediately with the event type set to "EV_TIMEOUT".
225 It's a fatal error to add the same event multiple times:
227 my $e = event_new(...);
229 $e->add;
230 $e->add; # this line will die
231 When an event couldn't be added for some other reason, the event's
233 exception handler is called. See "EXCEPTION HANDLING" further below on
234 how exceptions raised by event_add() differ from other exceptions.
235 * $event->fh
237 Returns the filehandle this $event is supposed to watch. You will
238 usually call this in the event-handler.
239 * $event->remove
241 This removes an event object from the event-loop. Note that the object
242 itself is not destroyed and freed. It is merely disabled and you can
243 later re-enable it by calling "$event->add".
244
246 Sometimes you want events to happen periodically, regardless of any
247 filehandles. Such events are created with timer_new():
248 * timer_new( $function, [@args] )
250 This is very much the same as event_new(), only that it lacks its first
251 two parameters. $function is a reference to a Perl function that
252 should be executed. As always, this function will receive the event
253 object as returned by timer_new() as first argument, the type of event
254 (always EV_TIMEOUT) plus the optional argumentlist @args.
255 * $event->add( [$timeout] )
257 Alias: event_add( $event, [$timeout] )
258 Adds $event to the event-loop. The event is scheduled to be triggered
260 every $timeout seconds where $timeout can be any floating-point value.
261 If $timeout is omitted, a value of one second is assumed.
262 It will throw an exception if adding the given event failed. If you
264 still want your program to keep running, wrap this statement into an
265 eval block:
266 my $e = event_new(...);
268 eval {
269 $e->add;
270 } or warn "Adding failed";
271 Note that timer-based events are not persistent so you have to call
273 this method/function again in the event-handler in order to re-schedule
274 it.
275 It's a fatal error to add the same event multiple times:
277 my $e = timer_new(...);
279 $e->add;
280 $e->add; # this line will die
281 When an event couldn't be added for some other reason, the event's
283 exception handler is called. See "EXCEPTION HANDLING" further below on
284 how exceptions raised by event_add() differ from other exceptions.
285 * $event->remove
287 This removes the timer-event $event from the event-loop. Again, $event
288 remains intact and may later be re-scheduled with event_add().
289
291 Your program can also respond to signals sent to it by other
292 applications. To handle signals, you create the corresponding event
293 using signal_new().
294 Note that thusly created events take precedence over event-handlers
296 defined in %SIG. That means the function you assigned to $SIG{ $SIGNAME
297 } will never be executed if a "Event::Lib"-handler for $SIGNAME also
298 exists.
299 * signal_new( $signal, $function, [@args] )
301 Sets up $function as a handler for $signal. $signal has to be an
302 integer specifying which signal to intercept and handle. For example,
303 15 is "SIGTERM" (on most platforms, anyway). You are advised to use the
304 symbolic names as exported by the POSIX module:
305 use Event::Lib;
307 use POSIX qw/SIGINT/;
308 my $signal = signal_new(SIGINT, sub { print "Someone hit ctrl-c" });
310 $signal->add;
311 event_mainloop();
312 As always, $function receives the event object as first argument, the
314 event-type (always EV_SIGNAL) as second. @args specifies an option list
315 of values that is to be passed to the handler.
316 * $event->add( [$timeout] )
318 Alias: event_add( $event, [$timeout] )
319 Adds the signal-event previously created with signal_new() to the
321 event-loop. $timeout is an optional argument specifying a timeout
322 given as floating-point number. It means that the event handler is
323 triggered either when the event happens or when $timeout seconds have
324 passed, whichever comes first.
325 $timeout here has the exact same semantics as with filehandle-based
327 events described further above.
328 Note that signal-events are always persistent unless $timeout was
330 given. That means that you have to delete the event manually if you
331 want it to happen only once:
332 sub sigint {
334 my $event = shift;
335 print "Someone hit ctrl-c";
336 $event->remove;
337 }
338 my $signal = signal_new(SIGINT, \&sigint);
340 $signal->add;
341 event_mainloop();
342 Subsequently, a persistent and timeouted signal-handler would read
344 thusly:
345 sub sigint {
347 my $event = shift;
348 print "Someone hit ctrl-c";
349 $event->add(2.5);
350 }
351 my $signal = signal_new(SIGINT, \&sigint);
353 $signal->add(2.5);
354 event_mainloop();
355 It's a fatal error to add the same event multiple times:
357 my $e = signal_new(...);
359 $e->add;
360 $e->add; # this line will die
361 When an event couldn't be added for some other reason, the event's
363 exception handler is called. See "EXCEPTION HANDLING" further below on
364 how exceptions raised by event_add() differ from other exceptions.
365 * $event->remove
367 The same as their counterparts for filehandle-events, so please see
368 above.
369
371 * $event->pending
372 This will tell you whether $event is still in the event-queue waiting
373 to be processed. More specifically, it returns a false value if $event
374 was already handled (and was not either persistent or re-scheduled). In
375 case $event is still in the queue it returns the amount of seconds as a
376 floating-point number until it is triggered again. If $event has no
377 attached timeout, it returns "0 but true".
378 * $event->args( [@args] )
380 When called with no arguments, it will in scalar context return the
381 number of additional arguments associated with $event. In list context,
382 it returns those arguments as one list.
383 When @args is given, the current list of arguments for $event is
385 replaced with @args and nothing is returned.
386 * $event->args_del
388 This will remove all additional arguments from $event so the next time
389 the event handler is called, the list of additional arguments passed to
390 it will be empty.
391 * $event->callback
393 Returns the callback associated with this event as code-reference so
394 that you can call it manually in case you think you need that:
395 $event->callback->($event, $event->fh, @args);
397 * $event->except_handler( $function )
399 You can associate an exception handler with each event which gets
400 called in case the callback for that event dies. $function is a Perl
401 code-reference which will - when called - receive the event as first
402 argument, the error message with which the event handler died, the type
403 of event and any additional arguments associated with that event. That
404 way you can inspect the circumstances and provide your own error-
405 handling.
406 Please see "EXCEPTION HANDLING" for some background and more details.
408
410 Event::Lib offers three functions to process pending events.
411 * event_mainloop ()
413 This function will start the event-loop and never return, generally.
414 More precisely, it will return if either the program ran out of events
415 in which case event_mainloop() returns a true value. In case of an
416 error during event-processing, it will return a false value in which
417 case you should check $!.
418 IMPORTANT: When any of your events register new events they will be
420 added to the global queue of events and be handled in the same loop.
421 You are therefore not allowed to call event_mainloop() more than once
422 in your program. Attempting to do so will yield a warning and the
423 operation is silently turned into a no-op.
424 * event_one_loop( [$timeout] )
426 This function will do exactly one loop which means the next pending
427 event is handled. In case no event is currently ready for processing,
428 it will block and wait until one becomes processible.
429 If $timeout is specified, it will wait at most $timeout seconds and
431 then return.
432 * event_one_nbloop ()
434 This is the non-blocking counterpart to event_one_loop(): It returns
435 immediately when no event is ready to be processed. Otherwise the next
436 imminent event is handled.
437 You want to use either event_one_loop() or event_one_nbloop() instead
439 of event_mainloop() if you want to write your own event-loop. The core
440 of such a program could look like this:
441 event_new(...)->add;
443 event_new(...)->add;
444 timer_new(...)->add;
445 ...
446 while () {
448 event_one_nbloop();
449 ...
450 select undef, undef, undef, 0.05; # sleep for 0.05 seconds
451 }
452
454 It is important to understand the lifetime of events because concepts
455 such as scope and visibility have little meaning with respect to
456 events.
457 When you add an event to the queue using event_add(), this event will
459 remain there until it is triggered, no matter what you do with the
460 object returned by event_new(), timer_new() and signal_new()
461 respectively. Consider this code:
462 use Event::Lib;
464 $| = 1;
465 my $event = timer_new(sub { print "timer called\n" });
467 # schedule the timer to go off in ten seconds
469 $event->add(10);
470 undef $event;
472 event_mainloop;
473 This program will, regardless of the "undef $event", print "timer
475 called". As a consequence, there is only one true and correct way to
476 cancel an event, namely by calling remove() on it. Likewise:
477 use warnings;
479 use Event::Lib;
480 $| = 1;
481 my $event = timer_new(sub { print "Called after two seconds\n" });
483 $event->add(2);
484 $event = timer_new(sub { print "Called after three seconds\n" });
485 $event->add(3);
486 event_mainloop;
488 __END__
490 Explicit undef() of or reassignment to pending event at - line 8.
491 Called after two seconds
492 Called after three seconds
493 So even though you have only one Perl object container $event, you have
495 two events!
496 As this can become hard to maintain in complex programs, Event::Lib
498 will emmit a warning if any of the above cases is detected and if you
499 have warnings enabled. If you don't want this warning turn it off
500 temporarily. The above program then becomes:
501 use warnings;
503 use Event::Lib;
504 $| = 1;
505 my $event = timer_new(sub { print "Called after two seconds\n" });
507 $event->add(2);
508 {
510 no warnings 'misc';
511 $event = timer_new(sub { print "Called after three seconds\n" });
512 $event->add(3);
513 }
514 event_mainloop;
516 Note that the line following the undef() or the reassignment has to be
518 within the "no warnings 'misc'"-block because this is the line where
519 this warning is actually triggered and not the line with the undef() or
520 reassignment itself.
521
523 Some programs simply cannot afford to die. It is a possible that a
524 callback is triggered and finds itself in a situation where it just
525 cannot proceed. Think of a callback that is supposed to append to a
526 file and in the meantime the disk has filled so that no space is left
527 on the device.
528 It is now possible to provide exception handlers for these cases. The
530 idea is that these exception handlers are called with the same
531 arguments the callback was previously triggered with (plus the error
532 message as second argument) which gives you the change to further
533 investigate the cause of the failure and possibly take counter-
534 measures.
535 You can register exception handlers per event using the
537 except_handler() method. Furthermore, you can register one global
538 exception handler that is going to be used for all events that don't
539 have their own handler:
540 * event_register_except_handler( $function )
542 $function is a code-reference that will be called whenever the callback
543 of an event dies:
544 use Event::Lib;
546 sub handler {
548 my ($event, $exception, $type, @args) = @_;
549 # error handling here
550 ...
551 }
552 event_register_except_handler(\&handler);
554 ...
555 If you don't call event_register_except_handler() Event::Lib will use
557 its own basic default handler. This handler simply dies with the
558 original error message.
559 Exceptions raised by event_add()
561 If the exception was raised by event_add(), then the event's exception
562 handler is called. This is either the one registered with
563 except_handler() on a per-event basis, the global one set via
564 event_register_except_handler() or, if both of these was not done, the
565 default handler.
566 In any case, the exception handler called from event_add() is called
568 with slightly different arguments. This is in order to allow the
569 handler to distinguish between the case where an exception was raised
570 by an event-handler or where it was raised by event_add().
571 The first two arguments being the event in question and the error
573 message are the same for both kind of exceptions. What differs is the
574 third argument, $type. It will always be negative when event_add()
575 triggered this exception.
576 In particular, the type of event $type will be for a...
578 ... filehandle-event:
580 The negated type-flags with which the event was created. This means
581 that for the following exception-handler and when "$e->add" failed:
582 sub exception_handler {
584 my ($e, $err, $evtype, @args) = @_;
585 # ref($e) eq "Event::Lib::event"
587 # $err =~ /^Couldn't add event at/
588 # $evtype == -(EV_READ|EV_PERSIST)
589 # @args == (1, 2, 3)
590 # $! will contain the OS-level error
591 }
592 my $e = event_new(\*FH, EV_READ|EV_PERSIST, \&handler, 1 .. 3);
594 ...
595 $e->add;
596 ... timer-event:
598 $type will be -EV_TIMEOUT:
599 sub exception_handler {
601 my ($e, $err, $evtype, @args) = @_;
602 # ref($e) eq "Event::Lib::timer"
604 # $err =~ /^Couldn't add event at/
605 # $evtype == -EV_TIMEOUT
606 # @args == (1, 2, 3)
607 }
608 my $e = timer_new(\&handler, 1 .. 3);
610 ...
611 $e->add;
612 ... signal-event:
614 $type will be the negated signal number this event was supposed to
615 handle:
616 sub exception_handler {
618 my ($e, $err, $evtype, @args);
619 # ref($e) eq "Event::Lib::signal"
621 # $err =~ /^Couldn't add event at/
622 # $evtype == -SIGTERM
623 # @args == (1, 2, 3)
624 }
625 my $e = signal_new(SIGTERM, \&handler, 1 .. 3);
627 ...
628 $e->add;
629 As a consequence, first have your exception-handler test the sign of
631 $evtype. If it was negative, use "ref($e)" to extract the kind of
632 event.
633
635 Events can be assigned a priority. The lower its assigned priority is,
636 the earlier this event is processed. Using prioritized events in your
637 programs requires two steps. The first one is to set the number of
638 available priorities. Setting those should happen once in your script
639 and before calling event_mainloop():
640 * event_priority_init( $priorities )
642 Sets the number of different events to $priorities.
643 Assigning a priority to each event then happens thusly:
645 * $event->set_priority( $priority )
647 Gives $event (which can be any of the three type of events) the
648 priority $priority. Remember that a lower priority means the event is
649 processed earlier!
650 Note: If your installed version of libevent does not yet contain
652 priorities which happens for pre-1.0 versions, the above will become
653 no-ops. Other than that, your scripts will remain functional.
654
656 There are some functions that will aid you in finding problems in your
657 program or even to assure you that your program is ok but there might
658 be a bug in Event::Lib.
659 * event_log_level( $loglevel )
661 You can specify what kind of messages Event::Lib should dump to stderr
662 by using thid function.
663 $loglevel is one of _EVENT_LOG_DEBUG, _EVENT_LOG_MSG, _EVENT_LOG_WARN,
665 _EVENT_LOG_ERR and _EVENT_LOG_NONE and will instruct Event::Lib to only
666 output messages of at least that severity. "_EVENT_LOG_NONE" will
667 suppress any messages. Not calling this function is equivalent to doing
668 event_log_level( _EVENT_LOG_ERR );
670 * $event->trace
672 This turns on tracing for $event. Tracing means that diagnostic
673 messages are written to STDERR whenever something happens to this
674 $event. This includes implicit action such as the destruction of an
675 event or explicit things like calling add() or remove() or other
676 methods on $event.
677 Returns $event so that you can easily plug it into your code:
679 event_new(...)->trace->add;
681 Once an event is traced, there is as of now no way to untrace it again.
683 * Event::Lib::Debug::get_pending_events()
685 This function is only available when you built Event::Lib with
686 "DEFINE=-DEVENT_LIB_DEBUG" (as an argument to perl Makefile.PL).
687 Additionally, you have to run your program with the environment
688 variable "EVENT_LIB_DEBUG_PENDING" set in order to get any output from
689 this function. The environment has to be set before "use Event::Lib;":
690 BEGIN {
692 $ENV{ EVENT_LIB_DEBUG_PENDING } = 1;
693 }
694 use Event::Lib;
696 or by setting it in your shell. For the bash, this looks like:
698 $ EVENT_LIB_DEBUG_PENDING=1 perl event_script.pl
700 This function will return a list of all currently still pending events.
702 Each element of this list is a reference to an array, where the first
703 element is the event object, the second the type of event
704 ("EV_TIMEOUT", "EV_SIGNAL", "EV_READ" etc.) and the remaining elements
705 the additional arguments this event was constructed with.
706 * Event::Lib::Debug::dump_pending_events()
708 Similar to the above, only that it will dump all currently pending
709 events to STDERR with some additional information that might be of
710 interest.
711 Again, this is only available when the module was build with
713 "-DEVENT_LIB_DEBUG" and with the environment variable
714 "EVENT_LIB_DEBUG_PENDING" set.
715
717 Event::Lib can be told which kernel notification method not to use.
718 This happens via the use of environment variables (there is no other
719 way due to libevent). They have to be set in a BEGIN-block before you
720 use() Event::Lib:
721 BEGIN {
723 $ENV{ $_ } = 1 for qw/EVENT_NOPOLL EVENT_NOEPOLL/;
724 }
725 use Event::Lib;
727 This will disable "poll" and "epoll" so it will use one of the
729 remaining methods, which could be either "select", "devpoll" or
730 "kqueue".
731 The variables that you may set are the following:
733 • EVENT_NOPOLL
735 • EVENT_NOSELECT
737 • EVENT_NOEPOLL
739 • EVENT_NODEVPOLL
741 • EVENT_NOKQUEUE
743 If you set all of the above variables, it is a fatal error and you'll
745 receive the message "event_init: no event mechanism available". There
746 is one other variable available:
747 • EVENT_LOG_LEVEL
749 This is the environment-variable version of set_log_level()
751 intended to conveniently run your script more verbosely for
752 debugging purpose. The lower this value is, the more informational
753 output libevent produces on STDERR. "EVENT_LOG_LEVEL=0" means
754 maximum debugging output whereas "EVENT_LOG_LEVEL=4" means no
755 output at all:
756 $ EVENT_LOG_LEVEL=0 perl your_script.pl
758
760 Here's a reasonably complete example how to use this library to create
761 a simple TCP server serving many clients at once. It makes use of all
762 three kinds of events:
763 use POSIX qw/SIGHUP/;
765 use IO::Socket::INET;
766 use Event::Lib;
767 $| = 1;
769 # Invoked when a new client connects to us
771 sub handle_incoming {
772 my $e = shift;
773 my $h = $e->fh;
774 my $client = $h->accept or die "Should not happen";
776 $client->blocking(0);
777 # set up a new event that watches the client socket
779 my $event = event_new($client, EV_READ|EV_PERSIST, \&handle_client);
780 $event->add;
781 }
782 # Invoked when the client's socket becomes readable
784 sub handle_client {
785 my $e = shift;
786 my $h = $e->fh;
787 printf "Handling %s:%s\n", $h->peerhost, $h->peerport;
788 while (<$h>) {
789 print "\t$_";
790 if (/^quit$/) {
791 # this client says goodbye
792 close $h;
793 $e->remove;
794 last;
795 }
796 }
797 }
798 # This just prints the number of
800 # seconds elapsed
801 my $secs;
802 sub show_time {
803 my $e = shift;
804 print "\r", $secs++;
805 $e->add;
806 }
807 # Do something when receiving SIGHUP
809 sub sighup {
810 my $e = shift;
811 # a common thing to do would be
812 # re-reading a config-file or so
813 ...
814 }
815 # Create a listening socket
817 my $server = IO::Socket::INET->new(
818 LocalAddr => 'localhost',
819 LocalPort => 9000,
820 Proto => 'tcp',
821 ReuseAddr => SO_REUSEADDR,
822 Listen => 1,
823 Blocking => 0,
824 ) or die $@;
825 my $main = event_new($server, EV_READ|EV_PERSIST, \&handle_incoming);
827 my $timer = timer_new(\&show_time);
828 my $hup = signal_new(SIGHUP, \&sighup);
829 $_->add for $main, $timer, $hup;
831 event_mainloop;
833 __END__
835 You can test the above server with this little program of which you can
837 start a few several simultaneous instances:
838 use IO::Socket::INET;
840 my $server = IO::Socket::INET->new(
842 Proto => 'tcp',
843 PeerAddr => 'localhost',
844 PeerPort => 9000,
845 ) or die $@;
846 print $server "HI!\n";
848 sleep 10;
849 print $server "quit\n";
850 __END__
852
854 There are already a handful of similar modules on the CPAN. The two
855 most prominent ones are Event and the venerable POE framework.
856 Event
858 In its functionality it's quite close to Event::Lib with some
859 additional features not present in this module (you can watch
860 variables, for example). Interface-wise, it's quite a bit heavier
861 while Event::Lib gets away with just a handful of functions and
862 methods. On the other hand, it has been around for years and so you may
863 expect Event to be rock-stable.
864 The one main advantage of Event::Lib appears to be in its innards. The
866 underlying libevent is capable of employing not just the "poll" and
867 "select" notification mechanisms but also other and possibly better
868 performing ones such as "kqueue", "devpoll" and "epoll" where
869 available.
870 POE
872 POE is definitely more than the above. It's really a threading
873 environment in disguise. Purely event-based techniques have
874 limitations, most notably that an event-handler blocks all other
875 pending events until it is done with its work. It's therefore not
876 possible to write a parallel link-checker only with Event or
877 Event::Lib. You still need threads or fork(2) for that.
878 That's where POE enters the scene. It is truely capable of running jobs
880 in parallel. Such jobs are usually encapsulated in "POE::Component"
881 objects of which already quite a few premade ones exist on the CPAN.
882 This power comes at a price. POE has a somewhat steep learning-curve
884 and forces you to think in POE concepts. For medium- and large-sized
885 applications, this doesn't have to be a bad thing. Once grokked, it's
886 easy to add more components to your project, so it's almost infinitely
887 extensible.
888 Stem
890 Stem is a very close rival to POE and they are nose-to-nose when it
891 comes to features. However, Stem's design is a lot easier to understand
892 and to adapt to your need, mostly because it doesn't come up with its
893 own methodology and terminology. It is very well thought out without
894 being over-designed.
895 It's easy and straight-forward to do simple event-looping (it currently
897 comes with its own well-conceived event loop; additionally it can make
898 use of Event when available). So called Stem cells can be easily
899 plugged together to build big applications where these cells can run in
900 parallel, both in an asynchronous or synchronized fashion.
901 It's main drawback (as of now) is its lack of documentation. However,
903 It's been written in a clean way so its source can often serve as a
904 drop-in replacement for the lack of documentation.
905 Conclusion
907 Use the right tools for your job. Event::Lib and Event are good for
908 writing servers that serve many clients at once, or in general:
909 Anything that requires you to watch resources and do some work when
910 something interesting happens with those resources. Once the work
911 needed to be carried out per event gets too complex, you may still use
912 "fork".
913 Or you use Stem or POE. You get the watching and notifying capabilities
915 alright, but also the power to do things in parallel without creating
916 threads or child processes manually.
917
919 This modules exports by default the following functions:
920 event_init
922 event_log_level
923 event_priority_init
924 event_register_except_handler
925 event_fork
926 event_new
928 timer_new
929 signal_new
930 event_add
932 event_mainloop
934 event_one_loop
935 event_one_nbloop
936 plus the following constants:
938 EV_PERSIST
940 EV_READ
941 EV_SIGNAL
942 EV_TIMEOUT
943 EV_WRITE
944 _EVENT_LOG_DEBUG
945 _EVENT_LOG_MSG
946 _EVENT_LOG_WARN
947 _EVENT_LOG_ERR
948 _EVENT_LOG_NONE
949
951 This library is not thread-safe.
952 The module has turned out to be quite stable under stress-situations
954 handling many thousands simultaneous connections with a very decent
955 performance which it owes to the underlying libevent. However, event-
956 based applications can reach a stupendous complexity and it is not
957 possible to foresee every kind of conceivable scenario.
958 If you therefore find a bug (a crash, a memory leak, inconsistencies or
960 omissions in this documentation, or just about anything else), don't
961 hesitate to contact me. See "AUTHOR" further below for details.
962
964 Thread-safety is high on the list. Recent libevent has thread-support
965 which will make this fairly easy.
966 Not all of libevent's public interface is implemented. The buffered
968 events are still missing. They will be added once I grok what they are
969 for.
970
972 This module wouldn't be in its current state without the patient and
973 professional help of MailChannels Corporation
974 (http://www.mailchannels.com). Over the course of five months, Stas
975 Bekman, Ken Simpson and Mike Smith exchanged hundreds of emails with
976 me, pointing out the many glitches that were in the module and coming
977 up with test-cases that made it possible for me to fix all these
978 issues.
979
981 libevent's home can be found at
982 <http://www.monkey.org/~provos/libevent/>. It contains further
983 references to event-based techniques.
984 Also the manpage of event(3).
986
988 This is version 1.03.
989
991 Tassilo von Parseval, <tassilo.von.parseval@rwth-aachen.de>
992
994 Copyright (C) 2004-2007 by Tassilo von Parseval
995 This library is free software; you can redistribute it and/or modify it
997 under the same terms as Perl itself, either Perl version 5.8.4 or, at
998 your option, any later version of Perl 5 you may have available.
999perl v5.34.0 2022-01-21 Event::Lib(3)