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

traceRoot: 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.

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 ]

The Concurrent ML Reference Manual

The TraceCML structure

Synopsis

Interface

Description

The `TraceCML` structure