# B Narrators and Listeners

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.

## B.1 The `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.

### The class `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.

### Private Narrators

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.

## B.2 The `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.

## B.3 The `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.