HowTo?

Before going further into this HowTo section, you should have a look at how the recorded data are structured [MORE_HERE].

How to set the profiler into your application (QuickSteps)?

Updating your project's settings:

• Which files to include? A unique header file is required:

                  #include <SugoiTools\appli.h>   
  

  
  If you are not using Microsoft Visual Studio, you have to link with the following libraries:

                  SugoiTools(d).lib
                  SugoiTracer(d).lib
  

• Some usefull preprocessor and macros:
  If your project is in C++ add the _CPP pre-processor value into your project. You may want to have a pre-processor value to enable profiling compilation like _MY_APP_DO_PROFILING. Then you can use it with different macros, they will help you having to many ifdef endif your the source code.

Todo:

Finish the documentation for C++

        //C++
                [TODO...]
        
        //C     
        #ifdef _MY_APP_DO_PROFILING
                #include <SugoiTools\appli.h>           //Main include file.
                #define _MY_APP_PROFILE(FCT) FCT                
                //
                #define _MY_APP_START_RECORD(FCT_NAME)  StartRecordingChar(CreateFunction(FCT_NAME), "VER", YOUR_APPLICATION_VERSION)
                #define _MY_APP_STOP_RECORD(FCT_ID)     StopRecording(FCT_ID)
                #define _MY_APP_ADDPARAM(FCT)   FCT
        #else
                #define _MY_APP_DOPROFILE(FCT)
                #define _MY_APP_START_RECORD(FCT_NAME)
                #define _MY_APP_STOP_RECORD(FCT_ID)
                #define _MY_APP_ADDPARAM(FCT)
        #endif

Init the profiling tools (C and C++):

The profiling tools use XML files to store the results, you may want to load an existing file while starting your application:

                return XMLLoadBench(Filename);

And save it when exiting your application:

                return XMLSaveBench(Filename);

Init the profiling tools (C++ only):

An application profiler is a TTCL_APPLI_TRACER object. You need to create one at the beginning of your application before any function is profiled.

 ...
 #include <SG_TRC_appli.h>      //include the main header file.
 ...
 int main()
 {
                //Create main application profiler
                TTCL_APPLI_TRACER * AppliProfiler = new TTCL_APPLI_TRACER();
                
                //now you can profile your functions...
                ...
 }

When you create the first TTCL_APPLI_TRACER object, the static handler TTCL_APPLI_TRACER<CL_TimerVal>::MainAppliTracer is affected to this object. Then you can easily reach your profiler from every parts of yours code.

Note:

Don't forget to delete AppliProfiler object (and other TTCL_APPLI_TRACER you created) when exiting four application.

Add a profiler in c++:

Save results to an XML file:

Before exiting your application, you may want to save you profiling data.

        //this will save your records into a file using the date, so you can check the evolution of your work.
        std::string FileName = "Bench -";
        FileName += __DATE__;
        TTCL_APPLI_TRACER<CL_TimerVal>::MainAppliTracer->XMLSaveToFile(FileName.data());

How to profile a function?

Profiling a function without arguments in C++:

Profiling a function in C++ is very easy, let's have a look at the following piece of code.

 void FunctionToProfile(....)
 {
 //I suggest you to use preprocessor branching for profiling, so you can easily disable it in your release builds.
#if SUPPORT_BENCHMARK

        //Here, we create a static handler to the CL_FUNCTION_TRC object representing this function.
        //we use the main TTCL_APPLI_TRACER object for this operation and call the AddFunct with the name of our function.
        //this part of code will only be executed once, the first time we get into FunctionToProfile().
        static SG_TRC_FUNCT_BY_TIME = TTCL_APPLI_TRACER<CL_TimerVal>::MainAppliTracer->AddFunct("FunctionToProfile");
        
        //Now we create a temporary tracer(CL_TEMP_TRACER) object, and we give him the handler to this function 'ThisFct'.
        //The second parameter will stay NULL, we will see later how to use it.
        //When creating a CL_TEMP_TRACER, a CL_TRACER is automatically created and start recording time.
        SG_TRC_TEMP_TRACER_BY_TIME (ThisFct, NULL);
        
#endif

        //code of the function
        ...
        ...     
        
        //when we leave FunctionToProfile(), 'Tracer' will be automatically destroyed and this will stop the timer and save a record.
}

Here it is, a new record for the function FunctionToProfile() has been set and added into the right CL_FUNCT_TRC object.

Profiling a function (C and C++):

Profiling a function in C is also quite easy and is done in a few steps:

• Create a unique ID and start the function profiling:

                  _MY_APP_DOPROFILE(int FctProfileId = _ART_START_RECORD("MY_FCT_NAME"));
  

• Add some (input)parameters to your function:

                  _MY_APP_ADDPARAM(AddParamInt(FctProfileId, "width", img_width););
                  _MY_APP_ADDPARAM(AddParamChar(FctProfileId, "filename", img_filename););
  

• Process you own function code.
• Add some (output)parameters to your function:
  You can add some results to your function like adding an input parameter.
• Stop the profiling before your are living the function:

                  _MY_APP_STOP_RECORD(ProfileId);
  

Note:

Several piece of code can be profiled at the same time using different ProfileId variable.

If the profiled function is inside a loop, it may be more efficient (in processing Time) to profile the loop and store the number of loop as a parameter. It is not possible in all case.

Adding argument to the profiled function in C++:

Adding profiling arguments can be easy, depending on wich type of argument you want to add. We are going to add a std::string argument, then an int arguments.

 void FunctionToProfile(char * _stringValue1, int _intValue1)
 {
 #if SUPPORT_BENCHMARK
        static SG_TRC_FUNCT_BY_TIME = TTCL_APPLI_TRACER<CL_TimerVal>::MainAppliTracer->AddFunct("FunctionToProfile");
        
        //Before creating the temp tracer, we are going to create a temp argumement CL_TRACE_BASE_PARAMS with a std::string argument.
        CL_TRACE_BASE_PARAMS * TempParams = new CL_TRACE_BASE_PARAMS("argDescription1", _stringValue1);
        
        //then we had an integer argument :
        TempParams->AddInt ("argDescription2", &_intValue1, 1);
        
        //then we create a CL_TEMP_TRACER with the right parameters.
        SG_TRC_TEMP_TRACER_BY_TIME (ThisFct, TempParams);
        
#endif

        //code of the function
        ...
        ...     
        
        //When destroying Tracer, the record will be stored with the right parameters.
}

Here it is, a new record for the function FunctionToProfile() has been set and added into the right CL_FUNCT_TRC object.
Notice: See the CL_TRACE_BASE_PARAMS class to know about the arguments managing.

How to profile a class?

How to get profiling statistics?

Getting real time statistics about a function C++:

Getting real time statistics about a class C++:

Reset all the records:

---