Warning, /sdk/kcachegrind/README_DEVELOPER is written in an unsupported language. File is not indexed.

0001 A short guide into the internal design of KCachegrind
0002 =====================================================
0005 Basics of the data model
0006 ------------------------
0008 KCachegrind is a visualization of constant data. This makes the
0009 data model quite simple. However, as the visualization may require
0010 a lot of aggregation/summation of a huge number of raw data points in
0011 all kind of different ways, this aggregation is done in a lazy way.
0012 Only when the visualization asks for aggregated data, and the data was
0013 never requested before, aggregation is done.
0014 This makes the loading of large files faster: only the hierarchy of
0015 records (e.g. instructions belonging to a source line, source lines
0016 belong to a function, multiple functions are part of an ELF object)
0017 is built while loading a file, but no aggregation of data is done.
0018 Further, this reduces memory consumption.
0020 Important classes of the data model:
0022 * TraceData is a representation of profile data from one profile session,
0023   possibly consisting of multiple parts, where each part corresponds to a
0024   loaded file
0026 * any record/entry of a some profile data is inherited from CostItem,
0027   and this is a complete hierarchy, which gets automatically built
0028   when loading a file. E.g. TraceData itself inherits from CostItem.
0030 * every record/entry usually consists of different fields, and
0031   are indexed by so-called EventType's. So-called "derived" event
0032   types are not actually backed by real fields with concrete data,
0033   but get calculated on-demand using a given formula referencing
0034   fields with real data.
0037 Basics of the GUI
0038 -----------------
0040 At any time, every view visualizes some CostItem from loaded profile data.
0041 More concretely, the "visualization state" consists of e.g. the
0042 current CostItem to show, a curent EventType to show, from which
0043 part(s) to show, which sub-CostItem should be shown selected and so on.
0045 Every view is inherited from the TraceItemView class, which manages the
0046 visualization state. TraceItemView's can be setup in a hierarchical
0047 fashion, and make sure to keep the visualization state consistent between
0048 each other. E.g. item selection by mouse are forwarded to the parent view,
0049 which passes the new selection back to all its sub-views.
0051 When a subclass of TraceItemView is asked to change its visualization state,
0052 it actually only starts a timer, and all state change wishes get merged
0053 until a time-out happens.
0054 Then, TraceViewItem::doUpdate() gets called with an argument telling what
0055 parts of the visualization state should be changed. There, one can do
0056 special handling if only one thing is to be changed, such as selection of
0057 another CostItem - in such cases, it is not required to refresh the whole
0058 view. Otherwise, TraceViewItem::refresh() gets called, which is expected
0059 to do a complete refresh of the visualization.
0061 The basic visualization task of subclasses of TraceItemView's is to visualize
0062 one CostItem (the "active" CostItem), typically e.g. a function
0063 (TraceFunction). Further, there is a "selected" CostItem. This usually is
0064 a subitem of the active, visualized CostItem, e.g. a source line from the
0065 active function (TraceLine), or another function in the call graph around
0066 the active function.
0068 TraceItemView's may not be able to show a given CostItem, but want to show
0069 another CostItem instead, or show nothing. In the latter case, they get
0070 grayed out. This behavior is encoded through TraceItemView::canShow, which,
0071 given a CostItem to visualize, returns the replacement it can visualize
0072 instead, or 0 if it cannot show anything.
0074 Every top-level window visualizes exactly one profile data (_data),
0075 and consists of some subviews (FunctionSelection on the left, MultiView on
0076 the right, with various TabViews embedded) which all inherit from
0077 TraceItemView, always synced to show some visualization state at a given
0078 time.