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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.8 by root, Fri Aug 19 19:20:36 2011 UTC vs.
Revision 1.9 by root, Fri Aug 19 19:59:53 2011 UTC

… …
31module more or less exposes the mechanism, with some extra spiff to allow 31module more or less exposes the mechanism, with some extra spiff to allow
32using it from other modules as well. 32using it from other modules as well.
33 33
34Remember that the default verbosity level is C<0>, so nothing will be 34Remember that the default verbosity level is C<0>, so nothing will be
35logged, ever, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number 35logged, ever, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number
36before starting your program.#TODO 36before starting your program, or change the logging level at runtime wiht
37something like:
37 38
38Possible future extensions are to allow custom log targets (where the 39 use AnyEvent;
39level is an object), log filtering based on package, formatting, aliasing 40 (AnyEvent::Log::ctx "")->level ("info");
40or package groups.
41 41
42=head1 LOG FUNCTIONS 42=head1 LOGGING FUNCTIONS
43 43
44These functions allow you to log messages. They always use the caller's 44These functions allow you to log messages. They always use the caller's
45package as a "logging module/source". Also, the main logging function is 45package as a "logging module/source". Also, the main logging function is
46callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is 46callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is
47loaded. 47loaded.
… …
310 310
311#TODO 311#TODO
312 312
313=back 313=back
314 314
315=head1 CONFIGURATION FUNCTIONALITY 315=head1 LOGGING CONTEXTS
316 316
317None, yet, except for C<PERL_ANYEVENT_VERBOSE>, described in the L<AnyEvent> manpage. 317This module associates every log message with a so-called I<logging
318context>, based on the package of the caller. Every perl package has its
319own logging context.
318 320
319#TODO: wahst a context 321A logging context has two major responsibilities: logging the message and
320#TODO 322propagating the message to other contexts.
323
324For logging, the context stores a set of logging levels that it
325potentially wishes to log, a formatting callback that takes the timestamp,
326context, level and string emssage and formats it in the way it should be
327logged, and a logging callback, which is responsible for actually logging
328the formatted message and telling C<AnyEvent::Log> whether it has consumed
329the message, or whether it should be propagated.
330
331For propagation, a context can have any number of attached I<parent
332contexts>. They will be ignored if the logging callback consumes the
333message, but in all other cases, the log message will be passed to all
334parent contexts attached to a context.
335
336=head2 DEFAULTS
337
338By default, all logging contexts have an empty set of log levels, a
339disabled logging callback and the default formatting callback.
340
341Package contexts have the package name as logging title by default.
342
343They have exactly one parent - the context of the "parent" package. The
344parent package is simply defined to be the package name without the last
345component, i.e. C<AnyEvent::Debug::Wrapped> becomes C<AnyEvent::Debug>,
346and C<AnyEvent> becomes the empty string.
347
348Since perl packages form only an approximate hierarchy, this parent
349context can of course be removed.
350
351All other (anonymous) contexts have no parents and an empty title by
352default.
353
354When the module is first loaded, it configures the root context (the one
355with the empty string) to simply dump all log messages to C<STDERR>,
356and sets it's log level set to all levels up to the one specified by
357C<$ENV{PERL_ANYEVENT_VERBOSE}>.
358
359The effetc of all this is that log messages, by default, wander up to the
360root context and will be logged to STDERR if their log level is less than
361or equal to C<$ENV{PERL_ANYEVENT_VERBOSE}>.
362
363=head2 CREATING/FINDING A CONTEXT
321 364
322=over 4 365=over 4
323 366
324=item $ctx = AnyEvent::Log::ctx [$pkg] 367=item $ctx = AnyEvent::Log::ctx [$pkg]
325 368
326Returns a I<config> object for the given package name. 369This function creates or returns a logging context (which is an object).
327 370
328If no package name is given, returns the context for the current perl 371If a package name is given, then the context for that packlage is
372returned. If it is called without any arguments, then the context for the
329package (i.e. the same context as a C<AE::log> call would use). 373callers package is returned (i.e. the same context as a C<AE::log> call
374would use).
330 375
331If C<undef> is given, then it creates a new anonymous context that is not 376If C<undef> is given, then it creates a new anonymous context that is not
332tied to any package and is destroyed when no longer referenced. 377tied to any package and is destroyed when no longer referenced.
333 378
334=cut 379=cut
… …
346# create default root context 391# create default root context
347{ 392{
348 my $root = ctx undef; 393 my $root = ctx undef;
349 $root->[0] = ""; 394 $root->[0] = "";
350 $root->title ("default"); 395 $root->title ("default");
351 $root->level ($AnyEvent::VERBOSE); 396 $root->level ($AnyEvent::VERBOSE); undef $AnyEvent::VERBOSE;
352 $root->log_cb (sub { 397 $root->log_cb (sub {
353 print STDERR shift; 398 print STDERR shift;
354 0 399 0
355 }); 400 });
356 $CTX{""} = $root; 401 $CTX{""} = $root;
357} 402}
358 403
404=back
405
406=cut
407
359package AnyEvent::Log::Ctx; 408package AnyEvent::Log::Ctx;
360 409
361# 0 1 2 3 4 410# 0 1 2 3 4
362# [$title, $level, %$parents, &$logcb, &$fmtcb] 411# [$title, $level, %$parents, &$logcb, &$fmtcb]
412
413=head2 CONFIGURING A LOG CONTEXT
414
415The following methods can be used to configure the logging context.
416
417=over 4
363 418
364=item $ctx->title ([$new_title]) 419=item $ctx->title ([$new_title])
365 420
366Returns the title of the logging context - this is the package name, for 421Returns the title of the logging context - this is the package name, for
367package contexts, and a user defined string for all others. 422package contexts, and a user defined string for all others.
… …
372 427
373sub title { 428sub title {
374 $_[0][0] = $_[1] if @_ > 1; 429 $_[0][0] = $_[1] if @_ > 1;
375 $_[0][0] 430 $_[0][0]
376} 431}
432
433=back
434
435=head3 LOGGING LEVELS
436
437The following methods deal with the logging level set associated wiht the log context.
438
439The most common method to use is probably C<< $ctx->level ($level) >>,
440which configures the specified and any higher priority levels.
441
442=over 4
377 443
378=item $ctx->levels ($level[, $level...) 444=item $ctx->levels ($level[, $level...)
379 445
380Enables logging fot the given levels and disables it for all others. 446Enables logging fot the given levels and disables it for all others.
381 447
… …
434 $ctx->[1] &= ~(1 << $_) 500 $ctx->[1] &= ~(1 << $_)
435 for &_lvl_lst; 501 for &_lvl_lst;
436 AnyEvent::Log::_reassess; 502 AnyEvent::Log::_reassess;
437} 503}
438 504
505=back
506
507=head3 PARENT CONTEXTS
508
509The following methods attach and detach another logging context to a
510logging context.
511
512Log messages are propagated to all parent contexts, unless the logging
513callback consumes the message.
514
515=over 4
516
439=item $ctx->attach ($ctx2[, $ctx3...]) 517=item $ctx->attach ($ctx2[, $ctx3...])
440 518
441Attaches the given contexts as parents to this context. It is not an error 519Attaches the given contexts as parents to this context. It is not an error
442to add a context twice (the second add will be ignored). 520to add a context twice (the second add will be ignored).
443 521
… …
463 my $ctx = shift; 541 my $ctx = shift;
464 542
465 delete $ctx->[2]{$_+0} 543 delete $ctx->[2]{$_+0}
466 for map { AnyEvent::Log::ctx $_ } @_; 544 for map { AnyEvent::Log::ctx $_ } @_;
467} 545}
546
547=back
548
549=head3 MESSAGE LOGGING
550
551The following methods configure how the logging context actually does
552the logging (which consists of foratting the message and printing it or
553whatever it wants to do with it) and also allows you to log messages
554directly to a context, without going via your package context.
555
556=over 4
468 557
469=item $ctx->log_cb ($cb->($str)) 558=item $ctx->log_cb ($cb->($str))
470 559
471Replaces the logging callback on the context (C<undef> disables the 560Replaces the logging callback on the context (C<undef> disables the
472logging callback). 561logging callback).

Diff Legend

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