| << Prev | - Up - | Next >> |
This appendix documents some supporting classes required to observe a running compiler. These classes implement a general producer - consumer pattern for the status of a running computation and the error messages generated by it. They can be used independently of the compiler (actually, they are also used by the ozdoc tool that generated this documentation).
A narrator, presented in Section B.1, is a producer of status and error messages. Conversely, a Listener, presented in Section B.2, is a consumer of such messages. Each listener is connected to exactly one narrator; every narrator may have a number of listeners (you can observe this if you open compiler panels in the Oz Programming Interface).
Typically, the result (from, say, a compilation) one will want to programmatically check for is success or failure, and the list of error messages generated. An error listener provides easy access to precisely that information, and is presented in Section B.3.
Narrator Module The Narrator module, located at x-oz://system/Narrator, exports a class Narrator.'class' which is the superclass of all narrators. It manages a number of connected listeners (which are simply ports for the purpose of narrators) and provides for broadcasting messages to all registered listeners. The constructor returns a private narrator instance, used by the running computation to send well-defined status messages. Both of these classes are described in the following.
Narrator.'class'Methods
init(?PrivateNarratorO) initializes a narrator that initially has no listeners attached, and returns the corresponding private narrator.
register(+Port) registers a new listener Port. All subsequently told messages will be forwarded to Port.
newListener(+Port) is invoked on every new listener Port that is registered. The default action is a no-op; subclasses may override this for example to provide the new Listener with a summary of the current state (as a batch of messages).
unregister(+Port) unregisters a listener Port. No more messages will subsequently be forwarded to Port.
tell(X) broadcasts the message X to all registered listeners.
Methods
setLogPhases(+B) determines whether messages about phases of the underlying computations should be broadcasted to listeners (if B is true) or not (if B is false). The default is false.
setMaxNumberOfErrors(+I) sets the number of error messages to report before interrupting the underlying computation with a tooManyErrors exception. The default is 17. If I is less than or equal to zero, infinitely many errors are acceptable.
tell(X) broadcasts the message X to all registered listeners.
startBatch() resets internal state (in particular, the error count).
startPhase(+V) broadcasts an info(...) message to all registered listeners, to the effect that phase V has started.
startSubPhase(+V) broadcasts an info(...) message to all registered listeners, to the effect that sub-phase V has started.
endBatch(+A) broadcasts messages to all registered listeners about the outcome of the underlying computation. A can be one of accepted, rejected, aborted, crashed, or interrupted. For any but accepted or interrupted, an attention message is broadcast. Causes an info(...) message to be broadcast.
error(coord: +Coord <= unit
kind: +KindV <= unit
msg: +MsgV <= unit
items: +Ts <= unit
abort: +B <= true) broadcasts a message(error(...) ...). Raises tooManyErrors if the maximum allowed error count is exceeded.
warn(coord: +Coord <= unit
kind: +KindV <= unit
msg: +MsgV <= unit
items: +Ts <= unit) broadcasts a message(warn(...) ...).
hasSeenError(?B) returns true iff an error message has been broadcast.
Listener Module The Listener module, located at x-oz://system/Listener, exports the class Listener.'class' with the following methods.
Methods
init(+NarratorO +ServeL) initializes a listener with a narrator and the label of a unary method. The listener creates a port, registers this with NarratorO, and creates a thread in which the ServeL method is applied to the port's stream.
close() undoes all effects of the init method: The server thread is terminated and the listener's port is unregistered.
getNarrator(?NarratorO) returns the narrator with which the listener's port is currently registered.
getPort(?Port) returns the associated port.
ErrorListener Module The ErrorListener module, located at x-oz://system/ErrorListener, exports the class ErrorListener.'class' with the following methods.
Methods
init(+NarratorO +ServeOneL <= unit ?VerboseL <= false) initializes an error listener. If ServeOneL is different from unit, it should be the label of a method of a subclass. If an unrecognized message is received from the narrator, the method is invoked with the message as its single parameter. VerboseL can be one of true (print all received messages to standard error), false (print none of the messages), and auto (print all messages if some error message is among them).
reset() is a no-op, intended to be overriden by derived classes. Invoked when a close() message is received.
setVerbosity(+L) sets the verbosity to L, which can be one of true (print all received messages to standard error), false (print none of the messages), and auto (print all messages if some error message is among them).
hasErrors(?B) returns true iff some error message was received since the last close() message.
isActive(?B) returns true iff some error or warning message has been received since the last close() message.
getVS(?V) returns the history of messages as a virtual string.
getMessages(?Xs) returns the history of messages as a list.
formatMessages(+Xs ?V) takes a list of messages Xs and returns them as a virtual string.
| << Prev | - Up - | Next >> |