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 ===================================================== 0003 0004 0005 Basics of the data model 0006 ------------------------ 0007 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. 0019 0020 Important classes of the data model: 0021 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 0025 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. 0029 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. 0035 0036 0037 Basics of the GUI 0038 ----------------- 0039 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. 0044 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. 0050 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. 0060 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. 0067 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. 0073 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. 0079