# The Concurrent ML Reference Manual

## The `TraceCML` structure

#### Synopsis

> `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.

#### Interface

> `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
> `

#### Description

`type trace_module`
  A trace_module is an element in a hierarchical name space, which is used to control debugging output.
`datatype trace_to`
  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.
`traceRoot`
  is the root module of the trace hierarchy
`exception NoSuchModule`
`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.
`watcher`
  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 © 1998 Bell Labs, Lucent Technologies