The Concurrent ML Reference Manual

The TraceCML structure


signature  TRACE_CML
structure TraceCML : TRACE_CML

The TraceCML structure provides rudimentary debugging support in the form of mechanisms to control debugging output, and to monitor thread termination. This version of this module is adapted from Cliff Krumvieda's utility for tracing CML programs. It provides three facilities: trace modules, for controlling debugging output; thread watching, for detecting thread termination; and a mechanism for reporting uncaught exceptions on a per thread basis.

Trace modules provide a hierarchical name space, which is used to control the granularity of debugging output. The trace module operations have been implemented in such a way that they can be invoked independent of whether CML is currently running. This allows the trace hierarchy to be setup statically.

The TraceCML also provides hooks to detect unexpected termination of threads. Support is provided to watch for a thread's termination (useful for monitoring servers that are never supposed to terminate). Hooks are also provided to specify the action taken when a thread terminates because of an uncaught exception.


type trace_module
datatype trace_to
  = TraceToOut
  | TraceToErr
  | TraceToNull
  | TraceToFile of string
  | TraceToStream of TextIO.outstream
val setTraceFile : trace_to -> unit
val traceRoot : trace_module
exception NoSuchModule
val traceModule : trace_module * string -> trace_module
val nameOf : trace_module -> string
val moduleOf : string -> trace_module
val traceOn : trace_module -> unit
val traceOff : trace_module -> unit
val traceOnly : trace_module -> unit
val amTracing : trace_module -> bool
val status : trace_module -> (trace_module * bool) list
val trace : trace_module * (unit -> string list) -> unit
val watcher : trace_module
val watch : string * CML.thread_id -> unit
val unwatch : CML.thread_id -> unit
val setUncaughtFn : (CML.thread_id * exn -> unit) -> unit
val setHandleFn : (CML.thread_id * exn -> bool) -> unit
val resetUncaughtFn : unit -> unit


type trace_module
A trace_module is an element in a hierarchical name space, which is used to control debugging output.

datatype trace_to
  = TraceToOut
  | TraceToErr
  | TraceToNull
  | TraceToFile of string
  | TraceToStream of TextIO.outstream
The various destinations of trace output.

setTraceFile tt
Direct the destination of trace output. Note: TraceToStream can only be specified as a destination if CML is running.

is the root module of the trace hierarchy

traceModule (tm, s)
creates a new trace module that is a child of tm and has the label s. If such a module exists, it just returns the existing module.

nameOf tm
returns the full name of the module tm.

moduleOf name
returns the trace module named by name. Trace module names are written in the style of Unix pathnames (e.g., using "/" as a separator).

traceOn tm
turns tracing on for moduel tm and its descendents.

traceOff tm
turns tracing off for moduel tm and its descendents.

traceOnly tm
turn tracing on for module tm, but not for its descendents.

amTracing tm
returns true if tracing is enabled for module tm.

status tm
returns a pre-order list of the modules rooted at tm, along with their status (enabled or disabled).

trace (tm, f)
explain the use and semantics of trace HERE.

is a trace module that is used to control the printing of thread termination messages. Its name is "/ThreadWatcher/", and by default it is enabled.

watch (name, tid)
watch the thread named by tid for unexpected termination. If the thread terminates, then a trace message is generated (see watcher). The string name is used to identify the thread in the termination message.

unwatch tid
stop watching the thread named by tid.

setUncaughtFn f
sets the default uncaught exception action to f.

setHandleFn f
adds the function f as an additional uncaught exception action. If the action returns true, then no further action is taken. This can be used to handle application specific exceptions.

resetUncaughtFn ()
resets the default uncaught exception action to the system default, and removes any layered actions.

[ Top | Parent | Contents | Index | Root ]

Last Modified &date;
Comments to John Reppy.
Copyright © 1991-2003 John Reppy