Actual source code: petsclogtypes.h
1: #pragma once
2: #include <petscsystypes.h>
4: /* MANSEC = Sys */
5: /* SUBMANSEC = Log */
7: /*S
8: PetscEventPerfInfo - statistics on how many times the event is used, how much time it takes, etc.
10: Level: advanced
12: Note:
13: This is the data structure that describes profiling statsitics collected for an event from
14: the default log handler (`PetscLogDefaultBegin()`) using `PetscLogEventGetPerfInfo()`.
16: .seealso: [](ch_profiling)
17: S*/
18: typedef struct {
19: int id; /* The integer identifying this event / stage */
20: PetscBool active; /* Deprecated */
21: PetscBool visible; /* The flag to print info in summary */
22: int depth; /* The nesting depth of the event call */
23: int count; /* The number of times this event was executed */
24: PetscLogDouble flops; /* The flops used in this event */
25: PetscLogDouble flops2; /* The square of flops used in this event */
26: PetscLogDouble flopsTmp; /* The accumulator for flops used in this event */
27: PetscLogDouble time; /* The time taken for this event */
28: PetscLogDouble time2; /* The square of time taken for this event */
29: PetscLogDouble timeTmp; /* The accumulator for time taken for this event */
30: PetscLogDouble syncTime; /* The synchronization barrier time */
31: PetscLogDouble dof[8]; /* The number of degrees of freedom associated with this event */
32: PetscLogDouble errors[8]; /* The errors (user-defined) associated with this event */
33: PetscLogDouble numMessages; /* The number of messages in this event */
34: PetscLogDouble messageLength; /* The total message lengths in this event */
35: PetscLogDouble numReductions; /* The number of reductions in this event */
36: PetscLogDouble memIncrease; /* How much the resident memory has increased in this event */
37: PetscLogDouble mallocIncrease; /* How much the maximum malloced space has increased in this event */
38: PetscLogDouble mallocSpace; /* How much the space was malloced and kept during this event */
39: PetscLogDouble mallocIncreaseEvent; /* Maximum of the high water mark with in event minus memory available at the end of the event */
40: #if defined(PETSC_HAVE_DEVICE)
41: PetscLogDouble CpuToGpuCount; /* The total number of CPU to GPU copies */
42: PetscLogDouble GpuToCpuCount; /* The total number of GPU to CPU copies */
43: PetscLogDouble CpuToGpuSize; /* The total size of CPU to GPU copies */
44: PetscLogDouble GpuToCpuSize; /* The total size of GPU to CPU copies */
45: PetscLogDouble GpuFlops; /* The flops done on a GPU in this event */
46: PetscLogDouble GpuTime; /* The time spent on a GPU in this event */
47: PetscLogDouble GpuEnergy; /* The energy consumed on a GPU in this event */
48: #endif
49: } PetscEventPerfInfo;
51: /*S
52: PetscIntStack - Opaque PETSc stack-of-`int` data structure used internally for performance logging (for example, to track nested log stage and event pushes)
54: Level: developer
56: .seealso: `PetscIntStackCreate()`, `PetscIntStackDestroy()`, `PetscIntStackPush()`, `PetscIntStackPop()`, `PetscIntStackTop()`, `PetscIntStackEmpty()`
57: S*/
58: typedef struct _n_PetscIntStack *PetscIntStack;
60: /*MC
61: PetscLogEvent - id used to identify PETSc or user events which timed portions (blocks of executable)
62: code.
64: Level: intermediate
66: .seealso: [](ch_profiling), `PetscLogEventRegister()`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogStage`
67: M*/
68: typedef int PetscLogEvent;
70: /*MC
71: PetscLogStage - id used to identify user stages (phases, sections) of runs - for logging
73: Level: intermediate
75: .seealso: [](ch_profiling), `PetscLogStageRegister()`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogEvent`
76: M*/
77: typedef int PetscLogStage;
79: /*MC
80: PetscLogClass - id used to identify classes for logging purposes only. It
81: is not equal to its `PetscClassId`, which is the identifier used for other
82: purposes.
84: Level: developer
86: .seealso: [](ch_profiling), `PetscLogStateClassRegister()`
87: M*/
88: typedef int PetscLogClass;
90: /*S
91: PetscLogHandler - Interface for performance logging. A log handler receives a `PetscLogState` that has
92: information about the events (`PetscLogEvent`) and stages (`PetscLogStage`) in the logging environment.
93: When a handler is connected to PETSc's global logging stream (`PetscLogHandlerStart()`), it receives
94: updates about events (`PetscLogEventBegin()` / `PetscLogEventEnd()`), stages (`PetscLogStagePush()` /
95: `PetscLogStagePop()`), and objects (`PetscLogObjectCreate()` / `PetscLogObjectDestroy()`). After
96: collecting information the logger can summarize its data with `PetscLogHandlerView()`.
98: Example Usage:
99: .vb
100: #include <petscsys.h>
102: int main() {
103: UserCtx ctx;
104: PetscLogHandlerType handler_type;
106: PetscInitialize(...);
107: // ... fill in ctx
108: PetscLogHandlerCreate(PETSC_COMM_WORLD, &handler);
109: PetscLogHandlerSetType(handler, handler_type);
110: PetscLogHandlerStart(handler); // connect your handler to global logging state
111: // ... run code to be profiled
112: PetscLogHandlerStop(handler); // disconnect your handler from the global logging state
113: PetscLogHandlerView(handler, PETSC_VIEWER_STDOUT_WORLD); // view the results
114: PetscLogHandlerDestroy(&handler);
115: PetscFinalize();
116: }
117: .ve
119: Level: developer
121: .seealso: [](ch_profiling),
122: `PetscLogHandlerCreate()`,
123: `PetscLogHandlerStart()`, `PetscLogHandlerStop()`,
124: `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`,
125: `PetscLogHandlerSetState()`, `PetscLogHandlerGetState()`,
126: `PetscLogHandlerEventBegin()`, `PetscLogHandlerEventEnd()`,
127: `PetscLogHandlerEventSync()`,
128: `PetscLogHandlerObjectCreate()`, `PetscLogHandlerObjectDestroy()`,
129: `PetscLogHandlerStagePush()`, `PetscLogHandlerStagePop()`,
130: `PetscLogHandlerView()`,
131: `PetscLogHandlerDestroy()`
132: S*/
133: typedef struct _p_PetscLogHandler *PetscLogHandler;
135: /*J
136: PetscLogHandlerType - String with the name of a `PetscLogHandler` type
138: Level: Developer
140: Note:
141: Implementations included with PETSc include\:
142: + `PETSCLOGHANDLERDEFAULT` (`PetscLogDefaultBegin()`) - formats data for PETSc's default summary (`PetscLogView()`) and data-dump (`PetscLogDump()`) formats.
143: . `PETSCLOGHANDLERNESTED` (`PetscLogNestedBegin()`) - formats data for XML or flamegraph output
144: . `PETSCLOGHANDLERTRACE` (`PetscLogTraceBegin()`) - traces profiling events in an output stream
145: . `PETSCLOGHANDLERMPE` (`PetscLogMPEBegin()`) - outputs parallel performance visualization using MPE
146: . `PETSCLOGHANDLERPERFSTUBS` (`PetscLogPerfstubsBegin()`) - outputs instrumentation data for PerfStubs/TAU
147: . `PETSCLOGHANDLERLEGACY` (`PetscLogLegacyCallbacksBegin()`) - adapts legacy callbacks to the `PetscLogHandler` interface
148: - `PETSCLOGHANDLERNVTX` - creates NVTX ranges for events that are visible in Nsight
149: - `PETSCLOGHANDLERROCTX` - creates ROCTx ranges for events that are visible in rocprof
151: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`
152: J*/
153: typedef const char *PetscLogHandlerType;
155: #define PETSCLOGHANDLERDEFAULT "default"
156: #define PETSCLOGHANDLERNESTED "nested"
157: #define PETSCLOGHANDLERTRACE "trace"
158: #define PETSCLOGHANDLERMPE "mpe"
159: #define PETSCLOGHANDLERPERFSTUBS "perfstubs"
160: #define PETSCLOGHANDLERLEGACY "legacy"
161: #define PETSCLOGHANDLERNVTX "nvtx"
162: #define PETSCLOGHANDLERROCTX "roctx"
164: /*S
165: PetscLogRegistry - Opaque PETSc registry of logging events, stages and classes that is shared by all `PetscLogHandler`s attached to a given `PetscLogState`
167: Level: developer
169: .seealso: `PetscLogState`, `PetscLogStateGetRegistry()`, `PetscLogHandler`, `PetscLogEventRegister()`, `PetscLogStageRegister()`
170: S*/
171: typedef struct _n_PetscLogRegistry *PetscLogRegistry;
173: /*S
174: PetscLogState - Interface for the shared state information used by `PetscLogHandler`s.
176: Most users will not need to reference a `PetscLogState` directly: global logging routines
177: like `PetscLogEventRegister()` and `PetscLogStagePush()` implicitly manipulate PETSc's global
178: logging state, `PetscLogGetState()`.
180: Level: developer
182: Notes:
183: `PetscLogState` holds a registry of events (`PetscLogStateEventRegister()`), stages
184: (`PetscLogStateStageRegister()`), and classes (`PetscLogStateClassRegister()`).
185: It keeps track of when the user has activated events (`PetscLogStateEventSetActive()`) and
186: stages (`PetscLogStateStageSetActive()`). It also keeps a stack of running stages
187: (`PetscLogStateStagePush()`, `PetscLogStateStagePop()`).
189: The struct defining `PetscLogState` is in a public header so that `PetscLogEventBegin()`,
190: `PetscLogEventEnd()`, `PetscLogObjectCreate()`, and `PetscLogObjectDestroy()` can be defined
191: as macros rather than function calls, but users are discouraged from directly accessing
192: the struct's fields, which are subject to change.
194: .seealso: [](ch_profiling), `PetscLogStateCreate()`, `PetscLogStateDestroy()`
195: S*/
196: typedef struct _n_PetscLogState *PetscLogState;
197: struct _n_PetscLogState {
198: PetscLogRegistry registry;
199: PetscBT active;
200: PetscIntStack stage_stack;
201: int current_stage;
202: int bt_num_stages;
203: int bt_num_events;
204: int refct;
205: };
207: /*S
208: PetscLogEventInfo - A registry entry about a logging event for `PetscLogState`.
210: Level: developer
212: .seealso: [](ch_profiling), `PetscLogEvent`, `PetscLogState`, `PetscLogStateEventGetInfo()`
213: S*/
214: typedef struct {
215: char *name; /* The name of this event */
216: PetscClassId classid; /* The class the event is associated with */
217: PetscBool collective; /* Flag this event as collective */
218: } PetscLogEventInfo;
220: /*S
221: PetscLogClassInfo - A registry entry about a class for `PetscLogState`.
223: Level: developer
225: .seealso: [](ch_profiling), `PetscLogClass`, `PetscLogState`, `PetscLogStateStageGetInfo()`
226: S*/
227: typedef struct {
228: char *name; /* The class name */
229: PetscClassId classid; /* The integer identifying this class */
230: } PetscLogClassInfo;
232: /*S
233: PetscLogStageInfo - A registry entry about a class for `PetscLogState`.
235: Level: developer
237: .seealso: [](ch_profiling), `PetscLogStage`, `PetscLogState`, `PetscLogStateClassGetInfo()`
238: S*/
239: typedef struct {
240: char *name; /* The stage name */
241: } PetscLogStageInfo;