@@ -18,6 +18,14 @@ where `Size` is the maximum number of external functions to be wrapped,
1818` Diff ` is an optional template parameter for differentiating ` gotcha ` components with equivalent ` Size ` and ` Tools `
1919parameters but wrap different functions. Note: the ` Tools ` type cannot contain other ` gotcha ` components.
2020
21+ ### Use Cases
22+
23+ The ` gotcha ` component in timemory can provide either of the following functionalities:
24+
25+ 1 . Scoped instrumentation around external dynamically-linked function calls
26+ 2 . Wholesale replacement of external dynamically-linked function calls
27+
28+
2129## Traditional GOTCHA in C
2230
2331Writing a traditional GOTCHA wrapper in C requires a bit of work and the recommended methods require
@@ -77,7 +85,59 @@ A GOTCHA wrapper with timemory can be defined in a single line of code and there
7785macros provided that eliminate the need for specifying the function signature (return-type and
7886arguments) due to the ability for templates to extract these parameters.
7987
80- ## GOTCHA Example
88+ ## Function Replacement with GOTCHA Example
89+
90+ Suppose that an application is spending a signifincant amount of run-time calling the standard math library
91+ double-precision `exp` function and you would like to investigate whether using single-precision `expf` is an
92+ acceptable substitute in certain regions. Instead of writing the [full specification](#traditional-gotcha-in-c)
93+ shown previously and manually enabling and disabling the wrapper in the region of interest, you can use timemory.
94+
95+ Provided below is the full component specification require to implement the replacement function.
96+
97+ ```cpp
98+ // NOTE: declared in tim::component::
99+ struct exp_intercept : public base<exp_intercept, void>
100+ {
101+ double operator()(double val)
102+ { return expf(static_cast<float>(val)); }
103+ };
104+ ```
105+
106+ When the ` exp_intercept ` component is _ appropriately_ configured within a ` gotcha ` component,
107+ whenever ` double exp(double) ` is invoked, timemory will (via the GOTCHA library) redirect this function call to
108+ ` double exp_intercept::operator()(double) ` -- and within this function, the replaced call to ` expf ` is implemented.
109+ Configuring the ` gotcha ` component is slightly different, however. The goal of this component is __ * optimization* __
110+ instead of __ * measurement or analysis* __ so the ` gotcha ` component is specified as such:
111+
112+ ``` cpp
113+ using empty_t = component_tuple<>;
114+ using exp_gotcha_t = gotcha<1 , empty_t , exp_intercept>;
115+ ```
116+
117+ In other words, we define a ` gotcha ` component with an empty set of measurement/analysis components and
118+ then we specify _ a component_ as the third template parameter. The _ combination_ of an empty measurement/analysis
119+ collection as the second template parameter and a component as the third template parameter trigger a special
120+ optimized wrapper around the original function call which is explicitly designed to minimize the overhead of
121+ the redirection to the wrapper.
122+
123+ All that remains is implementing the initializer that specifies which functions are wrapped by the ` gotcha ` component:
124+
125+ ``` cpp
126+ __attribute__ ((constructor))
127+ void init_gotcha()
128+ {
129+ exp_gotcha_t::get_initializer() = [ =] ( )
130+ { TIMEMORY_C_GOTCHA(exp_gotcha_t, 0, exp); };
131+ }
132+ ```
133+
134+ In the above, using the constructor attribute (only available with certain compilers) creates a function
135+ that is automatically executed before main starts. Since this function configured the gotcha within a call-back,
136+ instead of explicitly invoking `TIMEMORY_C_GOTCHA`, the gotcha wrapper is not activated during this function,
137+ meaning that the redirection of `exp` to `expf` is explicitly tied to the allocation of
138+ at least one instance of `exp_gotcha_t`.
139+
140+ ## Instrumentation with GOTCHA Example
81141
82142> Reference: [source/tests/gotcha_tests.cpp](https://github.com/NERSC/timemory/blob/master/source/tests/gotcha_tests.cpp)
83143
0 commit comments