Commit | Line | Data |
---|---|---|
7f918cf1 CE |
1 | (* trace-cml-sig.sml |
2 | * | |
3 | * COPYRIGHT (c) 1992 AT&T Bell Laboratories | |
4 | * | |
5 | * This module provides rudimentary debugging support in the form of mechanisms | |
6 | * to control debugging output, and to monitor thread termination. This | |
7 | * version of this module is adapted from Cliff Krumvieda's utility for tracing | |
8 | * CML programs. It provides three facilities: trace modules, for controlling | |
9 | * debugging output; thread watching, for detecting thread termination; and | |
10 | * a mechanism for reporting uncaught exceptions on a per thread basis. | |
11 | *) | |
12 | ||
13 | signature TRACE_CML = | |
14 | sig | |
15 | ||
16 | (** Trace modules ** | |
17 | * | |
18 | * The basic idea is that one defines a heirarchy of ``trace | |
19 | * modules,'' which provide valves for debugging output. | |
20 | *) | |
21 | ||
22 | type trace_module | |
23 | ||
24 | (* where to direct trace output to *) | |
25 | datatype trace_to | |
26 | = TraceToOut | |
27 | | TraceToErr | |
28 | | TraceToNull | |
29 | | TraceToFile of string | |
30 | | TraceToStream of TextIO.outstream | |
31 | ||
32 | val setTraceFile : trace_to -> unit | |
33 | (* Direct the destination of trace output. Note: TraceToStream | |
34 | * can only be specified as a destination if CML is running. | |
35 | *) | |
36 | ||
37 | val traceRoot : trace_module | |
38 | (* the root module of the trace hierarchy *) | |
39 | ||
40 | exception NoSuchModule | |
41 | ||
42 | val traceModule : (trace_module * string) -> trace_module | |
43 | val nameOf : trace_module -> string | |
44 | (* return the name of the module *) | |
45 | val moduleOf : string -> trace_module | |
46 | (* return the module specified by the given string, or raise | |
47 | * NoSuchModule if none exists. | |
48 | *) | |
49 | ||
50 | val traceOn : trace_module -> unit | |
51 | (* turn tracing on for a module and its descendents *) | |
52 | val traceOff : trace_module -> unit | |
53 | (* turn tracing off for a module and its descendents *) | |
54 | val traceOnly : trace_module -> unit | |
55 | (* turn tracing on for a module (but not for its descendents) *) | |
56 | val amTracing : trace_module -> bool | |
57 | (* return true if this module is being traced *) | |
58 | ||
59 | val status : trace_module -> (trace_module * bool) list | |
60 | (* return a list of the registered modules dominated by the given | |
61 | * module, and their status. | |
62 | *) | |
63 | ||
64 | val trace : (trace_module * (unit -> string list)) -> unit | |
65 | (* conditionally generate tracing output *) | |
66 | ||
67 | ||
68 | (** Thread watching **) | |
69 | ||
70 | val watcher : trace_module | |
71 | (* controls printing of thread watching messages; the module's name | |
72 | * is "/ThreadWatcher/" | |
73 | *) | |
74 | val watch : (string * CML.thread_id) -> unit | |
75 | (* watch the given thread for unexpected termination *) | |
76 | val unwatch : CML.thread_id -> unit | |
77 | (* stop watching the named thread *) | |
78 | ||
79 | (** Uncaught exception handling **) | |
80 | ||
81 | val setUncaughtFn : ((CML.thread_id * exn) -> unit) -> unit | |
82 | (* this sets the default uncaught exception action. *) | |
83 | val setHandleFn : ((CML.thread_id * exn) -> bool) -> unit | |
84 | (* add an additional uncaught exception action. If the action returns | |
85 | * true, then no further action is taken. This can be used to handle | |
86 | * application specific exceptions. | |
87 | *) | |
88 | val resetUncaughtFn : unit -> unit | |
89 | (* this resets the default uncaught exception action to the system default, | |
90 | * and removes any layered actions. | |
91 | *) | |
92 | ||
93 | end; (* TRACE_CML *) | |
94 |