lib/cml/cml-lib/trace-cml.sig

   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