debug_helper.h

//                                                                                       //
//        _        _                         _            _                     _        //
//     __| |  ___ | |__   _   _   __ _      | |__    ___ | | _ __    ___  _ __ | |__     //
//    / _` | / _ \| '_ \ | | | | / _` |     | '_ \  / _ \| || '_ \  / _ \| '__|| '_ \    //
//   | (_| ||  __/| |_) || |_| || (_| |     | | | ||  __/| || |_) ||  __/| | _ | | | |   //
//    \__,_| \___||_.__/  \__,_| \__, |_____|_| |_| \___||_|| .__/  \___||_|(_)|_| |_|   //
//                               |___/|_____|               |_|                          //
//                                                                                       //
//                                                                                       //
//     This header file contains debug-related functionality, some of which will be      //
//     in the release version of the library, and expanded in the debug version.         //
//                                                                                       //

/*****************************************************************************

    X11workbench - X11 programmer's 'work bench' application and toolkit
    Copyright (c) 2010-2019 by Bob Frazier (aka 'Big Bad Bombastic Bob')

  DISCLAIMER:  The X11workbench application and toolkit software are supplied
               'as-is', with no warranties, either implied or explicit.
               Any claims to alleged functionality or features should be
               considered 'preliminary', and might not function as advertised.

  MIT-like license:

  There is no restriction as to what you can do with this software, so long
  as you include the above copyright notice and DISCLAIMER for any distributed
  work that is equal to or derived from this one, along with this paragraph
  that explains the terms of the license if the source is also being made
  available.  A "derived work" describes a work that uses a significant portion
  of the source files or algorithms that are included with this one.
  Specifically excluded from this are files that were generated by the software,
  or anything that is included with the software that is part of another package
  (such as files that were created or added during the 'configure' process).
  Specifically included is the use of part or all of any of the X11 workbench
  toolkit source or header files in your distributed application.  If you do not
  ship the source, the above copyright statement is still required to be placed
  in a reasonably prominent place, such as documentation, splash screens, and/or
  'about the application' dialog boxes.

  Use and distribution are in accordance with GPL, LGPL, and/or the above
  MIT-like license.  See COPYING and README files for more information.


  Additional information at http://sourceforge.net/projects/X11workbench

******************************************************************************/

#ifndef _DEBUG_HELPER_H_INCLUDED_
#define _DEBUG_HELPER_H_INCLUDED_

#ifndef __DOXYGEN__ /* exclude these so I don't mess up the docs */
#include "platform_helper.h" // always make sure, I need some definitions from here
#endif // __DOXYGEN__ /* exclude these so I don't mess up the docs */

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

#ifndef __DOXYGEN__ /* exclude these so I don't mess up the docs */
typedef struct s_WBGC * WBGC; // forward declaration - see window_helper.h
#endif // __DOXYGEN__ /* exclude these so I don't mess up the docs */


//   ____   _____  ____   _   _   ____    _   _  _____  _      ____   _____  ____   ____    //
//  |  _ \ | ____|| __ ) | | | | / ___|  | | | || ____|| |    |  _ \ | ____||  _ \ / ___|   //
//  | | | ||  _|  |  _ \ | | | || |  _   | |_| ||  _|  | |    | |_) ||  _|  | |_) |\___ \   //
//  | |_| || |___ | |_) || |_| || |_| |  |  _  || |___ | |___ |  __/ | |___ |  _ <  ___) |  //
//  |____/ |_____||____/  \___/  \____|  |_| |_||_____||_____||_|    |_____||_| \_\|____/   //
//                                                                                          //


enum DebugLevel
{
  DebugLevel_None = 0,      
  DebugLevel_ERROR = 0,     
  DebugLevel_WARN = 1,      

                            // criteria for selecting debug output
  DebugLevel_Minimal = 1,   
  DebugLevel_Light = 2,     
  DebugLevel_Medium = 3,    
  DebugLevel_Heavy = 4,     
  DebugLevel_Chatty = 5,    
  DebugLevel_Verbose = 6,   
  DebugLevel_Excessive = 7, 
  DebugLevel_MAXIMUM = 7,   
  DebugLevel_MASK = 7,      

  // next are subsystem masks for additional debugging for the toolkit.
  // Also, see 'aszDebugSubSys' in WBParseStandardArguments(), platform_helper.c (it must match)
  DebugSubSystem_ALL         = 0,           
  DebugSubSystem_RESTRICT    = 0x80000000,  
  DebugSubSystem_BITSHIFT    = 3,           
  DebugSubSystem_Init        = 0x00000008,  
  DebugSubSystem_Application = 0x00000010,  
  DebugSubSystem_Window      = 0x00000020,  
  DebugSubSystem_Menu        = 0x00000040,  
  DebugSubSystem_Event       = 0x00000080,  
  DebugSubSystem_Dialog      = 0x00000100,  
  DebugSubSystem_DialogCtrl  = 0x00000200,  
  DebugSubSystem_Frame       = 0x00000400,  
  DebugSubSystem_Keyboard    = 0x00000800,  
  DebugSubSystem_Mouse       = 0x00001000,  
  DebugSubSystem_Font        = 0x00002000,  
  DebugSubSystem_Settings    = 0x00004000,  
  DebugSubSystem_Selection   = 0x00008000,  
  DebugSubSystem_Pixmap      = 0x00010000,  
  DebugSubSystem_Expose      = 0x00020000,  
  DebugSubSystem_EditWindow  = 0x00040000,  
  DebugSubSystem_ScrollBar   = 0x00080000,  
  DebugSubSystem_DrawText    = 0x00100000,  
  DebugSubSystem_Clipboard   = 0x00200000,  
  DebugSubSystem_TextObject  = 0x00400000,  

  // remaining subsystem bits are reserved - please do not use them
  DebugSubSystem_RESERVED2   = 0x00800000,  
  DebugSubSystem_RESERVED3   = 0x01000000,  
  DebugSubSystem_RESERVED4   = 0x02000000,  
  DebugSubSystem_RESERVED5   = 0x04000000,  
  DebugSubSystem_RESERVED6   = 0x08000000,  
  DebugSubSystem_RESERVED7   = 0x10000000,  
  DebugSubSystem_RESERVED8   = 0x20000000,  
  DebugSubSystem_RESERVED9   = 0x40000000,  
  DebugSubSystem_MAX         = 0x40000000,  

  DebugSubSystem_MASK = ~7L  

  // user bits are the high 32-bits of a long-long value for the debug level.  They can be
  // used for any purpose without any restriction.
};




void WBSetDebugLevel(unsigned int iLevel);


#if defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ WB_UINT64 WBGetDebugLevel(void)
{
extern WB_UINT64 iWBDebugLevel;

  return iWBDebugLevel;
}
#else // !defined(__GNUC__) && !defined(_MSVC_VER)
WB_UINT64 WBGetDebugLevel(void);
#endif // defined(__GNUC__) || defined(_MSVC_VER)

#ifdef __GNUC__
void WBDebugPrint(const char *pFmt, ...) __attribute__ ((format(printf, 1, 2)));
#else // __GNUC__
void WBDebugPrint(const char *pFmt, ...);
#endif // __GNUC__

void WBDebugDump(const char *szTitle, void *pData, int cbData); // dump binary data

void WBDebugDumpGC(Display *pDisplay, WBGC hGC);

void WBDebugDumpRegion(Region hRgn, int bRotate);


void WBDebugDumpEvent(XEvent *pEvent);


#if defined(__GNUC__) || defined(_MSVC_VER)
static __inline__ int WBCheckDebugLevel(WB_UINT64 dwLevel)
{
extern WB_UINT64 iWBDebugLevel;

  if(WB_LIKELY((iWBDebugLevel & DebugLevel_MASK) < (dwLevel & DebugLevel_MASK)))
  {
    return 0;
  }

  if(!WB_UNLIKELY( WBGetDebugLevel() & DebugSubSystem_RESTRICT )) // RESTRICT not specified
  {
    if(!(dwLevel & DebugSubSystem_MASK) ) // no subsystem specified in debug output
    {
      return 1; // this is acceptable - since no subsystem specified, allow debug output if not 'RESTRICT'
    }
  }

  // at this point I have a debug subsystem 'RESTRICT' specified

  if(((dwLevel & DebugSubSystem_MASK) & (iWBDebugLevel & DebugSubSystem_MASK))
     != 0) // check to see that subsystem bits in 'dwLevel' match bits in 'iWBDebugLevel'
  {
    // at least one subsystem bit matches from 'dwLevel' and iWBDebugLevel
    return 1;
  }

  return 0;
}
#else // !defined(__GNUC__) && !defined(_MSVC_VER)
int WBCheckDebugLevel(WB_UINT64 dwLevel);
#endif // defined(__GNUC__) || defined(_MSVC_VER)



// NOTE:  The debug code will be included when NO_DEBUG is *NOT* defined

#ifdef NO_DEBUG /* assign this to disable debugging - most likely a -D in Makefile */
#define WB_DEBUG_PRINT(...)
#define WB_DEBUG_DUMP(L,X,Y,Z)
#define WB_IF_DEBUG_LEVEL(L) if(0) /* TODO:  turn off the warning? */
#define WB_DEFINE_PROFILE(__name)
#define WB_ENABLE_PROFILE(__name,__desc)
#define WB_START_PROFILE(__name)
#define WB_STOP_PROFILE(__name)
#else // NO_DEBUG

// NOTE:  this macro is the preferred method of implementing debug output.
#define WB_DEBUG_PRINT(L, ...) \
    WB_IF_DEBUG_LEVEL(L) { WBDebugPrint(__VA_ARGS__); }

#define WB_DEBUG_DUMP(L,X,Y,Z) \
    WB_IF_DEBUG_LEVEL(L) { WBDebugDump(X,Y,Z); }

#define WB_IF_DEBUG_LEVEL(L) if(WBCheckDebugLevel((L)))


#define WB_DEFINE_PROFILE(__name) static int __wb_profile_##__name = -1

#define WB_ENABLE_PROFILE(__name,__desc) { if(__wb_profile_##__name < 0) \
                                           __wb_profile_##__name = WBRegisterProfileVar(__FILE__, __LINE__, __FUNCTION__, \
                                                                                        WB_STRINGIZE(__name), __desc); }


#define WB_START_PROFILE(__name) WBStartProfile(__wb_profile_##__name)


#define WB_STOP_PROFILE(__name) WBStopProfile(__wb_profile_##__name)


// internally defined functions to support profiling - debug builds only.  do not call these directly.
int WBRegisterProfileVar(const char *szFile, WB_INT32 nLine, const char *szFunction, const char *szName, const char *szDesc);
void WBStartProfile(int nProfileID);
void WBStopProfile(int nProfileID);
void WBDumpProfileData(void);

#endif // NO_DEBUG


#define WB_WARN_PRINT(...) WB_DEBUG_PRINT(DebugLevel_WARN, __VA_ARGS__)

#define WB_ERROR_PRINT(...) WB_DEBUG_PRINT(DebugLevel_ERROR, __VA_ARGS__)

#define WB_WARN_DUMP(X,Y,Z) WB_DEBUG_DUMP(DebugLevel_WARN, X,Y,Z)

#define WB_ERROR_DUMP(X,Y,Z) WB_DEBUG_DUMP(DebugLevel_ERROR, X,Y,Z)




#ifdef __cplusplus
};
#endif // __cplusplus

#endif // _DEBUG_HELPER_H_INCLUDED_