Skip to content

Latest commit

 

History

History
199 lines (149 loc) · 5.45 KB

README.md

File metadata and controls

199 lines (149 loc) · 5.45 KB
Raw

TRAKO

GitHub forks license Codacy Badge Fediverse IRC Channel

Trako profiler to optimize C++ projects with a single macro !

INTRODUCTION

Trako aims to help profiling a C++ project in real time without changing much of the architecture and related code to be studied...

Features :

  • Class profiling :

    • count how many instances of class at a given type
    • tell how many instances where created since last query
    • ...

  • Methods profiling :

    • trace methods call stack (entering or leaving)
    • measure time spend in method or scope
    • count how many times methods have been called
    • ...

  • Prevent pollution of code :

    • enable or disable using a single defines and link with a lib
    • no additional code in user's files beside those a macros
    • usage of macros that can easily disabled or located removed etc
    • can be used everywhere investigation need to be focused on as long as you have the source code

  • Integration in emacs (and probably other grep supported editors/IDE) :

    • file:line log entry format , just jump to the right place in one click

USAGE

Download

In your project directory or system dirs (ie: /usr/local/include/trako)

git clone --depth 1 https://github.com/rzr/trako --branch "0.2.0"
# Optionally build and run the example program, to profile execution.
make -C trako run

Include Header

Include trako.h in your project, let me suggest to do this a common included file (ie: config.h or private.h etc):

#define EXAMPLE_CONFIG_TRAKO 1

#if defined(EXAMPLE_CONFIG_TRAKO) && EXAMPLE_CONFIG_TRAKO
# include <trako/trako.h>
# define EXAMPLE(cmd)                           \
  TRAKO(cmd)
#else
# define EXAMPLE(cmd)                           \
  TRAKO(cmd)
#endif

Modify Code

Use the single "TRAKO" macro with a couple of TRAKO commands

For classes:

class MyClass { TRAKO(CLASS(MyClass)); };

Then you can collect stats, anywhere you have to call :

TRAKO(CLASS_STATS()); //will print new instances

and the result will be printed to console :

src/main.cpp:73: trace: <MyClass> -1=1 =16B (<2<42 )

read it as :

  • src/main.cpp: source where trace was invoked
  • 54: line in previous file
  • trace: tag to ease filtering
  • MyClass : Typename of tracked class with TRAKO_CLASS keyword
  • -1 : one instance was removed since last query
  • =1 : number instances of it are living in ram
  • = 16B : taking 16Bytes of RAM
  • (<2 : maximum different instances at a give time
  • <42 ) : total of instance created

If you want to profile time spend in methods, ie:

void funct() { TRAKO(FUNCT); };

Or Scopes too:

void funct(bool enabled) { if (enabled) { TRAKO(SCOPE("enabled")); } };

Then call and time will be traced like:

src/main.cpp:20: scope: { method @1 [=0s 706us]
src/main.cpp:26: scope: { methodSub @2 [=0s 715us]
src/main.cpp:26: scope: } funct() @1 [+0s 3us]

For more have a look at the example file and it's trace :

  • src/main.cpp
  • main.log.txt

KNOWN BUGS AND LIMITATIONS

  • fell free to report discovered bugs, wishes etc by email
  • supporting only g++ so far
  • barely supports typename collision among different namespaces

SUPPORT

Some success have been observed with following compilers:

  • g++ (Debian 6.3.0-18+deb9u1) 6.3.0 20170516 @ debian:9/amd64
  • g++ (Raspbian 6.3.0-18+rpi1+deb9u1) 6.3.0 20170516 @ Raspbian_9.0/armv7l
  • g++ (Debian 8.3.0-6) 8.3.0 @ debian:10/x86_64
  • g++ (Ubuntu 9.3.0-10ubuntu2) 9.3.0 @ Ubuntu_20.04/x86_64
  • clang version 10.0.0-4ubuntu1 @ Ubuntu_20.04/x86_64

While those versions may need extra efforts (please submit tickets for no cxx11 support):

  • g++ (Debian 4.9.2-10+deb8u2) 4.9.2 @ Debian:8
  • g++ (Ubuntu 5.3.1-14ubuntu2) 5.3.1 20160413 @ Ubuntu_16.04/i586
  • clang version 11.0.3 (clang-1103.0.32.59) @ Mac Os 10.15 : #2

Please report for others platforms:

  • clang : TODO
  • msvc : TODO
  • others ?

TODO

Other features may come later, most of them are already in progress if not done I plan to publish them once polished...

  • Features

    • TODO [#A] assertion logs

  • TODO [#B] script to ins/des/intrument source

    • TODO [#B] also track non user pointers even on closed source code

  • TODO [#C] port to other compilers clang msvc etc

    • TODO [#C] script to display source along its trace

  • TODO [#C] Integration with other tools, XML, gnuplot etc

  • Refactoring tasks :

    • TODO [#C] use STL's functions objects

RESOURCES