latest/source/lib/omnitrace-user/omnitrace/user.h Source File

latest/source/lib/omnitrace-user/omnitrace/user.h Source File#

omnitrace: latest/source/lib/omnitrace-user/omnitrace/user.h Source File
user.h
Go to the documentation of this file.
1 // MIT License
2 //
3 // Copyright (c) 2022 Advanced Micro Devices, Inc. All Rights Reserved.
4 //
5 // Permission is hereby granted, free of charge, to any person obtaining a copy
6 // of this software and associated documentation files (the "Software"), to deal
7 // in the Software without restriction, including without limitation the rights
8 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 // copies of the Software, and to permit persons to whom the Software is
10 // furnished to do so, subject to the following conditions:
11 //
12 // The above copyright notice and this permission notice shall be included in all
13 // copies or substantial portions of the Software.
14 //
15 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 // SOFTWARE.
22 
23 #ifndef OMNITRACE_USER_H_
24 #define OMNITRACE_USER_H_
25 
26 #if defined(OMNITRACE_USER_SOURCE) && (OMNITRACE_USER_SOURCE > 0)
27 # if !defined(OMNITRACE_PUBLIC_API)
28 # define OMNITRACE_PUBLIC_API __attribute__((visibility("default")))
29 # endif
30 #else
31 # if !defined(OMNITRACE_PUBLIC_API)
32 # define OMNITRACE_PUBLIC_API
33 # endif
34 #endif
35 
36 #include "omnitrace/categories.h"
37 #include "omnitrace/types.h"
38 
39 #if defined(__cplusplus)
40 extern "C"
41 {
42 #endif
43 
44  /// @fn int omnitrace_user_start_trace(void)
45  /// @return omnitrace_user_error_t value
46  /// @brief Enable tracing on this thread and all subsequently created threads
47  extern int omnitrace_user_start_trace(void) OMNITRACE_PUBLIC_API;
48 
49  /// @fn int omnitrace_user_stop_trace(void)
50  /// @return omnitrace_user_error_t value
51  /// @brief Disable tracing on this thread and all subsequently created threads
52  extern int omnitrace_user_stop_trace(void) OMNITRACE_PUBLIC_API;
53 
54  /// @fn int omnitrace_user_start_thread_trace(void)
55  /// @return omnitrace_user_error_t value
56  /// @brief Enable tracing on this specific thread. Does not apply to subsequently
57  /// created threads
58  extern int omnitrace_user_start_thread_trace(void) OMNITRACE_PUBLIC_API;
59 
60  /// @fn int omnitrace_user_stop_thread_trace(void)
61  /// @return omnitrace_user_error_t value
62  /// @brief Disable tracing on this specific thread. Does not apply to subsequently
63  /// created threads
64  extern int omnitrace_user_stop_thread_trace(void) OMNITRACE_PUBLIC_API;
65 
66  /// @fn int omnitrace_user_push_region(const char* id)
67  /// @param id The string identifier for the region
68  /// @return omnitrace_user_error_t value
69  /// @brief Start a user defined region.
70  extern int omnitrace_user_push_region(const char*) OMNITRACE_PUBLIC_API;
71 
72  /// @fn int omnitrace_user_pop_region(const char* id)
73  /// @param id The string identifier for the region
74  /// @return omnitrace_user_error_t value
75  /// @brief End a user defined region. In general, user regions should be popped in
76  /// the inverse order that they were pushed, i.e. first-in, last-out (FILO). The
77  /// timemory backend was designed to accommodate asynchronous tasking, where FILO may
78  /// be violated, and will thus compenstate for out-of-order popping, however, the
79  /// perfetto backend will not; thus, out-of-order popping will result in different
80  /// results in timemory vs. perfetto.
81  extern int omnitrace_user_pop_region(const char*) OMNITRACE_PUBLIC_API;
82 
83  /// @typedef omnitrace_annotation omnitrace_annotation_t
84  ///
85  /// @fn int omnitrace_user_push_annotated_region(const char* id,
86  /// omnitrace_annotation_t* annotations,
87  /// size_t num_annotations)
88  /// @param id The string identifier for the region
89  /// @param annotations Array of @ref omnitrace_annotation instances
90  /// @param num_annotations Number of annotations
91  /// @return omnitrace_user_error_t value
92  /// @brief Start a user defined region and adds the annotations to the perfetto trace.
94  size_t) OMNITRACE_PUBLIC_API;
95 
96  /// @fn int omnitrace_user_pop_annotated_region(const char* id,
97  /// omnitrace_annotation_t* annotations,
98  /// size_t num_annotations)
99  /// @param id The string identifier for the region
100  /// @param annotations Array of @ref omnitrace_annotation instances
101  /// @param num_annotations Number of annotations
102  /// @return omnitrace_user_error_t value
103  /// @brief Stop a user defined region and adds the annotations to the perfetto trace.
105  size_t) OMNITRACE_PUBLIC_API;
106 
107  /// mark causal progress
108  extern int omnitrace_user_progress(const char*) OMNITRACE_PUBLIC_API;
109 
110  /// mark causal progress with annotations
112  size_t) OMNITRACE_PUBLIC_API;
113 
114  /// @fn int omnitrace_user_configure(omnitrace_user_configure_mode_t mode,
115  /// omnitrace_user_callbacks_t inp,
116  /// omnitrace_user_callbacks_t* out)
117  /// @param[in] mode Specifies how the new callbacks are merged with the old
118  /// callbacks
119  /// @param[in] inp An @ref omnitrace_user_callbacks instance specifying
120  /// the callbacks which should be invoked by the user API.
121  /// @param[out] out Pointer to @ref omnitrace_user_callbacks which,
122  /// when non-NULL, will be assigned the former callbacks.
123  /// @return omnitrace_user_error_t value
124  /// @brief Configure the function pointers invoked by the omnitrace user API.
125  /// The initial callbacks are set via the omnitrace-dl library when it is loaded but
126  /// the user can user this feature to turn on/off the user API or customize how the
127  /// the user callbacks occur. For example, the user could maintain one set of
128  /// callbacks which discard any annotation data or redirect all unannotated user
129  /// regions to the annotated user regions with annotations about some global state.
130  /// Changing the callbacks is thread-safe but not thread-local.
133  omnitrace_user_callbacks_t* out) OMNITRACE_PUBLIC_API;
134 
135  /// @fn int omnitrace_user_get_callbacks(int category, void** begin_func, void**
136  /// end_func)
137  /// @param[in] category An @ref OMNITRACE_USER_BINDINGS value
138  /// @param[out] begin_func The pointer to the function which corresponds to "starting"
139  /// the category, e.g. omnitrace_user_start_trace or omnitrace_user_push_region
140  /// @param[out] end_func The pointer to the function which corresponds to "ending" the
141  /// category, e.g. omnitrace_user_stop_trace or omnitrace_user_pop_region
142  /// @return omnitrace_user_error_t value
143  /// @brief Get the current function pointers for a given category. The initial values
144  /// are assigned by omnitrace-dl at start up.
146  OMNITRACE_PUBLIC_API;
147 
148  /// @fn const char* omnitrace_user_error_string(int error_category)
149  /// @param error_category OMNITRACE_USER_ERROR value
150  /// @return String descripting the error code
151  /// @brief Return a descriptor for the provided error code
152  extern const char* omnitrace_user_error_string(int) OMNITRACE_PUBLIC_API;
153 
154 #if defined(__cplusplus)
155 }
156 #endif
157 
158 #endif // OMNITRACE_USER_H_
A struct containing annotation data to be included in the perfetto trace.
Definition: categories.h:178
enum OMNITRACE_USER_CONFIGURE_MODE omnitrace_user_configure_mode_t
Struct containing the callbacks for the user API.
Definition: types.h:45
int omnitrace_user_annotated_progress(const char *, omnitrace_annotation_t *, unsigned long)
mark causal progress with annotations
int omnitrace_user_push_annotated_region(const char *, omnitrace_annotation_t *, unsigned long)
int omnitrace_user_progress(const char *)
mark causal progress
int omnitrace_user_configure(omnitrace_user_configure_mode_t mode, omnitrace_user_callbacks_t inp, omnitrace_user_callbacks_t *out)
Configure the function pointers invoked by the omnitrace user API. The initial callbacks are set via ...
int omnitrace_user_start_thread_trace(void)
Enable tracing on this specific thread. Does not apply to subsequently created threads.
int omnitrace_user_stop_trace(void)
Disable tracing on this thread and all subsequently created threads.
int omnitrace_user_pop_annotated_region(const char *, omnitrace_annotation_t *, unsigned long)
int omnitrace_user_start_trace(void)
Enable tracing on this thread and all subsequently created threads.
int omnitrace_user_stop_thread_trace(void)
Disable tracing on this specific thread. Does not apply to subsequently created threads.
const char * omnitrace_user_error_string(int)
Return a descriptor for the provided error code.
int omnitrace_user_pop_region(const char *)
End a user defined region. In general, user regions should be popped in the inverse order that they w...
int omnitrace_user_get_callbacks(omnitrace_user_callbacks_t *)
int omnitrace_user_push_region(const char *)
Start a user defined region.