DebugOutput.hpp

Go to the documentation of this file.

#ifndef moab_DEBUG_OUTPUT_HPP
#define moab_DEBUG_OUTPUT_HPP

#include <cstdarg>
#include <cstdio>
#include <vector>
#include <iosfwd>
#include <string>

#include "moab/Compiler.hpp"
#include "moab/CpuTimer.hpp"

namespace moab
{

class Range;
class DebugOutputStream;

/**\brief Utility class for printing debug output
 *
 * This class implements line-oriented output.  That is, it buffers
 * output data until a newline is encountered, at which point it
 * sends the output to the output stream followed by an explicit
 * flush, and optionally prefixed with the MPI rank.
 *
 * This class also implements a verbosity filter for all output.
 * The class instance has a verbosity limit.  Each request
 * for output has an associated verbosity level.  If the verbosity
 * level for the output is is less greater than the limit then
 * the output is discarded.  By convetion a verbosity limit
 * of zero should indicate no output. Therefore all requests
 * for output should have an associated verbosity level greater
 * than or equal to one.
 *
 * \Note Any output not terminated with an newline character or
 *       followed by later output containing a newline character
 *       will not be flushed until the destructor is invoked.
 * \Note C++-style IO (i.e. std::ostream) is not supported because
 *       it is necessarily inefficient for debug-type output.  All
 *       formatting (e.g. converting arguments to strings, etc.) must
 *       be done even when output is disabled.
 */
class DebugOutput
{

  public:
    /**
     *\param str       Output stream to which to flush output
     *\param verbosity Verbosity limit.
     */
    DebugOutput( DebugOutputStream* str, unsigned verbosity = 0 );
    /**
     *\param str       Output stream to which to flush output
     *\param rank      MPI rank with which to prefix output.
     *\param verbosity Verbosity limit.
     */
    DebugOutput( DebugOutputStream* str, int rank, unsigned verbosity = 0 );
    /**
     *\param str     Output stream to which to flush output
     *\param enabled Enable output: if not true, all output operations to nothing.
     */
    DebugOutput( FILE* str, unsigned verbosity = 0 );
    /**
     *\param str       Output stream to which to flush output
     *\param rank      MPI rank with which to prefix output.
     *\param verbosity Verbosity limit.
     */
    DebugOutput( FILE* str, int rank, unsigned verbosity = 0 );
    /**
     *\param str       Output stream to which to flush output
     *\param verbosity Verbosity limit.
     */
    DebugOutput( std::ostream& str, unsigned verbosity = 0 );
    /**
     *\param str       Output stream to which to flush output
     *\param rank      MPI rank with which to prefix output.
     *\param verbosity Verbosity limit.
     */
    DebugOutput( std::ostream& str, int rank, unsigned verbosity = 0 );

    /**
     *\param pfx       Prefix for output
     *\param str       Output stream to which to flush output
     *\param verbosity Verbosity limit.
     */
    DebugOutput( const char* pfx, DebugOutputStream* str, unsigned verbosity = 0 );
    /**
     *\param pfx       Prefix for output
     *\param str       Output stream to which to flush output
     *\param rank      MPI rank with which to prefix output.
     *\param verbosity Verbosity limit.
     */
    DebugOutput( const char* pfx, DebugOutputStream* str, int rank, unsigned verbosity = 0 );
    /**
     *\param pfx       Prefix for output
     *\param str     Output stream to which to flush output
     *\param enabled Enable output: if not true, all output operations to nothing.
     */
    DebugOutput( const char* pfx, FILE* str, unsigned verbosity = 0 );
    /**
     *\param pfx       Prefix for output
     *\param str       Output stream to which to flush output
     *\param rank      MPI rank with which to prefix output.
     *\param verbosity Verbosity limit.
     */
    DebugOutput( const char* pfx, FILE* str, int rank, unsigned verbosity = 0 );
    /**
     *\param pfx       Prefix for output
     *\param str       Output stream to which to flush output
     *\param verbosity Verbosity limit.
     */
    DebugOutput( const char* pfx, std::ostream& str, unsigned verbosity = 0 );
    /**
     *\param pfx       Prefix for output
     *\param str       Output stream to which to flush output
     *\param rank      MPI rank with which to prefix output.
     *\param verbosity Verbosity limit.
     */
    DebugOutput( const char* pfx, std::ostream& str, int rank, unsigned verbosity = 0 );

    DebugOutput( const DebugOutput& copy );
    DebugOutput& operator=( const DebugOutput& copy );

    /**
     * Destructor flushes any remaining output that wasn't followed
     * by a newline character.
     */
    ~DebugOutput();

    //!\brief Check if MPI rank has been set.
    bool have_rank() const
    {
        return mpiRank >= 0;
    }
    //!\brief Get MPI rank.
    int get_rank() const
    {
        return mpiRank;
    }
    //!\brief Set MPI rank.
    void set_rank( int rank )
    {
        mpiRank = rank;
    }
    //!\brief Set MPI rank to the rank of this proccess in MPI_COMM_WORLD,
    //!       or zero if MOAB is build w/out MPI.
    void use_world_rank();

    //!\brief Only print debug output from N processes
    void limit_output_to_first_N_procs( int N )
    {
        if( mpiRank >= N ) verbosityLimit = 0;
    }

    //!\brief Get verbosity limit
    unsigned get_verbosity() const
    {
        return verbosityLimit;
    }
    //!\brief Set verbosity limit
    void set_verbosity( unsigned val )
    {
        verbosityLimit = val;
    }

    //!\brief Get line prefix
    const std::string& get_prefix() const
    {
        return linePfx;
    }
    //!\brief Set line prefix
    void set_prefix( const std::string& str )
    {
        linePfx = str;
    }

    //!\brief Output the specified string iff output is enabled.
    void print( int verbosity, const char* str )
    {
        if( check( verbosity ) ) print_real( str );
    }

    //!\brief Output the specified string iff output is enabled.
    void print( int verbosity, const std::string& str )
    {
        if( check( verbosity ) ) print_real( str );
    }

    //!\brief Output the specified printf-formatted output iff output is enabled
    inline void printf( int verbosity, const char* fmt, ... ) MB_PRINTF( 2 );

    //!\brief Output the specified string iff output is enabled.
    //!
    //! Include current CPU time (as returned by clock()) in output.
    void tprint( int verbosity, const char* str )
    {
        if( check( verbosity ) ) tprint_real( str );
    }

    //!\brief Output the specified string iff output is enabled.
    //!
    //! Include current CPU time (as returned by clock()) in output.
    void tprint( int verbosity, const std::string& str )
    {
        if( check( verbosity ) ) tprint_real( str );
    }

    //!\brief Output the specified printf-formatted output iff output is enabled
    //!
    //! Include current CPU time (as returned by clock()) in output.
    inline void tprintf( int verbosity, const char* fmt, ... ) MB_PRINTF( 2 );

    //!\brief Print the contents of a moab::Range
    //!\param pfx String to print after default class prefix and before range contents
    void print( int verbosity, const char* pfx, const Range& range )
    {
        if( check( verbosity ) ) list_range_real( pfx, range );
    }
    //!\brief Print the contents of a moab::Range
    void print( int verbosity, const Range& range )
    {
        if( check( verbosity ) ) list_range_real( 0, range );
    }

    //!\brief Print the contents of a moab::Range as numerical values only
    //!\param pfx String to print after default class prefix and before range contents
    void print_ints( int verbosity, const char* pfx, const Range& range )
    {
        if( check( verbosity ) ) list_ints_real( pfx, range );
    }
    //!\brief Print the contents of a moab::Range as numerical values only
    void print_ints( int verbosity, const Range& range )
    {
        if( check( verbosity ) ) list_ints_real( 0, range );
    }

  private:
    std::string linePfx;
    DebugOutputStream* outputImpl;
    int mpiRank;
    unsigned verbosityLimit;
    CpuTimer cpuTi;

    void tprint();

    void list_range_real( const char* pfx, const Range& range );
    void list_ints_real( const char* pfx, const Range& range );
    void print_real( const char* buffer );
    void print_real( const std::string& str );
    void tprint_real( const char* buffer );
    void tprint_real( const std::string& str );

    // Function must be passed to copies of the same va_list because
    // a) it might have to call vs(n)printf twice, b) vs(n)printf modifies
    // the va_list such that it cannot be reused, and c) va_copy is not
    // (yet) portable (c99, no c++ standard).
    void print_real( const char* buffer, va_list args1, va_list args2 );
    void tprint_real( const char* buffer, va_list args1, va_list args2 );
    void process_line_buffer();

    std::vector< char > lineBuffer;

    inline bool check( unsigned verbosity )
    {
        return verbosity <= verbosityLimit;
    }
};

class DebugOutputStream
{
  protected:
    friend class DebugOutput;
    int referenceCount;

  public:
    DebugOutputStream() : referenceCount( 1 ) {}
    virtual ~DebugOutputStream();
    virtual void println( const char* pfx, const char* str )           = 0;
    virtual void println( int rank, const char* pfx, const char* str ) = 0;
};

void DebugOutput::printf( int verbosity, const char* fmt, ... )
{
    if( check( verbosity ) )
    {
        va_list args1, args2;
        va_start( args1, fmt );
        va_start( args2, fmt );
        print_real( fmt, args1, args2 );
        va_end( args2 );
        va_end( args1 );
    }
}

void DebugOutput::tprintf( int verbosity, const char* fmt, ... )
{
    if( check( verbosity ) )
    {
        va_list args1, args2;
        va_start( args1, fmt );
        va_start( args2, fmt );
        tprint_real( fmt, args1, args2 );
        va_end( args2 );
        va_end( args1 );
    }
}

}  // namespace moab

#endif