1POE::Component::SimpleLUosge(r3)Contributed Perl DocumenPtOaEt:i:oCnomponent::SimpleLog(3)
2
3
4
6 POE::Component::SimpleLog - Perl extension to manage a simple logging
7 system for POE.
8
10 use POE;
11 use POE::Component::SimpleLog;
12
13 # We don't want Time::HiRes
14 POE::Component::SimpleLog->new(
15 ALIAS => 'MyLog',
16 PRECISION => undef,
17 ) or die 'Unable to create the Logger';
18
19 # Create our own session to communicate with SimpleLog
20 POE::Session->create(
21 inline_states => {
22 _start => sub {
23 # Register for various logs
24 $_[KERNEL]->post( 'MyLog', 'REGISTER',
25 LOGNAME => 'FOO',
26 SESSION => $_[SESSION],
27 EVENT => 'GotFOOlog',
28 );
29
30 $_[KERNEL]->post( 'MyLog', 'REGISTER',
31 LOGNAME => 'BAZ',
32 SESSION => $_[SESSION],
33 EVENT => 'GotBAZlog',
34 );
35
36 # Log something!
37 $_[KERNEL]->post( 'MyLog', 'LOG', 'FOO', 'Wow, what a FOO!' );
38
39 # This will be silently discarded -> nobody registered for it
40 $_[KERNEL]->post( 'MyLog', 'LOG', 'BOO', 'Wow, what a BAZ!' );
41
42 # OK, enough logging!
43 $_[KERNEL]->post( 'MyLog', 'UNREGISTER',
44 LOGNAME => 'FOO',
45 SESSION => $_[SESSION],
46 EVENT => 'GotFOOlog',
47 );
48
49 # Now, this log will go nowhere as we just unregistered for it
50 $_[KERNEL]->post( 'MyLog', 'LOG', 'FOO', 'Wow, what a FOO!' );
51
52 # Completely remove all registrations!
53 $_[KERNEL]->post( 'MyLog', 'UNREGISTERSESSION', $_[SESSION] );
54
55 # Now, this log will go nowhere as we just removed all logs pertaining to our session
56 $_[KERNEL]->post( 'MyLog', 'LOG', 'BAZ', 'Wow, what a BAZ!' );
57
58 # We want to eat all we can!
59 $_[KERNEL]->post( 'MyLog', 'REGISTER',
60 LOGNAME => 'ALL',
61 SESSION => $_[SESSION],
62 EVENT => 'GotLOG',
63 );
64
65 # Now, *ANY* log issued to SimpleLog will go to GotLOG
66 $_[KERNEL]->post( 'MyLog', 'LOG', 'LAF', 'Wow, what a LAF!' );
67
68 # We are done!
69 $_[KERNEL]->post( 'MyLog', 'SHUTDOWN' );
70 },
71
72 'GotFOOlog' => \&gotFOO,
73 },
74 );
75
76 sub gotFOO {
77 # Get the arguments
78 my( $file, $line, $time, $name, $message ) = @_[ ARG0 .. ARG4 ];
79
80 # Assumes PRECISION is undef ( regular time() )
81 print STDERR "$time ${name}-> $file : $line = $message\n";
82 }
83
85 Very simple, and flexible logging system tailored for POE.
86
88 This module is a vastly simplified logging system that can do nice
89 stuff. Think of this module as a dispatcher for various logs.
90
91 This module *DOES NOT* do anything significant with logs, it simply
92 routes them to the appropriate place ( Events )
93
94 You register a log that you are interested in, by telling SimpleLog the
95 target session and target event. Once that is done, any log messages
96 your program generates ( sent to SimpleLog of course ) will be mas‐
97 saged, then sent to the target session / target event for processing.
98
99 This enables an interesting logging system that can be changed during
100 runtime and allow pluggable interpretation of messages.
101
102 One nifty idea you can do with this is:
103
104 Your program generally creates logs with the name of 'DEBUG'. You DCC
105 Chat your IRC bot, then tell it to show all debug messages to you. All
106 the irc bot have to do is register itself for all 'DEBUG' messages, and
107 once you disconnect from the bot, it can unregister itself.
108
109 NOTE: There is no pre-determined log levels ( Like Log4j's DEBUG / INFO
110 / FATAL / etc ) Arbitrary names can be used, to great effect. Logs with
111 the names 'CONNECT', 'DB_QUERY', etc can be created.
112
113 The standard way to use this module is to do this:
114
115 use POE;
116 use POE::Component::SimpleLog;
117
118 POE::Component::SimpleLog->new( ... );
119
120 POE::Session->create( ... );
121
122 POE::Kernel->run();
123
124 Starting SimpleLog
125
126 To start SimpleLog, just call it's new method:
127
128 POE::Component::SimpleLog->new(
129 'ALIAS' => 'MyLogger',
130 'PRECISION' => 1,
131 );
132
133 This method will die on error or return success.
134
135 This constructor accepts only 2 options.
136
137 "ALIAS"
138 This will set the alias SimpleLog uses in the POE Kernel. This
139 will default TO "SimpleLog"
140
141 "PRECISION"
142 If this value is defined, SimpleLog will use Time::HiRes to get the
143 timestamps.
144
145 Events
146
147 SimpleLog is so simple, there are only 5 events available.
148
149 "REGISTER"
150 This event accepts 3 arguments:
151
152 LOGNAME -> The name of the log to register for
153 SESSION -> The session where the log will go ( Also accepts Session ID's )
154 EVENT -> The event that will be called
155
156 The act of registering for a log can fail if one of the above values are undefined.
157
158 If the LOGNAME eq 'ALL', then that registration will get *ALL* the logs SimpleLog processes
159
160 There is no such thing as an "non-existant" log, registration just makes sure that you will get this log *WHEN* it comes.
161
162 Events that receive the logs will get these:
163 ARG0 -> CALLER_FILE
164 ARG1 -> CALLER_LINE
165 ARG2 -> Time::HiRes [ gettimeofday ] or time()
166 ARG3 -> LOGNAME
167 ARG4 -> Message
168
169 Here's an example:
170
171 $_[KERNEL]->post( 'SimpleLog', 'REGISTER',
172 LOGNAME => 'CONNECTION',
173 SESSION => $_[SESSION],
174 EVENT => 'GotLOG',
175 );
176
177 This is the subroutine that will get the GotLOG event
178 sub gotlog {
179 # Get the arguments
180 my( $file, $line, $time, $name, $message ) = @_[ ARG0 .. ARG4 ];
181
182 # Assumes PRECISION is undef ( regular time() )
183 print STDERR "$time ${name}-> $file : $line = $message\n";
184
185 # PRECISION = true ( Time::HiRes )
186 print STDERR "$time->[0].$time->[1] ${name}-> $file : $line = $message\n";
187 }
188
189 "UNREGISTER"
190 This event accepts 3 arguments:
191
192 LOGNAME -> The name of the log to unregister for
193 SESSION -> The session where the log will go ( Also accepts Session ID's )
194 EVENT -> The event that will be called
195
196 Unregistering for a log will fail if the exact 3 arguments were not found in our registry.
197
198 The act of unregistering will mean the session/event no longer receives any log messages.
199
200 NOTE: There might be some logs still traversing POE's queue...
201
202 Here's an example:
203
204 $_[KERNEL]->post( 'SimpleLog', 'UNREGISTER',
205 LOGNAME => 'CONNECTION',
206 SESSION => $_[SESSION]->ID,
207 EVENT => 'GotLOG',
208 );
209
210 "UNREGISTERSESSION"
211 This event accepts 1 argument:
212
213 ARG0 -> The session ( Also accepts Session ID's )
214
215 This is useful for removing all the registrations for a specific session.
216
217 Here's an example:
218
219 $_[KERNEL]->post( 'SimpleLog', 'UNREGISTERSESSION', $_[SESSION] );
220
221 "LOG"
222 This event accepts 2 arguments:
223
224 ARG0 -> Logname
225 ARG1 -> Message
226
227 This is where SimpleLog does it's work, sending the log to the proper events.
228
229 The Logname can be anything, if there is no events registered for it, the message will simply be discarded.
230
231 Here's an example:
232
233 $_[KERNEL]->post( 'SimpleLog', 'LOG', 'CONNECTION', 'A Client just connected!' );
234
235 "SHUTDOWN"
236 This is the generic SHUTDOWN routine, it will stop all logging.
237
238 Here's an example:
239
240 $_[KERNEL]->post( 'SimpleLog', 'SHUTDOWN' );
241
242 SimpleLog Notes
243
244 This module is very picky about capitalization!
245
246 All of the options are uppercase, to avoid confusion.
247
248 You can enable debugging mode by doing this:
249
250 sub POE::Component::SimpleLog::DEBUG () { 1 }
251 use POE::Component::SimpleLog;
252
253 EXPORT
254
255 Nothing.
256
258 POE
259
261 Apocalypse <apocal@cpan.org>
262
264 Copyright 2005 by Apocalypse
265
266 This library is free software; you can redistribute it and/or modify it
267 under the same terms as Perl itself.
268
269
270
271perl v5.8.8 2006-09-18 POE::Component::SimpleLog(3)