[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Log.pm

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.3 by root, Wed Aug 17 02:02:38 2011 UTC vs.
Revision 1.14 by root, Sat Aug 20 01:49:27 2011 UTC

…		…
2		2
3	AnyEvent::Log - simple logging "framework"	3	AnyEvent::Log - simple logging "framework"
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
		7	# simple use
		8	use AnyEvent;
		9
		10	AE::log debug => "hit my knee";
		11	AE::log warn => "it's a bit too hot";
		12	AE::log error => "the flag was false!";
		13	AE::log fatal => "the bit toggled! run!";
		14
		15	# "complex" use
7	use AnyEvent::Log;	16	use AnyEvent::Log;
		17
		18	my $tracer = AnyEvent::Log::logger trace => \$my $trace;
		19
		20	$tracer->("i am here") if $trace;
		21	$tracer->(sub { "lots of data: " . Dumper $self }) if $trace;
		22
		23	# configuration
		24
		25	# set logging for this package to maximum
		26	AnyEvent::Log::ctx->level ("all");
		27
		28	# set logging globally to anything below debug
		29	(AnyEvent::Log::ctx "")->level ("notice");
		30
		31	# see also EXAMPLES, below
		32
		33	# disable logging for package "AnyEvent" and all packages below it
		34	AnyEvent->AnyEvent::Log::ctx->level (0);
		35
		36	# log everything below debug to a file, for the whole program
		37	my $ctx = AnyEvent::Log::ctx;
		38	$ctx->log_cb (sub { print FILE shift; 0 });
		39	(AnyEvent::Log::ctx "")->add ($ctx);
8		40
9	=head1 DESCRIPTION	41	=head1 DESCRIPTION
10		42
11	This module implements a relatively simple "logging framework". It doesn't	43	This module implements a relatively simple "logging framework". It doesn't
12	attempt to be "the" logging solution or even "a" logging solution for	44	attempt to be "the" logging solution or even "a" logging solution for
13	AnyEvent - AnyEvent simply creates logging messages internally, and this	45	AnyEvent - AnyEvent simply creates logging messages internally, and this
14	module more or less exposes the mechanism, with some extra spiff to allow	46	module more or less exposes the mechanism, with some extra spiff to allow
15	using it from other modules as well.	47	using it from other modules as well.
16		48
17	Remember that the default verbosity level is C<0>, so nothing	49	Remember that the default verbosity level is C<0>, so nothing will be
18	will be logged, ever, unless you set C<$Anyvent::VERBOSE> or	50	logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number before
19	C<PERL_ANYEVENT_VERBOSE> to a higher number.	51	starting your program, or change the logging level at runtime with
		52	something like:
20		53
21	Possible future extensions are to allow custom log targets (where the	54	use AnyEvent;
22	level is an object), log filtering based on package, formatting, aliasing	55	(AnyEvent::Log::ctx "")->level ("info");
23	or package groups.
24		56
		57	The design goal behind this module was to keep it simple (and small),
		58	but make it powerful enough to be potentially useful for any module, and
		59	extensive enough for the most common tasks, such as logging to multiple
		60	targets, or being able to log into a database.
		61
		62	The amount of documentation might indicate otherwise, but the module is
		63	still just 240 lines or so.
		64
25	=head1 LOG FUNCTIONS	65	=head1 LOGGING FUNCTIONS
26		66
27	These functions allow you to log messages. They always use the caller's	67	These functions allow you to log messages. They always use the caller's
28	package as a "logging module/source". Also, The main logging function is	68	package as a "logging module/source". Also, the main logging function is
29	easily available as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent>	69	callable as C<AnyEvent::log> or C<AE::log> when the C<AnyEvent> module is
30	module is loaded.	70	loaded.
31		71
32	=over 4	72	=over 4
33		73
34	=cut	74	=cut
35		75
…		…
38	use Carp ();	78	use Carp ();
39	use POSIX ();	79	use POSIX ();
40		80
41	use AnyEvent (); BEGIN { AnyEvent::common_sense }	81	use AnyEvent (); BEGIN { AnyEvent::common_sense }
42	use AnyEvent::Util ();	82	use AnyEvent::Util ();
		83
		84	our $VERSION = $AnyEvent::VERSION;
43		85
44	our ($now_int, $now_str1, $now_str2);	86	our ($now_int, $now_str1, $now_str2);
45		87
46	# Format Time, not public - yet?	88	# Format Time, not public - yet?
47	sub ft($) {	89	sub ft($) {
…		…
52	if $now_int != $i;	94	if $now_int != $i;
53		95
54	"$now_str1$f$now_str2"	96	"$now_str1$f$now_str2"
55	}	97	}
56		98
57	our %CFG; #TODO	99	our %CTX; # all logging contexts
		100
		101	# creates a default package context object for the given package
		102	sub _pkg_ctx($) {
		103	my $ctx = bless [$_[0], (1 << 10) - 1 - 1, {}], "AnyEvent::Log::Ctx";
		104
		105	# link "parent" package
		106	my $pkg = $_[0] =~ /^(.+)::/ ? $1 : "AE::Log::Top";
		107
		108	$pkg = $CTX{$pkg} \|\|= &_pkg_ctx ($pkg);
		109	$ctx->[2]{$pkg+0} = $pkg;
		110
		111	$ctx
		112	}
58		113
59	=item AnyEvent::Log::log $level, $msg[, @args]	114	=item AnyEvent::Log::log $level, $msg[, @args]
60		115
61	Requests logging of the given C<$msg> with the given log level (1..9).	116	Requests logging of the given C<$msg> with the given log level (1..9).
62	You can also use the following strings as log level: C<fatal> (1),	117	You can also use the following strings as log level: C<fatal> (1),
…		…
78		133
79	Whether the given message will be logged depends on the maximum log level	134	Whether the given message will be logged depends on the maximum log level
80	and the caller's package.	135	and the caller's package.
81		136
82	Note that you can (and should) call this function as C<AnyEvent::log> or	137	Note that you can (and should) call this function as C<AnyEvent::log> or
83	C<AE::log>, without C<use>-ing this module if possible, as those functions	138	C<AE::log>, without C<use>-ing this module if possible (i.e. you don't
84	will laod the logging module on demand only.	139	need any additional functionality), as those functions will load the
		140	logging module on demand only. They are also much shorter to write.
		141
		142	Also, if you optionally generate a lot of debug messages (such as when
		143	tracing some code), you should look into using a logger callback and a
		144	boolean enabler (see C<logger>, below).
85		145
86	Example: log something at error level.	146	Example: log something at error level.
87		147
88	AE::log error => "something";	148	AE::log error => "something";
89		149
…		…
108	info => 7,	168	info => 7,
109	debug => 8,	169	debug => 8,
110	trace => 9,	170	trace => 9,
111	);	171	);
112		172
		173	sub now () { time }
		174
		175	AnyEvent::post_detect {
		176	*now = \&AE::now;
		177	};
		178
113	our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);	179	our @LEVEL2STR = qw(0 fatal alert crit error warn note info debug trace);
114		180
		181	# time, ctx, level, msg
		182	sub _format($$$$) {
		183	my $ts = ft $_[0];
		184	my $ct = " ";
		185
		186	my @res;
		187
		188	for (split /\n/, sprintf "%-5s %s: %s", $LEVEL2STR[$_[2]], $_[1][0], $_[3]) {
		189	push @res, "$ts$ct$_\n";
		190	$ct = " + ";
		191	}
		192
		193	join "", @res
		194	}
		195
115	sub _log {	196	sub _log {
116	my ($pkg, $targ, $msg, @args) = @_;	197	my ($ctx, $level, $format, @args) = @_;
117		198
118	my $level = ref $targ ? die "Can't use reference as logging level (yet)"	199	$level = $level > 0 && $level <= 9
119	: $targ > 0 && $targ <= 9 ? $targ+0	200	? $level+0
120	: $STR2LEVEL{$targ} \|\| Carp::croak "$targ: not a valid logging level, caught";	201	: $STR2LEVEL{$level} \|\| Carp::croak "$level: not a valid logging level, caught";
121		202
122	return if $level > $AnyEvent::VERBOSE;	203	my $mask = 1 << $level;
123		204
124	$msg = $msg->() if ref $msg;	205	my (%seen, @ctx, $now, $fmt);
125	$msg = sprintf $msg, @args if @args;
126	$msg =~ s/\n$//;
127		206
128	# now we have a message, log it	207	do
129	#TODO: could do LOTS of stuff here, and should, at least in some later version	208	{
		209	# skip if masked
		210	if ($ctx->[1] & $mask && !$seen{$ctx+0}++) {
		211	if ($ctx->[3]) {
		212	# logging target found
130		213
131	$msg = sprintf "%5s %s: %s", $LEVEL2STR[$level], $pkg, $msg;	214	# now get raw message, unless we have it already
132	my $pfx = ft AE::now;	215	unless ($now) {
		216	$format = $format->() if ref $format;
		217	$format = sprintf $format, @args if @args;
		218	$format =~ s/\n$//;
		219	$now = AE::now;
		220	};
133		221
134	for (split /\n/, $msg) {	222	# format msg
135	printf STDERR "$pfx $_\n";	223	my $str = $ctx->[4]
136	$pfx = "\t";	224	? $ctx->[4]($now, $_[0], $level, $format)
137	}	225	: $fmt \|\|= _format $now, $_[0], $level, $format;
		226
		227	$ctx->[3]($str);
		228	}
		229
		230	# not masked, not consumed - propagate to parent contexts
		231	push @ctx, values %{ $ctx->[2] };
		232	}
		233	}
		234	while $ctx = pop @ctx;
138		235
139	exit 1 if $level <= 1;	236	exit 1 if $level <= 1;
140	}	237	}
141		238
142	sub log($$;@) {	239	sub log($$;@) {
143	_log +(caller)[0], @_;	240	_log
		241	$CTX{ (caller)[0] } \|\|= _pkg_ctx +(caller)[0],
		242	@_;
144	}	243	}
145		244
146	AnyEvent::log = AE::log = \&log;	245	AnyEvent::log = AE::log = \&log;
147		246
148	=item $logger = AnyEvent::Log::logger $level[, \$enabled]	247	=item $logger = AnyEvent::Log::logger $level[, \$enabled]
…		…
191	our %LOGGER;	290	our %LOGGER;
192		291
193	# re-assess logging status for all loggers	292	# re-assess logging status for all loggers
194	sub _reassess {	293	sub _reassess {
195	for (@_ ? $LOGGER{$_[0]} : values %LOGGER) {	294	for (@_ ? $LOGGER{$_[0]} : values %LOGGER) {
196	my ($pkg, $level, $renabled) = @$_;	295	my ($ctx, $level, $renabled) = @$_;
197		296
198	# to detetc whether a message would be logged, we # actually	297	# to detect whether a message would be logged, we # actually
199	# try to log one and die. this isn't # fast, but we can be	298	# try to log one and die. this isn't fast, but we can be
200	# sure that the logging decision is correct :)	299	# sure that the logging decision is correct :)
201		300
202	$$renabled = !eval {	301	$$renabled = !eval {
203	local $SIG{__DIE__};	302	local $SIG{__DIE__};
204		303
205	_log $pkg, $level, sub { die };	304	_log $ctx, $level, sub { die };
206		305
207	1	306	1
208	};	307	};
209		308
210	$$renabled = 1; # TODO	309	$$renabled = 1; # TODO
211	}	310	}
212	}	311	}
213		312
214	sub logger($;$) {	313	sub _logger($;$) {
215	my ($level, $renabled) = @_;	314	my ($ctx, $level, $renabled) = @_;
216		315
217	$renabled \|\|= \my $enabled;	316	$renabled \|\|= \my $enabled;
218	my $pkg = (caller)[0];
219		317
220	$$renabled = 1;	318	$$renabled = 1;
221		319
222	my $logger = [$pkg, $level, $renabled];	320	my $logger = [$ctx, $level, $renabled];
223		321
224	$LOGGER{$logger+0} = $logger;	322	$LOGGER{$logger+0} = $logger;
225		323
226	_reassess $logger+0;	324	_reassess $logger+0;
227		325
…		…
231	};	329	};
232		330
233	sub {	331	sub {
234	$guard if 0; # keep guard alive, but don't cause runtime overhead	332	$guard if 0; # keep guard alive, but don't cause runtime overhead
235		333
236	_log $pkg, $level, @_	334	_log $ctx, $level, @_
237	if $$renabled;	335	if $$renabled;
238	}	336	}
239	}	337	}
240		338
241	#TODO	339	sub logger($;$) {
		340	_logger
		341	$CTX{ (caller)[0] } \|\|= _pkg_ctx +(caller)[0],
		342	@_
		343	}
242		344
243	=back	345	=back
244		346
245	=head1 CONFIGURATION FUNCTIONALITY	347	=head1 LOGGING CONTEXTS
246		348
247	None, yet, except for C<PERL_ANYEVENT_VERBOSE>, described in the L<AnyEvent> manpage.	349	This module associates every log message with a so-called I<logging
		350	context>, based on the package of the caller. Every perl package has its
		351	own logging context.
		352
		353	A logging context has three major responsibilities: filtering, logging and
		354	propagating the message.
		355
		356	For the first purpose, filtering, each context has a set of logging
		357	levels, called the log level mask. Messages not in the set will be ignored
		358	by this context (masked).
		359
		360	For logging, the context stores a formatting callback (which takes the
		361	timestamp, context, level and string message and formats it in the way
		362	it should be logged) and a logging callback (which is responsible for
		363	actually logging the formatted message and telling C<AnyEvent::Log>
		364	whether it has consumed the message, or whether it should be propagated).
		365
		366	For propagation, a context can have any number of attached I<parent
		367	contexts>. Any message that is neither masked by the logging mask nor
		368	masked by the logging callback returning true will be passed to all parent
		369	contexts.
		370
		371	Each call to a logging function will log the message at most once per
		372	context, so it does not matter (much) if there are cycles or if the
		373	message can arrive at the same context via multiple paths.
		374
		375	=head2 DEFAULTS
		376
		377	By default, all logging contexts have an full set of log levels ("all"), a
		378	disabled logging callback and the default formatting callback.
		379
		380	Package contexts have the package name as logging title by default.
		381
		382	They have exactly one parent - the context of the "parent" package. The
		383	parent package is simply defined to be the package name without the last
		384	component, i.e. C<AnyEvent::Debug::Wrapped> becomes C<AnyEvent::Debug>,
		385	and C<AnyEvent> becomes ... C<AnyEvent::Log::Top> which is the
		386	exception of the rule - just like the parent of any package name in
		387	Perl is C<main>, the default parent of any top-level package context is
		388	C<AnyEvent::Log::Top>.
		389
		390	Since perl packages form only an approximate hierarchy, this parent
		391	context can of course be removed.
		392
		393	All other (anonymous) contexts have no parents and an empty title by
		394	default.
		395
		396	When the module is loaded it creates the default context called
		397	C<AnyEvent::Log::Default> (also stored in C<$AnyEvent::Log::Default>),
		398	which simply logs everything to STDERR and doesn't propagate anything
		399	anywhere by default. The purpose of the default context is to provide
		400	a convenient place to override the global logging target or to attach
		401	additional log targets. It's not meant for filtering.
		402
		403	It then creates the root context called C<AnyEvent::Log::Root> (also
		404	stored in C<$AnyEvent::Log::Root>) and sets its log level set to all
		405	levels up to the one specified by C<$ENV{PERL_ANYEVENT_VERBOSE}>. It
		406	then attached the default logging context to it. The purpose of the root
		407	context is to simply provide filtering according to some global log level.
		408
		409	Finally it creates the top-level package context called
		410	C<AnyEvent::Log::Top> (also stored in, you might have guessed,
		411	C<$AnyEvent::Log::Top>) and attached the root context but otherwise leaves
		412	it at default config. It's purpose is simply to collect all log messages
		413	system-wide.
		414
		415	These three special contexts can also be referred to by the
		416	package/context names C<AE::Log::Default>, C<AE::Log::Root> and
		417	C<AE::Log::Top>.
		418
		419	The effect of all this is that log messages, by default, wander up
		420	to the root context where log messages with lower priority then
		421	C<$ENV{PERL_ANYEVENT_VERBOSE}> will be filtered away and then to the
		422	AnyEvent::Log::Default context to be logged to STDERR.
		423
		424	Splitting the top level context into three contexts makes it easy to set
		425	a global logging level (by modifying the root context), but still allow
		426	other contexts to log, for example, their debug and trace messages to the
		427	default target despite the global logging level, or to attach additional
		428	log targets that log messages, regardless of the global logging level.
		429
		430	It also makes it easy to replace the default STDERR-logger by something
		431	that logs to a file, or to attach additional logging targets.
		432
		433	=head2 CREATING/FINDING/DESTROYING CONTEXTS
248		434
249	=over 4	435	=over 4
250		436
		437	=item $ctx = AnyEvent::Log::ctx [$pkg]
		438
		439	This function creates or returns a logging context (which is an object).
		440
		441	If a package name is given, then the context for that packlage is
		442	returned. If it is called without any arguments, then the context for the
		443	callers package is returned (i.e. the same context as a C<AE::log> call
		444	would use).
		445
		446	If C<undef> is given, then it creates a new anonymous context that is not
		447	tied to any package and is destroyed when no longer referenced.
		448
251	=cut	449	=cut
		450
		451	sub ctx(;$) {
		452	my $pkg = @_ ? shift : (caller)[0];
		453
		454	ref $pkg
		455	? $pkg
		456	: defined $pkg
		457	? $CTX{$pkg} \|\|= AnyEvent::Log::_pkg_ctx $pkg
		458	: bless [undef, (1 << 10) - 1 - 1], "AnyEvent::Log::Ctx"
		459	}
		460
		461	=item AnyEvent::Log::reset
		462
		463	Deletes all contexts and recreates the default hierarchy, i.e. resets the
		464	logging subsystem to defaults.
		465
		466	This can be used to implement config-file (re-)loading: before loading a
		467	configuration, reset all contexts.
		468
		469	=cut
		470
		471	sub reset {
		472	@$_ = () for values %CTX; # just to be sure - to kill circular logging dependencies
		473	%CTX = ();
		474
		475	my $default = ctx undef;
		476	$default->title ("AnyEvent::Log::Default");
		477	$default->log_cb (sub {
		478	print STDERR shift;
		479	0
		480	});
		481	$AnyEvent::Log::Default = $CTX{"AnyEvent::Log::Default"} = $CTX{"AE::Log::Default"} = $default;
		482
		483	my $root = ctx undef;
		484	$root->title ("AnyEvent::Log::Root");
		485	$root->level ($AnyEvent::VERBOSE);
		486	$root->attach ($default);
		487	$AnyEvent::Log::Root = $CTX{"AnyEvent::Log::Root"} = $CTX{"AE::Log::Root"} = $root;
		488
		489	my $top = ctx undef;
		490	$top->title ("AnyEvent::Log::Top");
		491	$top->attach ($root);
		492	$AnyEvent::Log::Top = $CTX{"AnyEvent::Log::Top"} = $CTX{"AE::Log::Top"} = $top;
		493	}
		494
		495	AnyEvent::Log::reset;
		496
		497	# hello, CPAN, please catch me
		498	package AnyEvent::Log::Default;
		499	package AE::Log::Default;
		500	package AnyEvent::Log::Root;
		501	package AE::Log::Root;
		502	package AnyEvent::Log::Top;
		503	package AE::Log::Top;
		504
		505	package AnyEvent::Log::Ctx;
		506
		507	# 0 1 2 3 4
		508	# [$title, $level, %$parents, &$logcb, &$fmtcb]
		509
		510	=item $ctx = new AnyEvent::Log::Ctx methodname => param...
		511
		512	This is a convenience constructor that makes it simpler to construct
		513	anonymous logging contexts.
		514
		515	Each key-value pair results in an invocation of the method of the same
		516	name as the key with the value as parameter, unless the value is an
		517	arrayref, in which case it calls the method with the contents of the
		518	array. The methods are called in the same order as specified.
		519
		520	Example: create a new logging context and set both the default logging
		521	level, some parent contexts and a logging callback.
		522
		523	$ctx = new AnyEvent::Log::Ctx
		524	title => "dubious messages",
		525	level => "error",
		526	log_cb => sub { print STDOUT shift; 0 },
		527	parents => [$ctx1, $ctx, $ctx2],
		528	;
		529
		530	=back
		531
		532	=cut
		533
		534	sub new {
		535	my $class = shift;
		536
		537	my $ctx = AnyEvent::Log::ctx undef;
		538
		539	while (@_) {
		540	my ($k, $v) = splice @_, 0, 2;
		541	$ctx->$k (ref $v eq "ARRAY" ? @$v : $v);
		542	}
		543
		544	bless $ctx, $class # do we really support subclassing, hmm?
		545	}
		546
		547
		548	=head2 CONFIGURING A LOG CONTEXT
		549
		550	The following methods can be used to configure the logging context.
		551
		552	=over 4
		553
		554	=item $ctx->title ([$new_title])
		555
		556	Returns the title of the logging context - this is the package name, for
		557	package contexts, and a user defined string for all others.
		558
		559	If C<$new_title> is given, then it replaces the package name or title.
		560
		561	=cut
		562
		563	sub title {
		564	$_[0][0] = $_[1] if @_ > 1;
		565	$_[0][0]
		566	}
		567
		568	=back
		569
		570	=head3 LOGGING LEVELS
		571
		572	The following methods deal with the logging level set associated with the
		573	log context.
		574
		575	The most common method to use is probably C<< $ctx->level ($level) >>,
		576	which configures the specified and any higher priority levels.
		577
		578	All functions which accept a list of levels also accept the special string
		579	C<all> which expands to all logging levels.
		580
		581	=over 4
		582
		583	=item $ctx->levels ($level[, $level...)
		584
		585	Enables logging for the given levels and disables it for all others.
		586
		587	=item $ctx->level ($level)
		588
		589	Enables logging for the given level and all lower level (higher priority)
		590	ones. In addition to normal logging levels, specifying a level of C<0> or
		591	C<off> disables all logging for this level.
		592
		593	Example: log warnings, errors and higher priority messages.
		594
		595	$ctx->level ("warn");
		596	$ctx->level (5); # same thing, just numeric
		597
		598	=item $ctx->enable ($level[, $level...])
		599
		600	Enables logging for the given levels, leaving all others unchanged.
		601
		602	=item $ctx->disable ($level[, $level...])
		603
		604	Disables logging for the given levels, leaving all others unchanged.
		605
		606	=cut
		607
		608	sub _lvl_lst {
		609	map {
		610	$_ > 0 && $_ <= 9 ? $_+0
		611	: $_ eq "all" ? (1 .. 9)
		612	: $STR2LEVEL{$_} \|\| Carp::croak "$_: not a valid logging level, caught"
		613	} @_
		614	}
		615
		616	our $NOP_CB = sub { 0 };
		617
		618	sub levels {
		619	my $ctx = shift;
		620	$ctx->[1] = 0;
		621	$ctx->[1] \|= 1 << $_
		622	for &_lvl_lst;
		623	AnyEvent::Log::_reassess;
		624	}
		625
		626	sub level {
		627	my $ctx = shift;
		628	my $lvl = $_[0] =~ /^(?:0\|off\|none)$/ ? 0 : (_lvl_lst $_[0])[-1];
		629
		630	$ctx->[1] = ((1 << $lvl) - 1) << 1;
		631	AnyEvent::Log::_reassess;
		632	}
		633
		634	sub enable {
		635	my $ctx = shift;
		636	$ctx->[1] \|= 1 << $_
		637	for &_lvl_lst;
		638	AnyEvent::Log::_reassess;
		639	}
		640
		641	sub disable {
		642	my $ctx = shift;
		643	$ctx->[1] &= ~(1 << $_)
		644	for &_lvl_lst;
		645	AnyEvent::Log::_reassess;
		646	}
		647
		648	=back
		649
		650	=head3 PARENT CONTEXTS
		651
		652	The following methods attach and detach another logging context to a
		653	logging context.
		654
		655	Log messages are propagated to all parent contexts, unless the logging
		656	callback consumes the message.
		657
		658	=over 4
		659
		660	=item $ctx->attach ($ctx2[, $ctx3...])
		661
		662	Attaches the given contexts as parents to this context. It is not an error
		663	to add a context twice (the second add will be ignored).
		664
		665	A context can be specified either as package name or as a context object.
		666
		667	=item $ctx->detach ($ctx2[, $ctx3...])
		668
		669	Removes the given parents from this context - it's not an error to attempt
		670	to remove a context that hasn't been added.
		671
		672	A context can be specified either as package name or as a context object.
		673
		674	=item $ctx->parents ($ctx2[, $ctx3...])
		675
		676	Replaces all parents attached to this context by the ones given.
		677
		678	=cut
		679
		680	sub attach {
		681	my $ctx = shift;
		682
		683	$ctx->[2]{$_+0} = $_
		684	for map { AnyEvent::Log::ctx $_ } @_;
		685	}
		686
		687	sub detach {
		688	my $ctx = shift;
		689
		690	delete $ctx->[2]{$_+0}
		691	for map { AnyEvent::Log::ctx $_ } @_;
		692	}
		693
		694	sub parents {
		695	undef $_[0][2];
		696	&attach;
		697	}
		698
		699	=back
		700
		701	=head3 MESSAGE LOGGING
		702
		703	The following methods configure how the logging context actually does
		704	the logging (which consists of formatting the message and printing it or
		705	whatever it wants to do with it) and also allows you to log messages
		706	directly to a context, without going via your package context.
		707
		708	=over 4
		709
		710	=item $ctx->log_cb ($cb->($str))
		711
		712	Replaces the logging callback on the context (C<undef> disables the
		713	logging callback).
		714
		715	The logging callback is responsible for handling formatted log messages
		716	(see C<fmt_cb> below) - normally simple text strings that end with a
		717	newline (and are possibly multiline themselves).
		718
		719	It also has to return true iff it has consumed the log message, and false
		720	if it hasn't. Consuming a message means that it will not be sent to any
		721	parent context. When in doubt, return C<0> from your logging callback.
		722
		723	Example: a very simple logging callback, simply dump the message to STDOUT
		724	and do not consume it.
		725
		726	$ctx->log_cb (sub { print STDERR shift; 0 });
		727
		728	You can filter messages by having a log callback that simply returns C<1>
		729	and does not do anything with the message, but this counts as "message
		730	being logged" and might not be very efficient.
		731
		732	Example: propagate all messages except for log levels "debug" and
		733	"trace". The messages will still be generated, though, which can slow down
		734	your program.
		735
		736	$ctx->levels ("debug", "trace");
		737	$ctx->log_cb (sub { 1 }); # do not log, but eat debug and trace messages
		738
		739	=item $ctx->fmt_cb ($fmt_cb->($timestamp, $ctx, $level, $message))
		740
		741	Replaces the formatting callback on the context (C<undef> restores the
		742	default formatter).
		743
		744	The callback is passed the (possibly fractional) timestamp, the original
		745	logging context, the (numeric) logging level and the raw message string and needs to
		746	return a formatted log message. In most cases this will be a string, but
		747	it could just as well be an array reference that just stores the values.
		748
		749	Example: format just the raw message, with numeric log level in angle
		750	brackets.
		751
		752	$ctx->fmt_cb (sub {
		753	my ($time, $ctx, $lvl, $msg) = @_;
		754
		755	"<$lvl>$msg\n"
		756	});
		757
		758	Example: return an array reference with just the log values, and use
		759	C<PApp::SQL::sql_exec> to store the emssage in a database.
		760
		761	$ctx->fmt_cb (sub { \@_ });
		762	$ctx->log_cb (sub {
		763	my ($msg) = @_;
		764
		765	sql_exec "insert into log (when, subsys, prio, msg) values (?, ?, ?, ?)",
		766	$msg->[0] + 0,
		767	"$msg->[1]",
		768	$msg->[2] + 0,
		769	"$msg->[3]";
		770
		771	0
		772	});
		773
		774	=cut
		775
		776	sub log_cb {
		777	my ($ctx, $cb) = @_;
		778
		779	$ctx->[3] = $cb;
		780	}
		781
		782	sub fmt_cb {
		783	my ($ctx, $cb) = @_;
		784
		785	$ctx->[4] = $cb;
		786	}
		787
		788	=item $ctx->log ($level, $msg[, @params])
		789
		790	Same as C<AnyEvent::Log::log>, but uses the given context as log context.
		791
		792	=item $logger = $ctx->logger ($level[, \$enabled])
		793
		794	Same as C<AnyEvent::Log::logger>, but uses the given context as log
		795	context.
		796
		797	=cut
		798
		799	*log = \&AnyEvent::Log::_log;
		800	*logger = \&AnyEvent::Log::_logger;
252		801
253	1;	802	1;
		803
		804	=back
		805
		806	=head1 EXAMPLES
		807
		808	This section shows some common configurations.
		809
		810	=over 4
		811
		812	=item Setting the global logging level.
		813
		814	Either put PERL_ANYEVENT_VERBOSE=<number> into your environment before
		815	running your program, or modify the log level of the root context:
		816
		817	PERL_ANYEVENT_VERBOSE=5 ./myprog
		818
		819	$AnyEvent::Log::Root->level ("warn");
		820
		821	=item Append all messages to a file instead of sending them to STDERR.
		822
		823	This is affected by the global logging level.
		824
		825	open my $fh, ">>", $path
		826	or die "$path: $!";
		827
		828	$AnyEvent::Log::Default->log_cb (sub {
		829	syswrite $fh, shift;
		830	0
		831	});
		832
		833	=item Write all messages with priority C<error> and higher to a file.
		834
		835	This writes them only when the global logging level allows it, because
		836	it is attached to the default context which is invoked I<after> global
		837	filtering.
		838
		839	open my $fh, ">>", $path
		840	or die "$path: $!";
		841
		842	$AnyEvent::Log::Default->attach (new AnyEvent::Log::Ctx
		843	log_cb => sub { syswrite $fh, shift; 0 });
		844
		845	This writes them regardless of the global logging level, because it is
		846	attached to the toplevel context, which receives all messages I<before>
		847	the global filtering.
		848
		849	$AnyEvent::Log::Top->attach (new AnyEvent::Log::Ctx
		850	log_cb => sub { syswrite $fh, shift; 0 });
		851
		852	In both cases, messages are still written to STDOUT.
		853
		854	=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
		855
		856	Attach the CyAnyEvent::Log::Default> context to the C<AnyEvent::Debug>
		857	context and increase the C<AnyEvent::Debug> logging level - this simply
		858	circumvents the global filtering for trace messages.
		859
		860	my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
		861	$debug->attach ($AnyEvent::Log::Default);
		862	$debug->levels ("trace"); # not "level"!
		863
		864	This of course works for any package.
254		865
255	=back	866	=back
256		867
257	=head1 AUTHOR	868	=head1 AUTHOR
258		869

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents): Revision 1.3 by root, Wed Aug 17 02:02:38 2011 UTC vs. Revision 1.14 by root, Sat Aug 20 01:49:27 2011 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.3 by root, Wed Aug 17 02:02:38 2011 UTC vs.
Revision 1.14 by root, Sat Aug 20 01:49:27 2011 UTC