edu.rice.cs.plt.debug
Class AsynchronousLogSink

java.lang.Object
  edu.rice.cs.plt.debug.AsynchronousLogSink

All Implemented Interfaces:

LogSink, java.io.Closeable

public class AsynchronousLogSink
extends java.lang.Object
implements LogSink

A LogSink that processes log messages in a separate thread. This minimizes the impact of logging bottlenecks on the performance of the program. When the first log message is sent to this sink, a daemon thread is started which records and waits for messages until the program terminates.

The impact of logging on performance cannot be entirely eliminated. In addition to the added pressure caused by an additional logging thread, the program thread still must generate a stack trace for each logging invocation, and enqueuing each logging message can take both time and space.

An advantage of synchronous logging is that users can infer from the lack of a message in a log that a certain invocation never occurred. In contrast, it is possible for asynchronous log messages to be created but not recorded before program termination (or any other arbitrary deadline). To avoid this problem, users may invoke flush() at any time, which will block until all messages in a nonempty queue have been recorded; additionally, by default a shutdown hook is registered which attempts to flush the queue before program shutdown completes.

Nested Class Summary

Nested classes/interfaces inherited from interface edu.rice.cs.plt.debug.LogSink

LogSink.EndMessage, LogSink.ErrorMessage, LogSink.Message, LogSink.MessageVisitor<T>, LogSink.StackMessage, LogSink.StandardMessage, LogSink.StartMessage, LogSink.ValueMessage

Constructor Summary

AsynchronousLogSink(LogSink delegate)
Create an asynchronous LogSink which passes messages to the given delegate sink.

AsynchronousLogSink(LogSink delegate, boolean flushOnShutdown)
Create an asynchronous LogSink which passes messages to the given delegate sink.

Method Summary

void	close()
void	flush() If any log messages have been enqueued but not yet recorded, block until they are recorded.
void	log(LogSink.StandardMessage m)
void	logEnd(LogSink.EndMessage m)
void	logError(LogSink.ErrorMessage m)
void	logStack(LogSink.StackMessage m)
void	logStart(LogSink.StartMessage m)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AsynchronousLogSink

public AsynchronousLogSink(LogSink delegate)

Create an asynchronous LogSink which passes messages to the given delegate sink. Sets flushOnShutdown to true.

AsynchronousLogSink

public AsynchronousLogSink(LogSink delegate,
                           boolean flushOnShutdown)

Create an asynchronous LogSink which passes messages to the given delegate sink.

Parameters:

flushOnShutdown - Whether a shutdown hook invoking flush() should be registered when the logging thread is first started.

Method Detail

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException

flush

public void flush()
           throws java.lang.InterruptedException

If any log messages have been enqueued but not yet recorded, block until they are recorded.

Throws:

java.lang.InterruptedException

log

public void log(LogSink.StandardMessage m)

Specified by:

log in interface LogSink

logStart

public void logStart(LogSink.StartMessage m)

Specified by:

logStart in interface LogSink

logEnd

public void logEnd(LogSink.EndMessage m)

Specified by:

logEnd in interface LogSink

logError

public void logError(LogSink.ErrorMessage m)

Specified by:

logError in interface LogSink

logStack

public void logStack(LogSink.StackMessage m)

Specified by:

logStack in interface LogSink