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