ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/README
(Generate patch)

Comparing AnyEvent/README (file contents):
Revision 1.45 by root, Fri Jul 17 14:57:03 2009 UTC vs.
Revision 1.46 by root, Sat Jul 18 05:19:09 2009 UTC

… …
350 invocation, and callback invocation will be synchronous. Synchronous 350 invocation, and callback invocation will be synchronous. Synchronous
351 means that it might take a while until the signal gets handled by the 351 means that it might take a while until the signal gets handled by the
352 process, but it is guaranteed not to interrupt any other callbacks. 352 process, but it is guaranteed not to interrupt any other callbacks.
353 353
354 The main advantage of using these watchers is that you can share a 354 The main advantage of using these watchers is that you can share a
355 signal between multiple watchers. 355 signal between multiple watchers, and AnyEvent will ensure that signals
356 will not interrupt your program at bad times.
356 357
357 This watcher might use %SIG, so programs overwriting those signals 358 This watcher might use %SIG (depending on the event loop used), so
358 directly will likely not work correctly. 359 programs overwriting those signals directly will likely not work
360 correctly.
361
362 Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not
363 support attaching callbacks to signals, which is a pity, as you cannot
364 do race-free signal handling in perl. AnyEvent will try to do it's best,
365 but in some cases, signals will be delayed. The maximum time a signal
366 might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default:
367 10 seconds). This variable can be changed only before the first signal
368 watcher is created, and should be left alone otherwise. Higher values
369 will cause fewer spurious wake-ups, which is better for power and CPU
370 saving. All these problems can be avoided by installing the optional
371 Async::Interrupt module.
359 372
360 Example: exit on SIGINT 373 Example: exit on SIGINT
361 374
362 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 375 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
363 376
… …
390 of when you start the watcher. 403 of when you start the watcher.
391 404
392 This means you cannot create a child watcher as the very first thing in 405 This means you cannot create a child watcher as the very first thing in
393 an AnyEvent program, you *have* to create at least one watcher before 406 an AnyEvent program, you *have* to create at least one watcher before
394 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 407 you "fork" the child (alternatively, you can call "AnyEvent::detect").
408
409 As most event loops do not support waiting for child events, they will
410 be emulated by AnyEvent in most cases, in which the latency and race
411 problems mentioned in the description of signal watchers apply.
395 412
396 Example: fork a process and wait for it 413 Example: fork a process and wait for it
397 414
398 my $done = AnyEvent->condvar; 415 my $done = AnyEvent->condvar;
399 416
… …
991 by "PERL_ANYEVENT_MODEL". 1008 by "PERL_ANYEVENT_MODEL".
992 1009
993 When set to 2 or higher, cause AnyEvent to report to STDERR which 1010 When set to 2 or higher, cause AnyEvent to report to STDERR which
994 event model it chooses. 1011 event model it chooses.
995 1012
1013 When set to 8 or higher, then AnyEvent will report extra information
1014 on which optional modules it loads and how it implements certain
1015 features.
1016
996 "PERL_ANYEVENT_STRICT" 1017 "PERL_ANYEVENT_STRICT"
997 AnyEvent does not do much argument checking by default, as thorough 1018 AnyEvent does not do much argument checking by default, as thorough
998 argument checking is very costly. Setting this variable to a true 1019 argument checking is very costly. Setting this variable to a true
999 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1020 value will cause AnyEvent to load "AnyEvent::Strict" and then to
1000 thoroughly check the arguments passed to most method calls. If it 1021 thoroughly check the arguments passed to most method calls. If it
1001 finds any problems, it will croak. 1022 finds any problems, it will croak.
1002 1023
1003 In other words, enables "strict" mode. 1024 In other words, enables "strict" mode.
1004 1025
1005 Unlike "use strict", it is definitely recommended to keep it off in 1026 Unlike "use strict" (or it's modern cousin, "use common::sense", it
1006 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment 1027 is definitely recommended to keep it off in production. Keeping
1028 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1007 while developing programs can be very useful, however. 1029 programs can be very useful, however.
1008 1030
1009 "PERL_ANYEVENT_MODEL" 1031 "PERL_ANYEVENT_MODEL"
1010 This can be used to specify the event model to be used by AnyEvent, 1032 This can be used to specify the event model to be used by AnyEvent,
1011 before auto detection and -probing kicks in. It must be a string 1033 before auto detection and -probing kicks in. It must be a string
1012 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 1034 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
1069 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH". 1091 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1070 When neither "ca_file" nor "ca_path" was specified during 1092 When neither "ca_file" nor "ca_path" was specified during
1071 AnyEvent::TLS context creation, and either of these environment 1093 AnyEvent::TLS context creation, and either of these environment
1072 variables exist, they will be used to specify CA certificate 1094 variables exist, they will be used to specify CA certificate
1073 locations instead of a system-dependent default. 1095 locations instead of a system-dependent default.
1096
1097 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1098 When these are set to 1, then the respective modules are not loaded.
1099 Mostly good for testing AnyEvent itself.
1074 1100
1075SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1101SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1076 This is an advanced topic that you do not normally need to use AnyEvent 1102 This is an advanced topic that you do not normally need to use AnyEvent
1077 in a module. This section is only of use to event loop authors who want 1103 in a module. This section is only of use to event loop authors who want
1078 to provide AnyEvent compatibility. 1104 to provide AnyEvent compatibility.
… …
1603 it is that this way, the handler will be restored to defaults on 1629 it is that this way, the handler will be restored to defaults on
1604 exec. 1630 exec.
1605 1631
1606 Feel free to install your own handler, or reset it to defaults. 1632 Feel free to install your own handler, or reset it to defaults.
1607 1633
1634RECOMMENDED/OPTIONAL MODULES
1635 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1636 it's built-in modules) are required to use it.
1637
1638 That does not mean that AnyEvent won't take advantage of some additional
1639 modules if they are installed.
1640
1641 This section epxlains which additional modules will be used, and how
1642 they affect AnyEvent's operetion.
1643
1644 Async::Interrupt
1645 This slightly arcane module is used to implement fast signal
1646 handling: To my knowledge, there is no way to do completely
1647 race-free and quick signal handling in pure perl. To ensure that
1648 signals still get delivered, AnyEvent will start an interval timer
1649 to wake up perl (and catch the signals) with soemd elay (default is
1650 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1651
1652 If this module is available, then it will be used to implement
1653 signal catching, which means that signals will not be delayed, and
1654 the event loop will not be interrupted regularly, which is more
1655 efficient (And good for battery life on laptops).
1656
1657 This affects not just the pure-perl event loop, but also other event
1658 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1659
1660 EV This module isn't really "optional", as it is simply one of the
1661 backend event loops that AnyEvent can use. However, it is simply the
1662 best event loop available in terms of features, speed and stability:
1663 It supports the AnyEvent API optimally, implements all the watcher
1664 types in XS, does automatic timer adjustments even when no monotonic
1665 clock is available, can take avdantage of advanced kernel interfaces
1666 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1667 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1668 Glib::EV).
1669
1670 Guard
1671 The guard module, when used, will be used to implement
1672 "AnyEvent::Util::guard". This speeds up guards considerably (and
1673 uses a lot less memory), but otherwise doesn't affect guard
1674 operation much. It is purely used for performance.
1675
1676 JSON and JSON::XS
1677 This module is required when you want to read or write JSON data via
1678 AnyEvent::Handle. It is also written in pure-perl, but can take
1679 advantage of the ulta-high-speed JSON::XS module when it is
1680 installed.
1681
1682 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1683 installed.
1684
1685 Net::SSLeay
1686 Implementing TLS/SSL in Perl is certainly interesting, but not very
1687 worthwhile: If this module is installed, then AnyEvent::Handle (with
1688 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1689
1690 Time::HiRes
1691 This module is part of perl since release 5.008. It will be used
1692 when the chosen event library does not come with a timing source on
1693 it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1694 additionally use it to try to use a monotonic clock for timing
1695 stability.
1696
1608FORK 1697FORK
1609 Most event libraries are not fork-safe. The ones who are usually are 1698 Most event libraries are not fork-safe. The ones who are usually are
1610 because they rely on inefficient but fork-safe "select" or "poll" calls. 1699 because they rely on inefficient but fork-safe "select" or "poll" calls.
1611 Only EV is fully fork-aware. 1700 Only EV is fully fork-aware.
1612 1701
1613 If you have to fork, you must either do so *before* creating your first 1702 If you have to fork, you must either do so *before* creating your first
1614 watcher OR you must not use AnyEvent at all in the child. 1703 watcher OR you must not use AnyEvent at all in the child OR you must do
1704 something completely out of the scope of AnyEvent.
1615 1705
1616SECURITY CONSIDERATIONS 1706SECURITY CONSIDERATIONS
1617 AnyEvent can be forced to load any event model via 1707 AnyEvent can be forced to load any event model via
1618 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1708 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1619 to execute arbitrary code or directly gain access, it can easily be used 1709 to execute arbitrary code or directly gain access, it can easily be used

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines