[plt-scheme] logging support (v4.0.2.4)

PLT Scheme version 4.0.2.4 (now in SVN) adds a first cut at
long-planned logging support. The logging API is fairly simple, and
it's based on similar support in Java, Python, etc.


Logging is built in, instead of implemented as a separate library, so
that the run-time system can report information through logging. For
example, when the bytecode compiler sees

 (define (go)
   (let ([f (lambda (x) x)])
     (f 1 2)))

then it easily detects that `f' is applied to the wrong number of
arguments if `go' is ever called. Sometimes, you'd like the optimizer
to tell you what it sees. Now it can --- if you turn up stderr event
reporting to "warning":

 laptop% mzscheme -W warning
 Welcome to MzScheme v4.0.2.4 [3m], Copyright (c) 2004-2008 PLT Scheme Inc.
 >  (define (go)
      (let ([f (lambda (x) x)])
        (f 1 2)))
 warning in: readline::2: go: optimizer detects procedure incorrectly applied
 to 2 arguments: f
 >

If you turn up reporting all the way to "info", then you get
information about garbage collections:

 laptop% mzscheme -W info
 Welcome to MzScheme v4.0.2.4 [3m], Copyright (c) 2004-2008 PLT Scheme Inc.
 GC [minor] at 1406520 bytes; 614944 collected in 5 msec
 GC [minor] at 2226032 bytes; 569248 collected in 7 msec
 GC [minor] at 4062888 bytes; 1087372 collected in 14 msec
 GC [minor] at 5617048 bytes; 1057728 collected in 17 msec
 GC [minor] at 7480240 bytes; 1181160 collected in 15 msec
 GC [minor] at 10601456 bytes; 1568052 collected in 24 msec
 GC [minor] at 15007512 bytes; 3217852 collected in 32 msec
 GC [minor] at 19120856 bytes; 4374972 collected in 41 msec
 >

For now, that's about all of the events that the run-time system logs,
but we expect more (and better formatted) events from the run-time
system in the future.


Instead of passing the -W command-line flag, you can set the PLTSTDERR
environment variable:

 laptop% env PLTSTDERR=info mzscheme 
 Welcome to MzScheme v4.0.2.4 [3m], Copyright (c) 2004-2008 PLT Scheme Inc.
 GC [minor] at 1406520 bytes; 614944 collected in 5 msec
 GC [minor] at 2226032 bytes; 569248 collected in 6 msec
 ...


Besides recording logged events to stderr (i.e., the original error
port), events can be recorded to the system log. Use the -L flag or
PLTSYSLOG flag to turn up system-log recording. By default, system-log
recording is set to "none" under Unix and "error" (the same as default
stderr recording) for Windows and Mac OS X.

More logging is on by default for Windows and Mac OS X because it's
more normal for applications to log messages on those platforms.


The log event levels, in decreasing order, are "fatal", "error",
"warning", "info", and "debug". To log a message at one of these
levels, the simplest way is to use the corresponding `log-' form:

 laptop% env PLTSTDERR=warning mzscheme
 Welcome to MzScheme v4.0.2.4 [3m], Copyright (c) 2004-2008 PLT Scheme Inc.
 > (log-warning "beware of dog")
 beware of dog
 > (log-info "beware of mice")
 >

The string-generating expression in `log-warning', etc., is not
evaluated if no one is listening for the corresponding level of events.

The more general interface is the `log-message' function, which takes a
target logger, a level symbol, a message string, and arbitrary data:

 > (log-message (current-logger) 'warning "beware of dog" 42)
 beware of dog

Instead of the number 42, a more typical value to supply with the
message is a set of continuation marks. That's what `log-warning', etc.
supply.


To receive logged events, create a log receiver. The receiver gets
events at a specified level or higher. To extract information for a
logged event, `sync' on the receiver:

 > (define lr (make-log-receiver (current-logger) 'info))
 > (log-info "beware of mice")
 > (sync lr)
 #(info "beware of mice" #<continuation-mark-set>)


See the documentation (section 14.5 in the reference manual) for a few
extra details, including information on named loggers and logger
hierarchies.


Matthew