unison

Fork of Unison, a bi-directional file synchronization tool
git clone git://git.laack.co/unison.git
Log | Files | Refs | README | LICENSE

trace.mli (4554B)

      1 (* Unison file synchronizer: src/ubase/trace.mli *)
      2 (* Copyright 1999-2020, Benjamin C. Pierce (see COPYING for details) *)
      3 
      4 (* ---------------------------------------------------------------------- *)
      5 (* Debugging support *)
      6 
      7 (* Show a low-level debugging message.  The first argument is the
      8    name of the module from which the debugging message originates: this is
      9    used to control which messages are printing (by looking at the value of
     10    the 'debug' preference, a list of strings).  The second argument is a
     11    thunk that, if executed, should print the actual message to stderr.  Note
     12    that, since control of debugging depends on preferences, it is not possible
     13    to see debugging output generated before the preferences have been
     14    loaded. *)
     15 val debug : string -> (unit->unit) -> unit
     16 
     17 val debugmods : string list Prefs.t
     18 
     19 (* Check whether a particular debugging flag is enabled *)
     20 val enabled : string -> bool
     21 
     22 (* Enable/disable a particular flag *)
     23 val enable : string -> bool -> unit
     24 
     25 (* When running in server mode, we use this ref to know to indicate this in
     26    debugging messages *)
     27 val runningasserver : bool ref
     28 
     29 (* Tell the Trace module which local stream to use for tracing and
     30    debugging messages *)
     31 val redirect : [`Stdout | `Stderr | `FormatStdout] -> unit
     32 
     33 (* ---------------------------------------------------------------------- *)
     34 (* Tracing *)
     35 
     36 (* The function used to display a message on the machine where the
     37    user is going to see it.  The default value just prints the string
     38    on stderr.  The graphical user interface should install an
     39    appropriate function here when it starts.  In the server process, this
     40    variable's value is ignored. *)
     41 val messageDisplayer : (string -> unit) ref
     42 
     43 (* The function used to format a status message (with a major and a minor
     44    part) into a string for display.  Should be set by the user interface. *)
     45 val statusFormatter : (string -> string -> string) ref
     46 
     47 (* The internal type of messages (it is exposed because it appears in the
     48    types of the following) *)
     49 type msg
     50 
     51 val mmsg : msg Umarshal.t
     52 
     53 (* The internal routine used for formatting a message to be displayed
     54    locally.  It calls !messageDisplayer to do the actual work. *)
     55 val displayMessageLocally : msg -> unit
     56 
     57 (* This can be set to function that should be used to get messages to
     58    the machine where the user can see it, if we are running on some
     59    other machine.  (On the client machine, this variable's value is None.
     60    On the server, it should be set to something that moves the message
     61    across the network and then calls displayMessageLocally on the
     62    client.) *)
     63 val messageForwarder : (msg -> unit) option ref
     64 
     65 (* Allow outside access to the logging preference, so that the main program
     66    can turn it off by default *)
     67 val logging : bool Prefs.t
     68 
     69 (* ---------------------------------------------------------------------- *)
     70 (* Messages *)
     71 
     72 (* Suppress all message printing *)
     73 val terse
     74   : bool Prefs.t
     75 
     76 (* Show a string to the user. *)
     77 val message : string -> unit
     78 
     79 (* Show a change of "top-level" status (what phase we're in) *)
     80 val status : string -> unit
     81 
     82 (* Show a change of "detail" status (what file we're working on) *)
     83 val statusMinor : string -> unit
     84 
     85 (* Show a change of "detail" status unless we want to avoid generating
     86    too much output (e.g. because we're using the text ui) *)
     87 val statusDetail : string -> unit
     88 
     89 (* Write a message just to the log file (no extra '\n' will be added: include
     90    one explicitly if you want one) *)
     91 val log : string -> unit
     92 
     93 (* Like 'log', but strips all ANSI color escapes in the input before
     94    writing to log file. Log output to stdout and stderr will keep
     95    ANSI color escapes intact *)
     96 val log_color : string -> unit
     97 
     98 (* Like 'log', but only send message to log file and not to stderr, even when
     99    [sendLogMsgsToStderr] is set to true *)
    100 val logonly : string -> unit
    101 
    102 (* Like 'log', but only send message to log file if -terse preference is set *)
    103 val logverbose : string -> unit
    104 
    105 (* When set to true (default), log messages will also be printed to stderr *)
    106 val sendLogMsgsToStderr : bool ref
    107 
    108 (* ---------------------------------------------------------------------- *)
    109 (* Timers (for performance measurements during development) *)
    110 
    111 type timer
    112 
    113 (* Create a new timer, print a description, and start it ticking *)
    114 val startTimer : string -> timer
    115 
    116 (* Create a new timer without printing a description *)
    117 val startTimerQuietly : string -> timer
    118 
    119 (* Display the current time on a timer (and its description) *)
    120 val showTimer : timer -> unit