// file: $isip/class/search/Trace/Trace.h
// version: $Id: Trace.h 9347 2003-11-26 20:46:15Z alphonso $
//

// make sure definitions are only made once
//
#ifndef ISIP_TRACE
#define ISIP_TRACE

// isip include files
//
#ifndef ISIP_ULONG
#include <Ulong.h>
#endif

#ifndef ISIP_FLOAT
#include <Float.h>
#endif
       
#ifndef ISIP_SINGLE_LINKED_LIST
#include <SingleLinkedList.h>
#endif

#ifndef ISIP_MEMORY_MANAGER
#include <MemoryManager.h>
#endif

#ifndef ISIP_BI_GRAPH
#include <BiGraph.h>
#endif

#ifndef ISIP_HASH_KEY
#include <HashKey.h>
#endif

#ifndef ISIP_HISTORY
#include <History.h>
#endif

#ifndef ISIP_BIGRAPH_VERTEX
#include <BiGraphVertex.h>
#endif

#ifndef ISIP_TRAIN_NODE
#include <TrainNode.h>
#endif

#ifndef ISIP_SYMBOL_GRAPH_NODE
#include <SymbolGraphNode.h>
#endif

// forward class definitions
//
class Context;
class History;
class TrainNode;

// Trace: the fundamental place holder in a recognition system. it
// keeps track of the paths through the search space as well as
// hypothesis scores.
//
class Trace {

  //---------------------------------------------------------------------------
  //
  // public constants
  //
  //---------------------------------------------------------------------------
public:

  // define the class name
  //
  static const String CLASS_NAME;

  //----------------------------------------
  //
  // i/o related constants
  //
  //----------------------------------------  

  static const String PARAM_SCORE;
  
  //----------------------------------------
  //
  // other important constants
  //
  //----------------------------------------  

  // define the trace mode choices
  //
  enum TRACE_MODE { DECODE = 0, TRAIN, DEF_TRACE_MODE = DECODE };

  // define the inactive likelihood score
  //  
  static const float32 INACTIVE_SCORE = -11111111111111.0f;
  
  //----------------------------------------
  //
  // default values and arguments
  //
  //----------------------------------------  

  // define the default value(s) of the class data
  //
  static const float32 DEF_SCORE = 0.0;
  static const ulong DEF_FRAME = 0;
  static const ulong DEF_COUNT = 0;
  static const ulong DEF_NSYMBOL_LENGTH = 0;
  
  // define default arguments to methods
  //
  static const ulong DEF_REF_INCR = 1;
  static const ulong DEF_REF_DECR = 1;  

  //---------------------------------------
  //
  // error codes
  //
  //---------------------------------------

  static const int32 ERR = (int32)900000;
  static const int32 READ = (int32)90001;  

  //---------------------------------------------------------------------------
  //
  // protected data
  //
  //---------------------------------------------------------------------------
protected:

  // define a trace mode flag
  //
  TRACE_MODE trace_mode_d;

  // define a structure to maintain the previous n-symbols
  //
  Context** nsymbol_d;
  
  // define a back pointer to the previous trace(s)
  //
  Trace* back_ptr_d;

  // define a structure to maintain the trace's location in the search space
  //
  History* history_d;

  // define the symbol and surrounding context that the trace is at
  //
  Context* symbol_d;

  // define the reference to the symbol graph node
  //
  SymbolGraphNode* symbol_node_d;

  // define the score for the path in the search space that this trace
  // represents
  //
  float32 score_d;

  // define the lm score for the path in the search space that this trace
  // represents
  //
  float32 lm_score_d;  

  // the time frame that this trace is in
  //
  ulong frame_d;
  
  // define a reference count that says when this trace can be deleted
  //
  ulong reference_count_d;

  // define a reference pointer to a search node used during training
  //
  BiGraphVertex<TrainNode>* reference_vertex_d;

  // define the static nsymbol length
  //
  static Ulong nsymbol_length_d;
  
  // define a static debug level
  //
  static Integral::DEBUG debug_level_d;

  // memory manager
  //
  static MemoryManager mgr_d;
  
  //---------------------------------------------------------------------------
  //
  // required public methods
  //
  //---------------------------------------------------------------------------
public:

  // method: name
  //
  static const String& name() {
    return CLASS_NAME;
  }

  // other static methods
  //
  static bool8 diagnose(Integral::DEBUG debug_level);

  // debug methods:
  //
  bool8 debug(const unichar* message) const;

  // method: setDebug
  //
  static bool8 setDebug(Integral::DEBUG debug_level) {
    debug_level_d = debug_level;
    return true;
  }
  
  // destructor/constructor(s)
  //
  ~Trace();

  // method: default constructor
  //
  Trace(float32 score = DEF_SCORE) {

    if (debug_level_d >= Integral::ALL) { 
      fprintf(stdout, "Constructor of trace: %p\n", this);
      fflush(stdout);
    }

    nsymbol_d = (Context**)NULL;
    back_ptr_d = (Trace*)NULL;
    frame_d = DEF_FRAME;
    reference_count_d = DEF_COUNT;
    trace_mode_d = DEF_TRACE_MODE;
    history_d = (History*)NULL;
    symbol_d = (Context*)NULL;
    symbol_node_d = (SymbolGraphNode*)NULL;    
    reference_vertex_d = (BiGraphVertex<TrainNode>*)NULL;

    setScore(score);
  }

  // method: copy constructor
  //
  Trace(const Trace& copy_trace) {

    if (debug_level_d >= Integral::ALL) { 
      fprintf(stdout, "Constructor of trace\n: %p", this);
      fflush(stdout);
    }

    nsymbol_d = (Context**)NULL;    
    back_ptr_d = (Trace*)NULL;    
    frame_d = DEF_FRAME;   
    reference_count_d = DEF_COUNT;
    trace_mode_d = DEF_TRACE_MODE;   
    score_d = DEF_SCORE;
    lm_score_d = DEF_SCORE;    
    history_d = (History*)NULL;
    symbol_d = (Context*)NULL;
    symbol_node_d = (SymbolGraphNode*)NULL;    
    reference_vertex_d = (BiGraphVertex<TrainNode>*)NULL;
    
    assign(copy_trace);
  }
  
  // assign methods
  //
  bool8 assign(const Trace& copy_trace);

  // method: sofSize
  //
  int32 sofSize() const {
    return Error::handle(name(), L"sofSize", Error::ARG, __FILE__, __LINE__);
  }
  
  // method: read
  //
  bool8 read(Sof& sof, int32 tag, const String& cname = CLASS_NAME) {
    return Error::handle(name(), L"read", Error::ARG, __FILE__, __LINE__);
  }

  // method: write
  //
  bool8 write(Sof& sof, int32 tag, const String& cname = CLASS_NAME) const {
    return Error::handle(name(), L"write", Error::ARG, __FILE__, __LINE__);
  }

  // method: readData
  //
  bool8 readData(Sof& sof, const String& pname = String::EMPTY,
		   int32 size = SofParser::FULL_OBJECT,
		   bool8 param = true,
                   bool8 nested = false) {
    return Error::handle(name(), L"readData", Error::ARG, __FILE__, __LINE__);
  }

  // method: writeData
  //
  bool8 writeData(Sof& sof, const String& pname = String::EMPTY) const {
    return Error::handle(name(), L"writeData", Error::ARG, __FILE__, __LINE__);
  }

  // eq methods
  //
  bool8 eq(const Trace& compare_trace) const;

  // method: operator <
  //
  bool8 operator < (const Trace& trace_a) {
    return (score_d < trace_a.score_d);
  }

  // method: operator >
  //
  bool8 operator > (const Trace& trace_a) {
    return (score_d > trace_a.score_d);
  }

  // method: lt
  //
  bool8 lt(Trace& trace_a) const {
    return (score_d < trace_a.score_d);
  }

  // method: gt
  //
  bool8 gt(Trace& trace_a) const {
    return (score_d > trace_a.score_d);
  }
  
  // method: new
  //
  static void* operator new(size_t size) {
    return mgr_d.get();
  }

  // method: new[]
  //
  static void* operator new[](size_t size) {
    return mgr_d.getBlock(size);
  }

  // method: delete
  //
  static void operator delete(void* ptr) {
    mgr_d.release(ptr);
  }

  // method: delete[]
  //
  static void operator delete[](void* ptr) {
    mgr_d.releaseBlock(ptr);
  }

  // method: setGrowSize
  //
  static bool8 setGrowSize(int32 grow_size) {
    return mgr_d.setGrow(grow_size);
  }

  // clear methods
  //
  bool8 clear(Integral::CMODE cmode = Integral::DEF_CMODE);

  //---------------------------------------------------------------------------
  //
  // class-specific public methods
  //
  //---------------------------------------------------------------------------

  // method: setTraceMode
  //
  bool8 setTraceMode(TRACE_MODE arg) {
    trace_mode_d = arg;
    return true;
  }

  // method: getTraceMode
  //
  TRACE_MODE getTraceMode() {
    return trace_mode_d;
  }
  
  // method: setScore
  //
  bool8 setScore(float32 score) {
    score_d = score;
    return true;
  }

  // method: getScore
  //
  float32 getScore() const {
    return score_d;
  }
  
  // method: setLMScore
  //
  bool8 setLMScore(float32 score) {
    lm_score_d = score;
    return true;
  }

  // method: getLMScore
  //
  float32 getLMScore() const {
    return lm_score_d;
  }
  
  // method: getNSymbol
  //
  Context**& getNSymbol() {
    return (Context**&)nsymbol_d;
  }

  // method: setNSymbol
  //
  bool8 setNSymbol(Context**& arg) {
    return (nsymbol_d = arg);
  }

  // method: getSymbolNode
  //
  SymbolGraphNode* getSymbolNode() {
    return symbol_node_d;
  }

  // method: setSymbolNode
  //
  bool8 setSymbolNode(SymbolGraphNode* arg) {
    return (symbol_node_d = arg);
  }  

  // history methods
  //
  bool8 setHistory(const History* arg);
  History* getHistory() const;

  // symbol methods
  //
  bool8 setSymbol(const Context* arg);
  Context* getSymbol() const;
  
  // back pointer methods
  //
  bool8 setBackPointer(Trace* back_ptr);

  // method: getBackPointer
  //
  Trace* getBackPointer() const {
    return back_ptr_d;
  }
  
  // other reference counting methods
  //
  ulong decrementRefCount(ulong decrement = DEF_REF_DECR);  

  // method: incrementRefCount
  //
  ulong incrementRefCount(ulong increment = DEF_REF_INCR) {
    return (reference_count_d += increment);
  }
  
  // method: getReference
  //
  BiGraphVertex<TrainNode>* getReference() const {
    return reference_vertex_d;
  }

  // method: setReference
  //
  bool8 setReference(BiGraphVertex<TrainNode>* vertex) {
    reference_vertex_d = vertex;
    return true;
  }
  
  // method: getRefCount
  //
  ulong getRefCount() const {
    return reference_count_d;
  }

  // method: setRefCount
  //
  bool8 setRefCount(ulong count) {
    reference_count_d = count;
    return true;
  }

  // method: setFrame
  //
  bool8 setFrame(ulong frame) {
    frame_d = frame;
    return true;
  }

  // method: getFrame
  //
  ulong getFrame() const {
    return frame_d;
  }

  // trace activity methods
  //
  bool8 setActive(bool8 is_active);

  // method: isActive
  //
  bool8 isActive() const {
    return (score_d != INACTIVE_SCORE);
  }

  // method: getNSymbolLength
  //
  static ulong getNSymbolLength() {
    return nsymbol_length_d;
  }
  
  // method: setNSymbolLength
  //
  static bool8 setNSymbolLength(ulong arg) {
    return (nsymbol_length_d = arg);
  }
  
  // trace deletion methods
  //
  static bool8 deleteTrace(Trace* in_trace, bool8 is_recursive,
		bool8 clean_search_node = false);
  
  // hash function
  //
  int32 hash(int32 capacity) const;
  
  //---------------------------------------------------------------------------
  //
  // private methods
  //
  //---------------------------------------------------------------------------
private:

};

// include the context class here circumvent the circular dependency
//
#ifndef ISIP_CONTEXT
#include <Context.h>
#endif

// end of include file
//
#endif