+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 19. Profile Mode</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="C++, library, profile" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="extensions.html" title="Part III. Extensions" /><link rel="prev" href="parallel_mode_test.html" title="Testing" /><link rel="next" href="profile_mode_design.html" title="Design" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 19. Profile Mode</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="parallel_mode_test.html">Prev</a> </td><th width="60%" align="center">Part III.
- Extensions
-
-</th><td width="20%" align="right"> <a accesskey="n" href="profile_mode_design.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="manual.ext.profile_mode"></a>Chapter 19. Profile Mode</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.intro">Intro</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.using">Using the Profile Mode</a></span></dt><dt><span class="section"><a href="profile_mode.html#manual.ext.profile_mode.tuning">Tuning the Profile Mode</a></span></dt></dl></dd><dt><span class="section"><a href="profile_mode_design.html">Design</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode_design.html#manual.ext.profile_mode.design.wrapper">Wrapper Model</a></span></dt><dt><span class="section"><a href="profile_mode_design.html#manual.ext.profile_mode.design.instrumentation">Instrumentation</a></span></dt><dt><span class="section"><a href="profile_mode_design.html#manual.ext.profile_mode.design.rtlib">Run Time Behavior</a></span></dt><dt><span class="section"><a href="profile_mode_design.html#manual.ext.profile_mode.design.analysis">Analysis and Diagnostics</a></span></dt><dt><span class="section"><a href="profile_mode_design.html#manual.ext.profile_mode.design.cost-model">Cost Model</a></span></dt><dt><span class="section"><a href="profile_mode_design.html#manual.ext.profile_mode.design.reports">Reports</a></span></dt><dt><span class="section"><a href="profile_mode_design.html#manual.ext.profile_mode.design.testing">Testing</a></span></dt></dl></dd><dt><span class="section"><a href="profile_mode_api.html">Extensions for Custom Containers</a></span></dt><dt><span class="section"><a href="profile_mode_cost_model.html">Empirical Cost Model</a></span></dt><dt><span class="section"><a href="profile_mode_impl.html">Implementation Issues</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode_impl.html#manual.ext.profile_mode.implementation.stack">Stack Traces</a></span></dt><dt><span class="section"><a href="profile_mode_impl.html#manual.ext.profile_mode.implementation.symbols">Symbolization of Instruction Addresses</a></span></dt><dt><span class="section"><a href="profile_mode_impl.html#manual.ext.profile_mode.implementation.concurrency">Concurrency</a></span></dt><dt><span class="section"><a href="profile_mode_impl.html#manual.ext.profile_mode.implementation.stdlib-in-proflib">Using the Standard Library in the Instrumentation Implementation</a></span></dt><dt><span class="section"><a href="profile_mode_impl.html#manual.ext.profile_mode.implementation.malloc-hooks">Malloc Hooks</a></span></dt><dt><span class="section"><a href="profile_mode_impl.html#manual.ext.profile_mode.implementation.construction-destruction">Construction and Destruction of Global Objects</a></span></dt></dl></dd><dt><span class="section"><a href="profile_mode_devel.html">Developer Information</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode_devel.html#manual.ext.profile_mode.developer.bigpic">Big Picture</a></span></dt><dt><span class="section"><a href="profile_mode_devel.html#manual.ext.profile_mode.developer.howto">How To Add A Diagnostic</a></span></dt></dl></dd><dt><span class="section"><a href="profile_mode_diagnostics.html">Diagnostics</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.template">Diagnostic Template</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.containers">Containers</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.hashtable_too_small">Hashtable Too Small</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.hashtable_too_large">Hashtable Too Large</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.inefficient_hash">Inefficient Hash</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.vector_too_small">Vector Too Small</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.vector_too_large">Vector Too Large</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.vector_to_hashtable">Vector to Hashtable</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.hashtable_to_vector">Hashtable to Vector</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.vector_to_list">Vector to List</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.list_to_vector">List to Vector</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.list_to_slist">List to Forward List (Slist)</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.assoc_ord_to_unord">Ordered to Unordered Associative Container</a></span></dt></dl></dd><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.algorithms">Algorithms</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.algorithms.sort">Sort Algorithm Performance</a></span></dt></dl></dd><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.locality">Data Locality</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.locality.sw_prefetch">Need Software Prefetch</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.locality.linked">Linked Structure Locality</a></span></dt></dl></dd><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.mthread">Multithreaded Data Access</a></span></dt><dd><dl><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.mthread.ddtest">Data Dependence Violations at Container Level</a></span></dt><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.mthread.false_share">False Sharing</a></span></dt></dl></dd><dt><span class="section"><a href="profile_mode_diagnostics.html#manual.ext.profile_mode.analysis.statistics">Statistics</a></span></dt></dl></dd><dt><span class="bibliography"><a href="profile_mode.html#profile_mode.biblio">Bibliography</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.intro"></a>Intro</h2></div></div></div><p>
- <span class="emphasis"><em>Goal: </em></span>Give performance improvement advice based on
- recognition of suboptimal usage patterns of the standard library.
- </p><p>
- <span class="emphasis"><em>Method: </em></span>Wrap the standard library code. Insert
- calls to an instrumentation library to record the internal state of
- various components at interesting entry/exit points to/from the standard
- library. Process trace, recognize suboptimal patterns, give advice.
- For details, see the
- <a class="link" href="https://ieeexplore.ieee.org/document/4907670/" target="_top">Perflint
- paper presented at CGO 2009</a>.
- </p><p>
- <span class="emphasis"><em>Strengths: </em></span>
-</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
- Unintrusive solution. The application code does not require any
- modification.
- </p></li><li class="listitem"><p> The advice is call context sensitive, thus capable of
- identifying precisely interesting dynamic performance behavior.
- </p></li><li class="listitem"><p>
- The overhead model is pay-per-view. When you turn off a diagnostic class
- at compile time, its overhead disappears.
- </p></li></ul></div><p>
- </p><p>
- <span class="emphasis"><em>Drawbacks: </em></span>
-</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
- You must recompile the application code with custom options.
- </p></li><li class="listitem"><p>You must run the application on representative input.
- The advice is input dependent.
- </p></li><li class="listitem"><p>
- The execution time will increase, in some cases by factors.
- </p></li></ul></div><p>
- </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.using"></a>Using the Profile Mode</h3></div></div></div><p>
- This is the anticipated common workflow for program <code class="code">foo.cc</code>:
-</p><pre class="programlisting">
-$ cat foo.cc
-#include <vector>
-int main() {
- vector<int> v;
- for (int k = 0; k < 1024; ++k) v.insert(v.begin(), k);
-}
-
-$ g++ -D_GLIBCXX_PROFILE foo.cc
-$ ./a.out
-$ cat libstdcxx-profile.txt
-vector-to-list: improvement = 5: call stack = 0x804842c ...
- : advice = change std::vector to std::list
-vector-size: improvement = 3: call stack = 0x804842c ...
- : advice = change initial container size from 0 to 1024
-</pre><p>
- </p><p>
- Anatomy of a warning:
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
- Warning id. This is a short descriptive string for the class
- that this warning belongs to. E.g., "vector-to-list".
- </p></li><li class="listitem"><p>
- Estimated improvement. This is an approximation of the benefit expected
- from implementing the change suggested by the warning. It is given on
- a log10 scale. Negative values mean that the alternative would actually
- do worse than the current choice.
- In the example above, 5 comes from the fact that the overhead of
- inserting at the beginning of a vector vs. a list is around 1024 * 1024 / 2,
- which is around 10e5. The improvement from setting the initial size to
- 1024 is in the range of 10e3, since the overhead of dynamic resizing is
- linear in this case.
- </p></li><li class="listitem"><p>
- Call stack. Currently, the addresses are printed without
- symbol name or code location attribution.
- Users are expected to postprocess the output using, for instance, addr2line.
- </p></li><li class="listitem"><p>
- The warning message. For some warnings, this is static text, e.g.,
- "change vector to list". For other warnings, such as the one above,
- the message contains numeric advice, e.g., the suggested initial size
- of the vector.
- </p></li></ul></div><p>
- </p><p>Three files are generated. <code class="code">libstdcxx-profile.txt</code>
- contains human readable advice. <code class="code">libstdcxx-profile.raw</code>
- contains implementation specific data about each diagnostic.
- Their format is not documented. They are sufficient to generate
- all the advice given in <code class="code">libstdcxx-profile.txt</code>. The advantage
- of keeping this raw format is that traces from multiple executions can
- be aggregated simply by concatenating the raw traces. We intend to
- offer an external utility program that can issue advice from a trace.
- <code class="code">libstdcxx-profile.conf.out</code> lists the actual diagnostic
- parameters used. To alter parameters, edit this file and rename it to
- <code class="code">libstdcxx-profile.conf</code>.
- </p><p>Advice is given regardless whether the transformation is valid.
- For instance, we advise changing a map to an unordered_map even if the
- application semantics require that data be ordered.
- We believe such warnings can help users understand the performance
- behavior of their application better, which can lead to changes
- at a higher abstraction level.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.tuning"></a>Tuning the Profile Mode</h3></div></div></div><p>Compile time switches and environment variables (see also file
- profiler.h). Unless specified otherwise, they can be set at compile time
- using -D_<name> or by setting variable <name>
- in the environment where the program is run, before starting execution.
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
- <code class="code">_GLIBCXX_PROFILE_NO_<diagnostic></code>:
- disable specific diagnostics.
- See section Diagnostics for possible values.
- (Environment variables not supported.)
- </p></li><li class="listitem"><p>
- <code class="code">_GLIBCXX_PROFILE_TRACE_PATH_ROOT</code>: set an alternative root
- path for the output files.
- </p></li><li class="listitem"><p>_GLIBCXX_PROFILE_MAX_WARN_COUNT: set it to the maximum
- number of warnings desired. The default value is 10.</p></li><li class="listitem"><p>
- <code class="code">_GLIBCXX_PROFILE_MAX_STACK_DEPTH</code>: if set to 0,
- the advice will
- be collected and reported for the program as a whole, and not for each
- call context.
- This could also be used in continuous regression tests, where you
- just need to know whether there is a regression or not.
- The default value is 32.
- </p></li><li class="listitem"><p>
- <code class="code">_GLIBCXX_PROFILE_MEM_PER_DIAGNOSTIC</code>:
- set a limit on how much memory to use for the accounting tables for each
- diagnostic type. When this limit is reached, new events are ignored
- until the memory usage decreases under the limit. Generally, this means
- that newly created containers will not be instrumented until some
- live containers are deleted. The default is 128 MB.
- </p></li><li class="listitem"><p>
- <code class="code">_GLIBCXX_PROFILE_NO_THREADS</code>:
- Make the library not use threads. If thread local storage (TLS) is not
- available, you will get a preprocessor error asking you to set
- -D_GLIBCXX_PROFILE_NO_THREADS if your program is single-threaded.
- Multithreaded execution without TLS is not supported.
- (Environment variable not supported.)
- </p></li><li class="listitem"><p>
- <code class="code">_GLIBCXX_HAVE_EXECINFO_H</code>:
- This name should be defined automatically at library configuration time.
- If your library was configured without <code class="code">execinfo.h</code>, but
- you have it in your include path, you can define it explicitly. Without
- it, advice is collected for the program as a whole, and not for each
- call context.
- (Environment variable not supported.)
- </p></li></ul></div><p>
- </p></div></div><div class="bibliography"><div class="titlepage"><div><div><h2 class="title"><a id="profile_mode.biblio"></a>Bibliography</h2></div></div></div><div class="biblioentry"><a id="id-1.3.5.6.9.2"></a><p><span class="citetitle"><em class="citetitle">
- Perflint: A Context Sensitive Performance Advisor for C++ Programs
- </em>. </span><span class="author"><span class="firstname">Lixia</span> <span class="surname">Liu</span>. </span><span class="author"><span class="firstname">Silvius</span> <span class="surname">Rus</span>. </span><span class="copyright">Copyright © 2009 . </span><span class="publisher"><span class="publishername">
- Proceedings of the 2009 International Symposium on Code Generation
- and Optimization
- . </span></span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parallel_mode_test.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extensions.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="profile_mode_design.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Testing </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Design</td></tr></table></div></body></html>
\ No newline at end of file
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Extensions for Custom Containers</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="C++, library, profile" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="profile_mode_design.html" title="Design" /><link rel="next" href="profile_mode_cost_model.html" title="Empirical Cost Model" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Extensions for Custom Containers</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="profile_mode_design.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="profile_mode_cost_model.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.api"></a>Extensions for Custom Containers</h2></div></div></div><p>
- Many large projects use their own data structures instead of the ones in the
- standard library. If these data structures are similar in functionality
- to the standard library, they can be instrumented with the same hooks
- that are used to instrument the standard library.
- The instrumentation API is exposed in file
- <code class="code">profiler.h</code> (look for "Instrumentation hooks").
- </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="profile_mode_design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="profile_mode_cost_model.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Design </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Empirical Cost Model</td></tr></table></div></body></html>
\ No newline at end of file
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Empirical Cost Model</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="C++, library, profile" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="profile_mode_api.html" title="Extensions for Custom Containers" /><link rel="next" href="profile_mode_impl.html" title="Implementation Issues" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Empirical Cost Model</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="profile_mode_api.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="profile_mode_impl.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.cost_model"></a>Empirical Cost Model</h2></div></div></div><p>
- Currently, the cost model uses formulas with predefined relative weights
- for alternative containers or container implementations. For instance,
- iterating through a vector is X times faster than iterating through a list.
- </p><p>
- (Under development.)
- We are working on customizing this to a particular machine by providing
- an automated way to compute the actual relative weights for operations
- on the given machine.
- </p><p>
- (Under development.)
- We plan to provide a performance parameter database format that can be
- filled in either by hand or by an automated training mechanism.
- The analysis module will then use this database instead of the built in.
- generic parameters.
- </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="profile_mode_api.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="profile_mode_impl.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Extensions for Custom Containers </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Implementation Issues</td></tr></table></div></body></html>
\ No newline at end of file
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Design</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="C++, library, profile" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="next" href="profile_mode_api.html" title="Extensions for Custom Containers" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Design</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="profile_mode.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="profile_mode_api.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.design"></a>Design</h2></div></div></div><p>
-</p><div class="table"><a id="table.profile_code_loc"></a><p class="title"><strong>Table 19.1. Profile Code Location</strong></p><div class="table-contents"><table class="table" summary="Profile Code Location" border="1"><colgroup><col align="left" class="c1" /><col align="left" class="c2" /></colgroup><thead><tr><th align="left">Code Location</th><th align="left">Use</th></tr></thead><tbody><tr><td align="left"><code class="code">libstdc++-v3/include/std/*</code></td><td align="left">Preprocessor code to redirect to profile extension headers.</td></tr><tr><td align="left"><code class="code">libstdc++-v3/include/profile/*</code></td><td align="left">Profile extension public headers (map, vector, ...).</td></tr><tr><td align="left"><code class="code">libstdc++-v3/include/profile/impl/*</code></td><td align="left">Profile extension internals. Implementation files are
- only included from <code class="code">impl/profiler.h</code>, which is the only
- file included from the public headers.</td></tr></tbody></table></div></div><br class="table-break" /><p>
-</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.wrapper"></a>Wrapper Model</h3></div></div></div><p>
- In order to get our instrumented library version included instead of the
- release one,
- we use the same wrapper model as the debug mode.
- We subclass entities from the release version. Wherever
- <code class="code">_GLIBCXX_PROFILE</code> is defined, the release namespace is
- <code class="code">std::__norm</code>, whereas the profile namespace is
- <code class="code">std::__profile</code>. Using plain <code class="code">std</code> translates
- into <code class="code">std::__profile</code>.
- </p><p>
- Whenever possible, we try to wrap at the public interface level, e.g.,
- in <code class="code">unordered_set</code> rather than in <code class="code">hashtable</code>,
- in order not to depend on implementation.
- </p><p>
- Mixing object files built with and without the profile mode must
- not affect the program execution. However, there are no guarantees to
- the accuracy of diagnostics when using even a single object not built with
- <code class="code">-D_GLIBCXX_PROFILE</code>.
- Currently, mixing the profile mode with debug and parallel extensions is
- not allowed. Mixing them at compile time will result in preprocessor errors.
- Mixing them at link time is undefined.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.instrumentation"></a>Instrumentation</h3></div></div></div><p>
- Instead of instrumenting every public entry and exit point,
- we chose to add instrumentation on demand, as needed
- by individual diagnostics.
- The main reason is that some diagnostics require us to extract bits of
- internal state that are particular only to that diagnostic.
- We plan to formalize this later, after we learn more about the requirements
- of several diagnostics.
- </p><p>
- All the instrumentation points can be switched on and off using
- <code class="code">-D[_NO]_GLIBCXX_PROFILE_<diagnostic></code> options.
- With all the instrumentation calls off, there should be negligible
- overhead over the release version. This property is needed to support
- diagnostics based on timing of internal operations. For such diagnostics,
- we anticipate turning most of the instrumentation off in order to prevent
- profiling overhead from polluting time measurements, and thus diagnostics.
- </p><p>
- All the instrumentation on/off compile time switches live in
- <code class="code">include/profile/profiler.h</code>.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.rtlib"></a>Run Time Behavior</h3></div></div></div><p>
- For practical reasons, the instrumentation library processes the trace
- partially
- rather than dumping it to disk in raw form. Each event is processed when
- it occurs. It is usually attached a cost and it is aggregated into
- the database of a specific diagnostic class. The cost model
- is based largely on the standard performance guarantees, but in some
- cases we use knowledge about GCC's standard library implementation.
- </p><p>
- Information is indexed by (1) call stack and (2) instance id or address
- to be able to understand and summarize precise creation-use-destruction
- dynamic chains. Although the analysis is sensitive to dynamic instances,
- the reports are only sensitive to call context. Whenever a dynamic instance
- is destroyed, we accumulate its effect to the corresponding entry for the
- call stack of its constructor location.
- </p><p>
- For details, see
- <a class="link" href="https://ieeexplore.ieee.org/document/4907670/" target="_top">paper presented at
- CGO 2009</a>.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.analysis"></a>Analysis and Diagnostics</h3></div></div></div><p>
- Final analysis takes place offline, and it is based entirely on the
- generated trace and debugging info in the application binary.
- See section Diagnostics for a list of analysis types that we plan to support.
- </p><p>
- The input to the analysis is a table indexed by profile type and call stack.
- The data type for each entry depends on the profile type.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.cost-model"></a>Cost Model</h3></div></div></div><p>
- While it is likely that cost models become complex as we get into
- more sophisticated analysis, we will try to follow a simple set of rules
- at the beginning.
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>Relative benefit estimation:</em></span>
- The idea is to estimate or measure the cost of all operations
- in the original scenario versus the scenario we advise to switch to.
- For instance, when advising to change a vector to a list, an occurrence
- of the <code class="code">insert</code> method will generally count as a benefit.
- Its magnitude depends on (1) the number of elements that get shifted
- and (2) whether it triggers a reallocation.
- </p></li><li class="listitem"><p><span class="emphasis"><em>Synthetic measurements:</em></span>
- We will measure the relative difference between similar operations on
- different containers. We plan to write a battery of small tests that
- compare the times of the executions of similar methods on different
- containers. The idea is to run these tests on the target machine.
- If this training phase is very quick, we may decide to perform it at
- library initialization time. The results can be cached on disk and reused
- across runs.
- </p></li><li class="listitem"><p><span class="emphasis"><em>Timers:</em></span>
- We plan to use timers for operations of larger granularity, such as sort.
- For instance, we can switch between different sort methods on the fly
- and report the one that performs best for each call context.
- </p></li><li class="listitem"><p><span class="emphasis"><em>Show stoppers:</em></span>
- We may decide that the presence of an operation nullifies the advice.
- For instance, when considering switching from <code class="code">set</code> to
- <code class="code">unordered_set</code>, if we detect use of operator <code class="code">++</code>,
- we will simply not issue the advice, since this could signal that the use
- care require a sorted container.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.reports"></a>Reports</h3></div></div></div><p>
-There are two types of reports. First, if we recognize a pattern for which
-we have a substitute that is likely to give better performance, we print
-the advice and estimated performance gain. The advice is usually associated
-to a code position and possibly a call stack.
- </p><p>
-Second, we report performance characteristics for which we do not have
-a clear solution for improvement. For instance, we can point to the user
-the top 10 <code class="code">multimap</code> locations
-which have the worst data locality in actual traversals.
-Although this does not offer a solution,
-it helps the user focus on the key problems and ignore the uninteresting ones.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.design.testing"></a>Testing</h3></div></div></div><p>
- First, we want to make sure we preserve the behavior of the release mode.
- You can just type <code class="code">"make check-profile"</code>, which
- builds and runs the whole test suite in profile mode.
- </p><p>
- Second, we want to test the correctness of each diagnostic.
- We created a <code class="code">profile</code> directory in the test suite.
- Each diagnostic must come with at least two tests, one for false positives
- and one for false negatives.
- </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="profile_mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="profile_mode_api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 19. Profile Mode </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Extensions for Custom Containers</td></tr></table></div></body></html>
\ No newline at end of file
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Developer Information</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="C++, library, profile" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="profile_mode_impl.html" title="Implementation Issues" /><link rel="next" href="profile_mode_diagnostics.html" title="Diagnostics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Developer Information</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="profile_mode_impl.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="profile_mode_diagnostics.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.developer"></a>Developer Information</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.developer.bigpic"></a>Big Picture</h3></div></div></div><p>The profile mode headers are included with
- <code class="code">-D_GLIBCXX_PROFILE</code> through preprocessor directives in
- <code class="code">include/std/*</code>.
- </p><p>Instrumented implementations are provided in
- <code class="code">include/profile/*</code>. All instrumentation hooks are macros
- defined in <code class="code">include/profile/profiler.h</code>.
- </p><p>All the implementation of the instrumentation hooks is in
- <code class="code">include/profile/impl/*</code>. Although all the code gets included,
- thus is publicly visible, only a small number of functions are called from
- outside this directory. All calls to hook implementations must be
- done through macros defined in <code class="code">profiler.h</code>. The macro
- must ensure (1) that the call is guarded against reentrance and
- (2) that the call can be turned off at compile time using a
- <code class="code">-D_GLIBCXX_PROFILE_...</code> compiler option.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.developer.howto"></a>How To Add A Diagnostic</h3></div></div></div><p>Let's say the diagnostic name is "magic".
- </p><p>If you need to instrument a header not already under
- <code class="code">include/profile/*</code>, first edit the corresponding header
- under <code class="code">include/std/</code> and add a preprocessor directive such
- as the one in <code class="code">include/std/vector</code>:
-</p><pre class="programlisting">
-#ifdef _GLIBCXX_PROFILE
-# include <profile/vector>
-#endif
-</pre><p>
- </p><p>If the file you need to instrument is not yet under
- <code class="code">include/profile/</code>, make a copy of the one in
- <code class="code">include/debug</code>, or the main implementation.
- You'll need to include the main implementation and inherit the classes
- you want to instrument. Then define the methods you want to instrument,
- define the instrumentation hooks and add calls to them.
- Look at <code class="code">include/profile/vector</code> for an example.
- </p><p>Add macros for the instrumentation hooks in
- <code class="code">include/profile/impl/profiler.h</code>.
- Hook names must start with <code class="code">__profcxx_</code>.
- Make sure they transform
- in no code with <code class="code">-D_NO_GLIBCXX_PROFILE_MAGIC</code>.
- Make sure all calls to any method in namespace <code class="code">__gnu_profile</code>
- is protected against reentrance using macro
- <code class="code">_GLIBCXX_PROFILE_REENTRANCE_GUARD</code>.
- All names of methods in namespace <code class="code">__gnu_profile</code> called from
- <code class="code">profiler.h</code> must start with <code class="code">__trace_magic_</code>.
- </p><p>Add the implementation of the diagnostic.
- </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
- Create new file <code class="code">include/profile/impl/profiler_magic.h</code>.
- </p></li><li class="listitem"><p>
- Define class <code class="code">__magic_info: public __object_info_base</code>.
- This is the representation of a line in the object table.
- The <code class="code">__merge</code> method is used to aggregate information
- across all dynamic instances created at the same call context.
- The <code class="code">__magnitude</code> must return the estimation of the benefit
- as a number of small operations, e.g., number of words copied.
- The <code class="code">__write</code> method is used to produce the raw trace.
- The <code class="code">__advice</code> method is used to produce the advice string.
- </p></li><li class="listitem"><p>
- Define class <code class="code">__magic_stack_info: public __magic_info</code>.
- This defines the content of a line in the stack table.
- </p></li><li class="listitem"><p>
- Define class <code class="code">__trace_magic: public __trace_base<__magic_info,
- __magic_stack_info></code>.
- It defines the content of the trace associated with this diagnostic.
- </p></li></ul></div><p>
- </p><p>Add initialization and reporting calls in
- <code class="code">include/profile/impl/profiler_trace.h</code>. Use
- <code class="code">__trace_vector_to_list</code> as an example.
- </p><p>Add documentation in file <code class="code">doc/xml/manual/profile_mode.xml</code>.
- </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="profile_mode_impl.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="profile_mode_diagnostics.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Implementation Issues </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Diagnostics</td></tr></table></div></body></html>
\ No newline at end of file
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Implementation Issues</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="C++, library, profile" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="profile_mode.html" title="Chapter 19. Profile Mode" /><link rel="prev" href="profile_mode_cost_model.html" title="Empirical Cost Model" /><link rel="next" href="profile_mode_devel.html" title="Developer Information" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Implementation Issues</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="profile_mode_cost_model.html">Prev</a> </td><th width="60%" align="center">Chapter 19. Profile Mode</th><td width="20%" align="right"> <a accesskey="n" href="profile_mode_devel.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.ext.profile_mode.implementation"></a>Implementation Issues</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.stack"></a>Stack Traces</h3></div></div></div><p>
- Accurate stack traces are needed during profiling since we group events by
- call context and dynamic instance. Without accurate traces, diagnostics
- may be hard to interpret. For instance, when giving advice to the user
- it is imperative to reference application code, not library code.
- </p><p>
- Currently we are using the libc <code class="code">backtrace</code> routine to get
- stack traces.
- <code class="code">_GLIBCXX_PROFILE_STACK_DEPTH</code> can be set
- to 0 if you are willing to give up call context information, or to a small
- positive value to reduce run time overhead.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.symbols"></a>Symbolization of Instruction Addresses</h3></div></div></div><p>
- The profiling and analysis phases use only instruction addresses.
- An external utility such as addr2line is needed to postprocess the result.
- We do not plan to add symbolization support in the profile extension.
- This would require access to symbol tables, debug information tables,
- external programs or libraries and other system dependent information.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.concurrency"></a>Concurrency</h3></div></div></div><p>
- Our current model is simplistic, but precise.
- We cannot afford to approximate because some of our diagnostics require
- precise matching of operations to container instance and call context.
- During profiling, we keep a single information table per diagnostic.
- There is a single lock per information table.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.stdlib-in-proflib"></a>Using the Standard Library in the Instrumentation Implementation</h3></div></div></div><p>
- As much as we would like to avoid uses of libstdc++ within our
- instrumentation library, containers such as unordered_map are very
- appealing. We plan to use them as long as they are named properly
- to avoid ambiguity.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.malloc-hooks"></a>Malloc Hooks</h3></div></div></div><p>
- User applications/libraries can provide malloc hooks.
- When the implementation of the malloc hooks uses stdlibc++, there can
- be an infinite cycle between the profile mode instrumentation and the
- malloc hook code.
- </p><p>
- We protect against reentrance to the profile mode instrumentation code,
- which should avoid this problem in most cases.
- The protection mechanism is thread safe and exception safe.
- This mechanism does not prevent reentrance to the malloc hook itself,
- which could still result in deadlock, if, for instance, the malloc hook
- uses non-recursive locks.
- XXX: A definitive solution to this problem would be for the profile extension
- to use a custom allocator internally, and perhaps not to use libstdc++.
- </p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.ext.profile_mode.implementation.construction-destruction"></a>Construction and Destruction of Global Objects</h3></div></div></div><p>
- The profiling library state is initialized at the first call to a profiling
- method. This allows us to record the construction of all global objects.
- However, we cannot do the same at destruction time. The trace is written
- by a function registered by <code class="code">atexit</code>, thus invoked by
- <code class="code">exit</code>.
- </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="profile_mode_cost_model.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="profile_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="profile_mode_devel.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Empirical Cost Model </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Developer Information</td></tr></table></div></body></html>
\ No newline at end of file
projects / thirdparty / gcc.git / commitdiff
