<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML><HEAD><TITLE>B Narrators and Listeners</TITLE><LINK href="ozdoc.css" rel="stylesheet" type="text/css"></HEAD><BODY><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node5.html#appendix.switches"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node7.html#appendix.syntax">Next >></A></TD></TR></TABLE><DIV id="appendix.narrator"><H1><A name="appendix.narrator">B Narrators and Listeners</A></H1><P> 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 <CODE>ozdoc</CODE> tool that generated this documentation). </P><P> A <EM>narrator</EM>, presented in <A href="node6.html#appendix.narrator.narrator">Section B.1</A>, is a producer of status and error messages. Conversely, a <EM>Listener</EM>, presented in <A href="node6.html#appendix.narrator.listener">Section B.2</A>, 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). </P><P> 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 <EM>error listener</EM> provides easy access to precisely that information, and is presented in <A href="node6.html#appendix.narrator.errorlistener">Section B.3</A>. </P><DIV id="appendix.narrator.narrator"><H2><A name="appendix.narrator.narrator">B.1 The <CODE>Narrator</CODE> Module</A></H2><P> The <CODE>Narrator</CODE> module, located at <CODE>x-oz://system/Narrator</CODE>, exports a class <CODE>Narrator<SPAN class="keyword">.</SPAN><SPAN class="string">'class'</SPAN></CODE> 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 <EM>private narrator</EM> instance, used by the running computation to send well-defined status messages. Both of these classes are described in the following. </P><DIV class="unnumbered"><H3><A name="label29">The class <CODE>Narrator<SPAN class="keyword">.</SPAN><SPAN class="string">'class'</SPAN></CODE></A></H3><DIV class="apropos"><P class="margin">Methods</P><P> </P><DL><DT><CODE>init(</CODE><CODE>?<I>PrivateNarratorO</I></CODE><CODE>)</CODE> </DT><DD><P>initializes a narrator that initially has no listeners attached, and returns the corresponding private narrator. </P></DD><DT><CODE>register(</CODE><CODE>+<I>Port</I></CODE><CODE>)</CODE> </DT><DD><P>registers a new listener <I>Port</I>. All subsequently told messages will be forwarded to <I>Port</I>. </P></DD><DT><CODE>newListener(</CODE><CODE>+<I>Port</I></CODE><CODE>)</CODE> </DT><DD><P>is invoked on every new listener <I>Port</I> 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). </P></DD><DT><CODE>unregister(</CODE><CODE>+<I>Port</I></CODE><CODE>)</CODE> </DT><DD><P>unregisters a listener <I>Port</I>. No more messages will subsequently be forwarded to <I>Port</I>. </P></DD><DT><CODE>tell(</CODE><CODE><I>X</I></CODE><CODE>)</CODE> </DT><DD><P>broadcasts the message <I>X</I> to all registered listeners. </P></DD></DL><P> </P></DIV></DIV><DIV class="unnumbered"><H3><A name="label30">Private Narrators</A></H3><DIV class="apropos"><P class="margin">Methods</P><P> </P><DL><DT><CODE>setLogPhases(</CODE><CODE>+<I>B</I></CODE><CODE>)</CODE> </DT><DD><P>determines whether messages about phases of the underlying computations should be broadcasted to listeners (if <I>B</I> is <CODE><SPAN class="keyword">true</SPAN></CODE>) or not (if <I>B</I> is <CODE><SPAN class="keyword">false</SPAN></CODE>). The default is <CODE><SPAN class="keyword">false</SPAN></CODE>. </P></DD><DT><CODE>setMaxNumberOfErrors(</CODE><CODE>+<I>I</I></CODE><CODE>)</CODE> </DT><DD><P>sets the number of error messages to report before interrupting the underlying computation with a <CODE>tooManyErrors</CODE> exception. The default is <CODE>17</CODE>. If <I>I</I> is less than or equal to zero, infinitely many errors are acceptable. </P></DD><DT><CODE>tell(</CODE><CODE><I>X</I></CODE><CODE>)</CODE> </DT><DD><P>broadcasts the message <I>X</I> to all registered listeners. </P></DD><DT><CODE>startBatch()</CODE> </DT><DD><P>resets internal state (in particular, the error count). </P></DD><DT><CODE>startPhase(</CODE><CODE>+<I>V</I></CODE><CODE>)</CODE> </DT><DD><P>broadcasts an <CODE>info(<SPAN class="keyword">...</SPAN>)</CODE> message to all registered listeners, to the effect that phase <CODE>V</CODE> has started. </P></DD><DT><CODE>startSubPhase(</CODE><CODE>+<I>V</I></CODE><CODE>)</CODE> </DT><DD><P>broadcasts an <CODE>info(<SPAN class="keyword">...</SPAN>)</CODE> message to all registered listeners, to the effect that sub-phase <CODE>V</CODE> has started. </P></DD><DT><CODE>endBatch(</CODE><CODE>+<I>A</I></CODE><CODE>)</CODE> </DT><DD><P>broadcasts messages to all registered listeners about the outcome of the underlying computation. <I>A</I> can be one of <CODE>accepted</CODE>, <CODE>rejected</CODE>, <CODE>aborted</CODE>, <CODE>crashed</CODE>, or <CODE>interrupted</CODE>. For any but <CODE>accepted</CODE> or <CODE>interrupted</CODE>, an <CODE>attention</CODE> message is broadcast. Causes an <CODE>info(<SPAN class="keyword">...</SPAN>)</CODE> message to be broadcast. </P></DD><DT><CODE>error(coord: </CODE><CODE>+<I>Coord</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">unit</SPAN> <BR> kind: </CODE><CODE>+<I>KindV</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">unit</SPAN> <BR> msg: </CODE><CODE>+<I>MsgV</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">unit</SPAN> <BR> items: </CODE><CODE>+<I>Ts</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">unit</SPAN> <BR> abort: </CODE><CODE>+<I>B</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">true</SPAN>)</CODE> </DT><DD><P>broadcasts a <CODE>message(error(<SPAN class="keyword">...</SPAN>) <SPAN class="keyword">...</SPAN>)</CODE>. Raises <CODE>tooManyErrors</CODE> if the maximum allowed error count is exceeded. </P></DD><DT><CODE>warn(coord: </CODE><CODE>+<I>Coord</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">unit</SPAN> <BR> kind: </CODE><CODE>+<I>KindV</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">unit</SPAN> <BR> msg: </CODE><CODE>+<I>MsgV</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">unit</SPAN> <BR> items: </CODE><CODE>+<I>Ts</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">unit</SPAN>)</CODE> </DT><DD><P>broadcasts a <CODE>message(warn(<SPAN class="keyword">...</SPAN>) <SPAN class="keyword">...</SPAN>)</CODE>. </P></DD><DT><CODE>hasSeenError(</CODE><CODE>?<I>B</I></CODE><CODE>)</CODE> </DT><DD><P>returns <CODE><SPAN class="keyword">true</SPAN></CODE> iff an error message has been broadcast. </P></DD></DL><P> </P></DIV></DIV></DIV><DIV id="appendix.narrator.listener"><H2><A name="appendix.narrator.listener">B.2 The <CODE>Listener</CODE> Module</A></H2><P> The <CODE>Listener</CODE> module, located at <CODE>x-oz://system/Listener</CODE>, exports the class <CODE>Listener<SPAN class="keyword">.</SPAN><SPAN class="string">'class'</SPAN></CODE> with the following methods. </P><DIV class="apropos"><P class="margin">Methods</P><P> </P><DL><DT><CODE>init(</CODE><CODE>+<I>NarratorO</I></CODE><CODE> </CODE><CODE>+<I>ServeL</I></CODE><CODE>)</CODE> </DT><DD><P>initializes a listener with a narrator and the label of a unary method. The listener creates a port, registers this with <CODE><I>NarratorO</I></CODE>, and creates a thread in which the <CODE><I>ServeL</I></CODE> method is applied to the port's stream. </P></DD><DT><CODE>close()</CODE> </DT><DD><P>undoes all effects of the <CODE>init</CODE> method: The server thread is terminated and the listener's port is unregistered. </P></DD><DT><CODE>getNarrator(</CODE><CODE>?<I>NarratorO</I></CODE><CODE>)</CODE> </DT><DD><P>returns the narrator with which the listener's port is currently registered. </P></DD><DT><CODE>getPort(</CODE><CODE>?<I>Port</I></CODE><CODE>)</CODE> </DT><DD><P>returns the associated port. </P></DD></DL><P> </P></DIV></DIV><DIV id="appendix.narrator.errorlistener"><H2><A name="appendix.narrator.errorlistener">B.3 The <CODE>ErrorListener</CODE> Module</A></H2><P> The <CODE>ErrorListener</CODE> module, located at <CODE>x-oz://system/ErrorListener</CODE>, exports the class <CODE>ErrorListener<SPAN class="keyword">.</SPAN><SPAN class="string">'class'</SPAN></CODE> with the following methods. </P><DIV class="apropos"><P class="margin">Methods</P><P> </P><DL><DT><CODE>init(</CODE><CODE>+<I>NarratorO</I></CODE><CODE> </CODE><CODE>+<I>ServeOneL</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">unit</SPAN> </CODE><CODE>?<I>VerboseL</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">false</SPAN>)</CODE> </DT><DD><P>initializes an error listener. If <I>ServeOneL</I> is different from <CODE><SPAN class="keyword">unit</SPAN></CODE>, 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. <I>VerboseL</I> can be one of <CODE><SPAN class="keyword">true</SPAN></CODE> (print all received messages to standard error), <CODE><SPAN class="keyword">false</SPAN></CODE> (print none of the messages), and <CODE>auto</CODE> (print all messages if some error message is among them). </P></DD><DT><CODE>reset()</CODE> </DT><DD><P>is a no-op, intended to be overriden by derived classes. Invoked when a <CODE>close()</CODE> message is received. </P></DD><DT><CODE>setVerbosity(</CODE><CODE>+<I>L</I></CODE><CODE>)</CODE> </DT><DD><P>sets the verbosity to <I>L</I>, which can be one of <CODE><SPAN class="keyword">true</SPAN></CODE> (print all received messages to standard error), <CODE><SPAN class="keyword">false</SPAN></CODE> (print none of the messages), and <CODE>auto</CODE> (print all messages if some error message is among them). </P></DD><DT><CODE>hasErrors(</CODE><CODE>?<I>B</I></CODE><CODE>)</CODE> </DT><DD><P>returns <CODE><SPAN class="keyword">true</SPAN></CODE> iff some error message was received since the last <CODE>close()</CODE> message. </P></DD><DT><CODE>isActive(</CODE><CODE>?<I>B</I></CODE><CODE>)</CODE> </DT><DD><P>returns <CODE><SPAN class="keyword">true</SPAN></CODE> iff some error or warning message has been received since the last <CODE>close()</CODE> message. </P></DD><DT><CODE>getVS(</CODE><CODE>?<I>V</I></CODE><CODE>)</CODE> </DT><DD><P>returns the history of messages as a virtual string. </P></DD><DT><CODE>getMessages(</CODE><CODE>?<I>Xs</I></CODE><CODE>)</CODE> </DT><DD><P>returns the history of messages as a list. </P></DD><DT><CODE>formatMessages(</CODE><CODE>+<I>Xs</I></CODE><CODE> </CODE><CODE>?<I>V</I></CODE><CODE>)</CODE> </DT><DD><P>takes a list of messages <I>Xs</I> and returns them as a virtual string. </P></DD></DL><P></P></DIV></DIV></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node5.html#appendix.switches"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node7.html#appendix.syntax">Next >></A></TD></TR></TABLE><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~kornstae/">Leif Kornstaedt</A><BR><SPAN class="version">Version 1.4.0 (20090610)</SPAN></ADDRESS></BODY></HTML>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
bd5c3d824c3db63ffd9226c15941e6ad
>
files
>
294
