(***********************************************************************)
(*                                                                     *)
(*                                 GALAX                               *)
(*                           XML Query Engine                          *)
(*                                                                     *)
(*  Copyright 2000, Lucent Technologies.                               *)
(*  Distributed only by permission.                                    *)
(*                                                                     *)
(***********************************************************************)

(* $Id: monitor.mli,v 1.4 2002/11/15 05:29:23 simeon Exp $ *)

(* This module is used for monitoring the activity of Galax. *)

(* Note:
     This module works in a push-pop fashion. A processing phase is
     pushed when it is started, and popped when it
     finishes. Monitoring action (typically recording of CPU time and
     memory allocation can be recorded whenever an action is
     performed.

     The push-pop model allows to nest processing phases. For
     instance, one can monitor the CPU time of individual expressions
     within the evaluation phase.
   - Jerome
 *)

(**********************)
(* General statistics *)
(**********************)

type stats_item =
    { glx_total_memory : float;
      glx_live_memory : float;
      glx_time : float }

type stats_point =
    { relative_stats : stats_item;
      absolute_stats : stats_item }

val new_stats_point : unit -> stats_point

val fprintf_memory : Format.formatter -> float -> unit

(* Type that represents various processing phases within the system *)

type phase =
  | Query_Toplevel_Phase
      (* [Toplevel Phase] Galax toplevel processing, this mostly
         performs administrative tasks and passing of information
         between actual processing phases. Cost of this phase should
         be mostly negligible. *)
  | Query_Processing_Context
      (* [Processing Context] This is the phase during which Galax is
         processing the XQuery context, mostly it is dealing with the
         query prolog (including typing, and evaluation). *)
  | Query_Processing_Expr of Xquery_ast.expr
      (* [Processing expression E1] This is the phase during which
         expression E1 is processed (including typing, and
         evaluation). *)
  | Query_Parsing_Phase
      (* [Query Parsing] This is the phase during which Galax is
         parsing the query. *)
  | Query_Normalization_Phase
      (* [Normalization] This is the phase during which Galax is
         normalizing the query to the core. *)
  | Query_Static_Typing_Phase
      (* [Static Type Analysis] This is a phase during which Galax is
         performing static typing. *)
  | Query_Optimization_Phase
      (* [Optimization] This is a phase during which Galax is
         doing XQuery simplification. *)
  | Query_Path_Analysis_Phase
      (* [Path Projection Analysis] This is a phase during which Galax
         is performing static path analysis. *)
  | Query_Evaluation_Phase
      (* [Evaluation] This is a phase during which Galax is doing
         query evaluation. *)
  | Query_Serialization_Phase
      (* [Serialization] This is a phase during which Galax is
         serializing the result. *)
  | Document_Parsing_Phase of AnyURI._uri
      (* [Document parsing] This is a phase during which Galax is
         parsing an input document. *)
  | Document_Loading_Phase of AnyURI._uri
      (* [Document loading] This is a phase during which Galax is
         loading an input document into the XQuery data model. *)
  | Document_ParsingLoading_Phase of AnyURI._uri
      (* [Document parsing&loading] In the case where SAX is used, it
         is not so easy to separate parsing from loading, which is
         done in a streaming fashion. This is a phase during which
         Galax is both parsing and loading simultaneously. *)
  | Expression_Phase of Xquery_astutil.cexpr_kind
      (* [Expression expr] This is a phase during which Galax is doing
         processing local processing for a given sub-expression. This
         allows to monitor activity on an expression per expression
         basis. *)

(*************************)
(* Data model statistics *)
(*************************)

type dm_stats =
    { mutable node_count : int }

val current_stats : dm_stats


(***********************)
(* Activity monitoring *)
(***********************)

val init_monitor : unit -> unit

val close_monitor : unit -> unit

val push_phase : phase -> unit

val pop_phase : unit -> unit

(*
val push_cexpr_kind : cexpr_kind -> unit

val pop_cexpr_kind : unit -> cexpr_kind

*)


(***********************)
(* Monitoring wrappers *)
(***********************)

val wrap_monitor : phase -> ('a -> 'b) -> 'a -> 'b

