/** @file psTrace.h
 *  \brief basic run-time trace facilities
 *  \ingroup LogTrace
 *
 *  This file will hold the prototypes for defining procedures to insert
 *  trace messages into the code.
 *
 *  @author Robert Lupton, Princeton University
 *  @author GLG, MHPCC
 *
 *  @version $Revision: 1.31 $ $Name:  $
 *  @date $Date: 2005/02/17 19:26:24 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */
#if !defined(PS_TRACE_H)
#define PS_TRACE_H 1

#define PS_UNKNOWN_TRACE_LEVEL -9999   // we don't know this name's level
#define PS_DEFAULT_TRACE_LEVEL -1
#define PS_THE_OTHER_DEFAULT_TRACE_LEVEL 0

/** \addtogroup LogTrace
 *  \{
 */

/** Functions **************************************************************/

//#define PS_NO_TRACE 1   ///< to turn off all tracing

// XXX EAM : the old 'empty' values of (void) 0 are dangerous
# if defined(PS_NO_TRACE)
#   define psTrace(facil, level, ...)   /* do nothing */
#   define p_psTrace(facil, level, ...) /* do nothing */
#   define psTraceSetLevel(facil,level) /* do nothing */
#   define psTraceGetLevel(facil)       /* do nothing */
#   define psTraceReset()               /* do nothing */
#   define psTraceFree()                /* do nothing */
#   define psTracePrintLevels()         /* do nothing */
#   define psTraceSetDestination(fp)    /* do nothing */
#   define psTraceSetDestination()      /* do nothing */
#   define PS_TRACE_ON 0

# else /* PS_NO_TRACE */
#   define PS_TRACE_ON 1

/** Basic structure for the component tree.  A component is a string of the
    form aaa.bbb.ccc, and may itself contain further subcomponents.  The
    Component structure doesn't in fact contain it's full name, but only the
    last part. */
typedef struct p_psComponent
{
    const char *name;			// last part of name of component
    psS32 level;			// trace level for this component
    bool p_psSpecified;
    psS32 n;				// number of subcomponents
    struct p_psComponent* *subcomp;     // next level of subcomponents
}
p_psComponent;

#ifdef DOXYGEN
void psTrace(const char *facil,        ///< facilty of interest
             psS32 myLevel,            ///< desired trace level
             ...)                      ///< trace message arguments
;
#else
/// Send a trace message
void p_psTrace(const char *facil,      ///< facilty of interest
               psS32 myLevel,          ///< desired trace level
               ...)                    ///< trace message arguments
;

#ifndef SWIG
#define psTrace(facil, level, ...) p_psTrace(facil, level, __VA_ARGS__)
#endif /* SWIG */

#endif /* DOXYGEN */

/// Set trace level
psBool psTraceSetLevel(const char *facil,     ///< facilty of interest
                       psS32 level)     ///< desired trace level
;

/// Get the trace level
psS32 psTraceGetLevel(const char *facil) ///< facilty of interest
;

/// Set all trace levels to zero (do not free nodes in the component tree).
void psTraceReset();

/// print trace levels
void psTracePrintLevels(void);

/// Set the destination of future trace messages.
void psTraceSetDestination(FILE * fp);

/// Get the current destination for trace messages.
FILE *psTraceGetDestination(void);

/* \} */// End of SystemGroup Functions

#endif /* PS_NO_TRACE */

#endif /* PS_TRACE_H */