README.txt 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110
  1. Package: trako
  2. Author: Philippe Coval <rzr@gna.org>
  3. URL: http://rzr.online.fr/
  4. Description: C++ tracking library that count instances funct calls etc
  5. ### INTRODUCTION ###
  6. Trako aims to help profiling a C++ project in real time
  7. without changing much of the architecture and related code to be studied...
  8. Features :
  9. * Class profiling :
  10. + count how many instances of class at a given type
  11. + tell how many instances where created since last query
  12. + ...
  13. * Methods profiling :
  14. + trace methods call stack (entering or leaving)
  15. + mesure time spend in method or scope
  16. + count how many times methods have been called
  17. + ...
  18. * Prevent pollution of code :
  19. + enable or disable using a single defines and link with a lib
  20. + no additionnal code in user's files beside those a macros
  21. + usage of macros that can easly disabled or located removed etc
  22. + can be used everywhere investigation need to be focused on
  23. as long as you have the source code
  24. * Integration in emacs (and probally other grep supported editors/IDE) :
  25. + file:line log entry format , just jump to the right place in one click
  26. ### USAGE ###
  27. Link your app with libtrako's enabled
  28. CXXFLAGS+=-DCONFIG_WANT_LIBTRAKO=1
  29. LDFLAGS+=-ltrako
  30. Add those "TRAKO keywords" in your tracked class ie :
  31. class MyClass { TRAKO_CLASS(MyClass); };
  32. Then you can collect stats, anywhere you have to call :
  33. TRAKO_DIFF(); //will print new instances
  34. and the result will be printed to console :
  35. src/main.cpp:73: trace: <MyClass> -1=1 =16B (<2<42 )
  36. read it as :
  37. * src/main.cpp: source where trace was invoked
  38. * 54: line in previous file
  39. * trace: tag to ease filtering
  40. * <MyClass> : Typename of tracked class with TRAKO_CLASS keyword
  41. * -1 : one instance was removed since last query
  42. * =1 : number instances of it are living in ram
  43. * = 16B : taking 16Bytes of RAM
  44. * (<2 : maximum different instances at a give time
  45. * <42 ) : total of instance created
  46. If you want to profile time spend in methods, ie:
  47. void funct() { TRAKO_FUNCT(); };
  48. will display time since application startup and once returning function, ie:
  49. src/main.cpp:20: scope: { method @1 [=0s 706us]
  50. src/main.cpp:26: scope: { methodSub @2 [=0s 715us]
  51. src/main.cpp:26: scope: } methodSub @2 [+0s 3us]
  52. For more have a look at those example files :
  53. src/main.cpp
  54. main.log.txt
  55. ### KNOWN BUGS AND LIMITATIONS ###
  56. * fell free to report discovered bugs, wishes etc by email
  57. * supporting only g++ so far
  58. * barly supports typename collision among different namespaces
  59. ### TODO ###
  60. Other features may come later,
  61. most of them are already in progress if not done
  62. I plan to publish them once polished...
  63. * Features
  64. ** TODO [#A] assertion logs
  65. ** TODO [#B] script to ins/des/intrument source
  66. ** TODO [#B] also track non user pointers even on closed source code
  67. ** TODO [#C] port to other compilers clang msvc etc
  68. ** TODO [#C] script to display source along its trace
  69. ** TODO [#C] Integration with other tools, XML, gnuplot etc
  70. * Refactoring tasks :
  71. ** TODO [#C] use STL's functions objects