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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.179 by root, Thu Sep 4 10:58:58 2008 UTC vs.
Revision 1.180 by root, Sat Sep 6 07:00:45 2008 UTC

… …
850=cut 850=cut
851 851
852package AnyEvent; 852package AnyEvent;
853 853
854no warnings; 854no warnings;
855use strict; 855use strict qw(vars subs);
856 856
857use Carp; 857use Carp;
858 858
859our $VERSION = 4.233; 859our $VERSION = 4.233;
860our $MODEL; 860our $MODEL;
… …
1175 1175
1176# undocumented/compatibility with pre-3.4 1176# undocumented/compatibility with pre-3.4
1177*broadcast = \&send; 1177*broadcast = \&send;
1178*wait = \&_wait; 1178*wait = \&_wait;
1179 1179
1180=head1 ERROR AND EXCEPTION HANDLING
1181
1182In general, AnyEvent does not do any error handling - it relies on the
1183caller to do that if required. The L<AnyEvent::Strict> module (see also
1184the C<PERL_ANYEVENT_STRICT> environment variable, below) provides strict
1185checking of all AnyEvent methods, however, which is highly useful during
1186development.
1187
1188As for exception handling (i.e. runtime errors and exceptions thrown while
1189executing a callback), this is not only highly event-loop specific, but
1190also not in any way wrapped by this module, as this is the job of the main
1191program.
1192
1193The pure perl event loop simply re-throws the exception (usually
1194within C<< condvar->recv >>), the L<Event> and L<EV> modules call C<<
1195$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1196so on.
1197
1198=head1 ENVIRONMENT VARIABLES
1199
1200The following environment variables are used by this module or its
1201submodules:
1202
1203=over 4
1204
1205=item C<PERL_ANYEVENT_VERBOSE>
1206
1207By default, AnyEvent will be completely silent except in fatal
1208conditions. You can set this environment variable to make AnyEvent more
1209talkative.
1210
1211When set to C<1> or higher, causes AnyEvent to warn about unexpected
1212conditions, such as not being able to load the event model specified by
1213C<PERL_ANYEVENT_MODEL>.
1214
1215When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1216model it chooses.
1217
1218=item C<PERL_ANYEVENT_STRICT>
1219
1220AnyEvent does not do much argument checking by default, as thorough
1221argument checking is very costly. Setting this variable to a true value
1222will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1223check the arguments passed to most method calls. If it finds any problems
1224it will croak.
1225
1226In other words, enables "strict" mode.
1227
1228Unlike C<use strict>, it is definitely recommended ot keep it off in
1229production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while
1230developing programs can be very useful, however.
1231
1232=item C<PERL_ANYEVENT_MODEL>
1233
1234This can be used to specify the event model to be used by AnyEvent, before
1235auto detection and -probing kicks in. It must be a string consisting
1236entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1237and the resulting module name is loaded and if the load was successful,
1238used as event model. If it fails to load AnyEvent will proceed with
1239auto detection and -probing.
1240
1241This functionality might change in future versions.
1242
1243For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1244could start your program like this:
1245
1246 PERL_ANYEVENT_MODEL=Perl perl ...
1247
1248=item C<PERL_ANYEVENT_PROTOCOLS>
1249
1250Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1251for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1252of auto probing).
1253
1254Must be set to a comma-separated list of protocols or address families,
1255current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1256used, and preference will be given to protocols mentioned earlier in the
1257list.
1258
1259This variable can effectively be used for denial-of-service attacks
1260against local programs (e.g. when setuid), although the impact is likely
1261small, as the program has to handle connection errors already-
1262
1263Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1264but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1265- only support IPv4, never try to resolve or contact IPv6
1266addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1267IPv6, but prefer IPv6 over IPv4.
1268
1269=item C<PERL_ANYEVENT_EDNS0>
1270
1271Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1272for DNS. This extension is generally useful to reduce DNS traffic, but
1273some (broken) firewalls drop such DNS packets, which is why it is off by
1274default.
1275
1276Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1277EDNS0 in its DNS requests.
1278
1279=item C<PERL_ANYEVENT_MAX_FORKS>
1280
1281The maximum number of child processes that C<AnyEvent::Util::fork_call>
1282will create in parallel.
1283
1284=back
1285
1180=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1286=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1181 1287
1182This is an advanced topic that you do not normally need to use AnyEvent in 1288This is an advanced topic that you do not normally need to use AnyEvent in
1183a module. This section is only of use to event loop authors who want to 1289a module. This section is only of use to event loop authors who want to
1184provide AnyEvent compatibility. 1290provide AnyEvent compatibility.
… …
1217 1323
1218I<rxvt-unicode> also cheats a bit by not providing blocking access to 1324I<rxvt-unicode> also cheats a bit by not providing blocking access to
1219condition variables: code blocking while waiting for a condition will 1325condition variables: code blocking while waiting for a condition will
1220C<die>. This still works with most modules/usages, and blocking calls must 1326C<die>. This still works with most modules/usages, and blocking calls must
1221not be done in an interactive application, so it makes sense. 1327not be done in an interactive application, so it makes sense.
1222
1223=head1 ENVIRONMENT VARIABLES
1224
1225The following environment variables are used by this module:
1226
1227=over 4
1228
1229=item C<PERL_ANYEVENT_VERBOSE>
1230
1231By default, AnyEvent will be completely silent except in fatal
1232conditions. You can set this environment variable to make AnyEvent more
1233talkative.
1234
1235When set to C<1> or higher, causes AnyEvent to warn about unexpected
1236conditions, such as not being able to load the event model specified by
1237C<PERL_ANYEVENT_MODEL>.
1238
1239When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1240model it chooses.
1241
1242=item C<PERL_ANYEVENT_STRICT>
1243
1244AnyEvent does not do much argument checking by default, as thorough
1245argument checking is very costly. Setting this variable to a true value
1246will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1247check the arguments passed to most method calls. If it finds any problems
1248it will croak.
1249
1250In other words, enables "strict" mode.
1251
1252Unlike C<use strict> it is definitely recommended ot keep it off in
1253production.
1254
1255=item C<PERL_ANYEVENT_MODEL>
1256
1257This can be used to specify the event model to be used by AnyEvent, before
1258auto detection and -probing kicks in. It must be a string consisting
1259entirely of ASCII letters. The string C<AnyEvent::Impl::> gets prepended
1260and the resulting module name is loaded and if the load was successful,
1261used as event model. If it fails to load AnyEvent will proceed with
1262auto detection and -probing.
1263
1264This functionality might change in future versions.
1265
1266For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1267could start your program like this:
1268
1269 PERL_ANYEVENT_MODEL=Perl perl ...
1270
1271=item C<PERL_ANYEVENT_PROTOCOLS>
1272
1273Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1274for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1275of auto probing).
1276
1277Must be set to a comma-separated list of protocols or address families,
1278current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1279used, and preference will be given to protocols mentioned earlier in the
1280list.
1281
1282This variable can effectively be used for denial-of-service attacks
1283against local programs (e.g. when setuid), although the impact is likely
1284small, as the program has to handle connection errors already-
1285
1286Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1287but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1288- only support IPv4, never try to resolve or contact IPv6
1289addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1290IPv6, but prefer IPv6 over IPv4.
1291
1292=item C<PERL_ANYEVENT_EDNS0>
1293
1294Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
1295for DNS. This extension is generally useful to reduce DNS traffic, but
1296some (broken) firewalls drop such DNS packets, which is why it is off by
1297default.
1298
1299Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1300EDNS0 in its DNS requests.
1301
1302=item C<PERL_ANYEVENT_MAX_FORKS>
1303
1304The maximum number of child processes that C<AnyEvent::Util::fork_call>
1305will create in parallel.
1306
1307=back
1308 1328
1309=head1 EXAMPLE PROGRAM 1329=head1 EXAMPLE PROGRAM
1310 1330
1311The following program uses an I/O watcher to read data from STDIN, a timer 1331The following program uses an I/O watcher to read data from STDIN, a timer
1312to display a message once per second, and a condition variable to quit the 1332to display a message once per second, and a condition variable to quit the

Diff Legend

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