view release on metacpan or  search on metacpan

lib/AnyEvent.pm  view on Meta::CPAN

C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
namespace. Other modules are encouraged (but by no means required) to use
C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
variables starting with C<AE_>, see below).

All variables can also be set via the C<AE_> prefix, that is, instead
of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
case there is a clash btween anyevent and another program that uses
C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
variable to the empty string, as those variables take precedence.

When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
exists. If taint mode is on, then AnyEvent will remove I<all> environment
variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
with C<undef> or the empty string, if the corresaponding C<AE_> variable
is set).

The exact algorithm is currently:

   1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
   2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
   3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.

This ensures that child processes will not see the C<AE_> variables.

The following environment variables are currently known to AnyEvent:

=over 4

=item C<PERL_ANYEVENT_VERBOSE>

By default, AnyEvent will log messages with loglevel C<4> (C<error>) or
higher (see L<AnyEvent::Log>). You can set this environment variable to a
numerical loglevel to make AnyEvent more (or less) talkative.

If you want to do more than just set the global logging level
you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
complex specifications.

When set to C<0> (C<off>), then no messages whatsoever will be logged with
everything else at defaults.

When set to C<5> or higher (C<warn>), AnyEvent warns about unexpected
conditions, such as not being able to load the event model specified by
C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
is the minimum recommended level for use during development.

When set to C<7> or higher (info), AnyEvent reports which event model it
chooses.

When set to C<8> or higher (debug), then AnyEvent will report extra
information on which optional modules it loads and how it implements
certain features.

=item C<PERL_ANYEVENT_LOG>

Accepts rather complex logging specifications. For example, you could log
all C<debug> messages of some module to stderr, warnings and above to
stderr, and errors and above to syslog, with:

   PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog

For the rather extensive details, see L<AnyEvent::Log>.

This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
so will take effect even before AnyEvent has initialised itself.

Note that specifying this environment variable causes the L<AnyEvent::Log>
module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
using the latter saves a few hundred kB of memory unless a module
explicitly needs the extra features of AnyEvent::Log.

=item C<PERL_ANYEVENT_STRICT>

AnyEvent does not do much argument checking by default, as thorough
argument checking is very costly. Setting this variable to a true value
will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
check the arguments passed to most method calls. If it finds any problems,
it will croak.

In other words, enables "strict" mode.

Unlike C<use strict> (or its modern cousin, C<< use L<common::sense>
>>, it is definitely recommended to keep it off in production. Keeping
C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
can be very useful, however.

=item C<PERL_ANYEVENT_DEBUG_SHELL>

If this env variable is nonempty, then its contents will be interpreted by
C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
replacing every occurance of C<$$> by the process pid). The shell object
is saved in C<$AnyEvent::Debug::SHELL>.

This happens when the first watcher is created.

For example, to bind a debug shell on a unix domain socket in
F<< /tmp/debug<pid>.sock >>, you could use this:

   PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
   # connect with e.g.: socat readline /tmp/debug123.sock

Or to bind to tcp port 4545 on localhost:

   PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
   # connect with e.g.: telnet localhost 4545

Note that creating sockets in F</tmp> or on localhost is very unsafe on
multiuser systems.

=item C<PERL_ANYEVENT_DEBUG_WRAP>

Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
debugging purposes. See C<AnyEvent::Debug::wrap> for details.

=item C<PERL_ANYEVENT_MODEL>

This can be used to specify the event model to be used by AnyEvent, before
auto detection and -probing kicks in.