/*

Copyright (C) 1996, 1997 John W. Eaton
Copyright (C) 2007, Muthiah Annamalai

This file is part of Octave.

Octave is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.

Octave is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License
along with Octave; see the file COPYING.  If not, write to the Free
Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.

*/

#if !defined (octave_profiler_h)
#define octave_profiler_h 1

#include <ctime>

#include <string>

#include "comment-list.h"
#include "oct-obj.h"
#include "ov-fcn.h"
#include "ov-typeinfo.h"

class string_vector;

class octave_value;
class tree_parameter_list;
class tree_statement_list;
class tree_va_return_list;
class tree_walker;
class symbol_table;
class symbol_record;


//indicate type of function profiled
typedef enum { OCTAVE_FUNCTION, BUILTIN_FUNCTION, 
	       ANONYMOUS_FUNCTION, MEX_FUNCTION, 
	       NESTED_FUNCTION , ENDOF_FUNCTION_TYPES} profiler_function_type;

//indicate state of the function
typedef enum { ENTER_FUNCTION, LEAVE_FUNCTION, 
	       EXCEPTION_IN_FUNCTION, ENDOF_FUNCTION_STATES } profiler_call_state;

//indicate types of timers used
typedef enum { TIMER_REAL, TIMER_CPU, 
	       TIMER_CLOCK, ENDOF_TIMER_TYPES } profiler_timer_type; 

//signature of the profiler function               
typedef void (*profiler_function)(const octave_function *fcn, \
                                    profiler_function_type ftype, \
                                    profiler_call_state cstate);

//
// convention: octave_profiler is the object/class that does the Octave infrastructure.
// profile is the real function, that does the profiling. 
// 
// octave_profiler class is similar in spirit to the Python's sys.setprofile() OR
// Ruby's set_profile_func primitives
//

class
OCTINTERP_API
octave_profiler
{
public:

  //
  //function used from the side of call/return sites within Octave. This function
  //passes the event to the delegated 'profile_fcn' if set. If !profiling just 
  //dont do anything.
  //
  static void send_event(const octave_function *fcn, profiler_function_type ftype, profiler_call_state cstate);

  // return true on success, false on failure
  static bool set_profiler(profiler_function profile);

  // clear profiler
  static bool clear_profiler();
  
  // actual handler
  static profiler_function profile_fcn;
  
  static bool isprofiling() { return profiling; }
  
  // indicates state of the profiler (readonly)
  static bool profiling;
};

//
//The singleton class that users can derive from for creating specialized
//profiling handlers, call-graph statistics and line/block level granular 
//profilers.
//
class
profile_base
{
 //instance variables
public:  
  double time_start;
  bool has_profiled;

  virtual ~profile_base() { };

  //see if singleton instance exists
  static bool instance_ok() { return false; }
  
  //factory method for singleton instance
  static profile_base* get_profile(void) { return NULL; }

  //start profile
  static void start_profiling() { };
  
  //stop profile only. Dont cleanup, we may print results.
  static void stop_profiling() { };

  //factory cleanup instance
  static void clear_profile(void) { return; }
  
  //reply if the interface has started the functions.
  static bool has_started() { return false; }
  
  //main routine to print statistics when profiling is complete
  //need to get singleton instance & invoke the member method.
  static void profile_base::print_stats() { return; }
  
  //passes the static method call to the instance method, after obtaining a singleton
  //copy for this.
  static void profile_func(const octave_function *fcn,profiler_function_type ftype,\
                            profiler_call_state cstate)
  {
      return;
  };
  
  //compiled functions: Mex-file, Oct-file, Builtins
  //script functions: M-file, Nested functions, Anonymous functions
  
  //real workhorse function need to delegate the calls to various apartments.
  virtual void profile_dispatch_func(const octave_function *fcn, \
                                    profiler_function_type ftype, profiler_call_state cstate)=0;
  //call processing
  virtual void do_profile_script_call(const octave_function *fcn, \
                                    profiler_function_type ftype)=0;


  //return processing
  virtual void do_profile_script_return(const octave_function *fcn, \
                                    profiler_function_type ftype)=0;
  virtual void do_profile_compiled_return(const octave_function *fcn, \
                                    profiler_function_type ftype)=0;

  // exception processing
  virtual void do_profile_script_exception(const octave_function *fcn, \
                                    profiler_function_type ftype)=0;
  virtual void do_profile_compiled_exception(const octave_function *fcn, \
                                    profiler_function_type ftype)=0;
  
  //print statistics actually
  virtual void print_profile()=0;
};

#endif /* octave_profiler_h */