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: typedef struct _n_PetscIntStack *PetscIntStack;
53: /*MC
54: PetscLogEvent - id used to identify PETSc or user events which timed portions (blocks of executable)
55: code.
57: Level: intermediate
59: .seealso: [](ch_profiling), `PetscLogEventRegister()`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogStage`
60: M*/
61: typedef int PetscLogEvent;
63: /*MC
64: PetscLogStage - id used to identify user stages (phases, sections) of runs - for logging
66: Level: intermediate
68: .seealso: [](ch_profiling), `PetscLogStageRegister()`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogEvent`
69: M*/
70: typedef int PetscLogStage;
72: /*MC
73: PetscLogClass - id used to identify classes for logging purposes only. It
74: is not equal to its `PetscClassId`, which is the identifier used for other
75: purposes.
77: Level: developer
79: .seealso: [](ch_profiling), `PetscLogStateClassRegister()`
80: M*/
81: typedef int PetscLogClass;
83: /*S
84: PetscLogHandler - Interface for performance logging. A log handler receives a `PetscLogState` that has
85: information about the events (`PetscLogEvent`) and stages (`PetscLogStage`) in the logging environment.
86: When a handler is connected to PETSc's global logging stream (`PetscLogHandlerStart()`), it receives
87: updates about events (`PetscLogEventBegin()` / `PetscLogEventEnd()`), stages (`PetscLogStagePush()` /
88: `PetscLogStagePop()`), and objects (`PetscLogObjectCreate()` / `PetscLogObjectDestroy()`). After
89: collecting information the logger can summarize its data with `PetscLogHandlerView()`.
91: Example Usage:
92: .vb
93: #include <petscsys.h>
95: int main() {
96: UserCtx ctx;
97: PetscLogHandlerType handler_type;
99: PetscInitialize(...);
100: // ... fill in ctx
101: PetscLogHandlerCreate(PETSC_COMM_WORLD, &handler);
102: PetscLogHandlerSetType(handler, handler_type);
103: PetscLogHandlerStart(handler); // connect your handler to global logging state
104: // ... run code to be profiled
105: PetscLogHandlerStop(handler); // disconnect your handler from the global logging state
106: PetscLogHandlerView(handler, PETSC_VIEWER_STDOUT_WORLD); // view the results
107: PetscLogHandlerDestroy(&handler);
108: PetscFinalize();
109: }
110: .ve
112: Level: developer
114: .seealso: [](ch_profiling),
115: `PetscLogHandlerCreate()`,
116: `PetscLogHandlerStart()`, `PetscLogHandlerStop()`,
117: `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`,
118: `PetscLogHandlerSetState()`, `PetscLogHandlerGetState()`,
119: `PetscLogHandlerEventBegin()`, `PetscLogHandlerEventEnd()`,
120: `PetscLogHandlerEventSync()`,
121: `PetscLogHandlerObjectCreate()`, `PetscLogHandlerObjectDestroy()`,
122: `PetscLogHandlerStagePush()`, `PetscLogHandlerStagePop()`,
123: `PetscLogHandlerView()`,
124: `PetscLogHandlerDestroy()`,
125: S*/
126: typedef struct _p_PetscLogHandler *PetscLogHandler;
128: /*J
129: PetscLogHandlerType - String with the name of a `PetscLogHandler` type
131: Level: Developer
133: Note:
134: Implementations included with PETSc include\:
135: + `PETSCLOGHANDLERDEFAULT` (`PetscLogDefaultBegin()`) - formats data for PETSc's default summary (`PetscLogView()`) and data-dump (`PetscLogDump()`) formats.
136: . `PETSCLOGHANDLERNESTED` (`PetscLogNestedBegin()`) - formats data for XML or flamegraph output
137: . `PETSCLOGHANDLERTRACE` (`PetscLogTraceBegin()`) - traces profiling events in an output stream
138: . `PETSCLOGHANDLERMPE` (`PetscLogMPEBegin()`) - outputs parallel performance visualization using MPE
139: . `PETSCLOGHANDLERPERFSTUBS` (`PetscLogPerfstubsBegin()`) - outputs instrumentation data for PerfStubs/TAU
140: . `PETSCLOGHANDLERLEGACY` (`PetscLogLegacyCallbacksBegin()`) - adapts legacy callbacks to the `PetscLogHandler` interface
141: - `PETSCLOGHANDLERNVTX` - creates NVTX ranges for events that are visible in Nsight
142: - `PETSCLOGHANDLERROCTX` - creates ROCTx ranges for events that are visible in rocprof
144: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`
145: J*/
146: typedef const char *PetscLogHandlerType;
148: #define PETSCLOGHANDLERDEFAULT "default"
149: #define PETSCLOGHANDLERNESTED "nested"
150: #define PETSCLOGHANDLERTRACE "trace"
151: #define PETSCLOGHANDLERMPE "mpe"
152: #define PETSCLOGHANDLERPERFSTUBS "perfstubs"
153: #define PETSCLOGHANDLERLEGACY "legacy"
154: #define PETSCLOGHANDLERNVTX "nvtx"
155: #define PETSCLOGHANDLERROCTX "roctx"
157: typedef struct _n_PetscLogRegistry *PetscLogRegistry;
159: /*S
160: PetscLogState - Interface for the shared state information used by `PetscLogHandler`s.
162: Most users will not need to reference a `PetscLogState` directly: global logging routines
163: like `PetscLogEventRegister()` and `PetscLogStagePush()` implicitly manipulate PETSc's global
164: logging state, `PetscLogGetState()`.
166: Level: developer
168: Notes:
169: `PetscLogState` holds a registry of events (`PetscLogStateEventRegister()`), stages
170: (`PetscLogStateStageRegister()`), and classes (`PetscLogStateClassRegister()`).
171: It keeps track of when the user has activated events (`PetscLogStateEventSetActive()`) and
172: stages (`PetscLogStateStageSetActive()`). It also keeps a stack of running stages
173: (`PetscLogStateStagePush()`, `PetscLogStateStagePop()`).
175: The struct defining `PetscLogState` is in a public header so that `PetscLogEventBegin()`,
176: `PetscLogEventEnd()`, `PetscLogObjectCreate()`, and `PetscLogObjectDestroy()` can be defined
177: as macros rather than function calls, but users are discouraged from directly accessing
178: the struct's fields, which are subject to change.
180: .seealso: [](ch_profiling), `PetscLogStateCreate()`, `PetscLogStateDestroy()`
181: S*/
182: typedef struct _n_PetscLogState *PetscLogState;
183: struct _n_PetscLogState {
184: PetscLogRegistry registry;
185: PetscBT active;
186: PetscIntStack stage_stack;
187: int current_stage;
188: int bt_num_stages;
189: int bt_num_events;
190: int refct;
191: };
193: /*S
194: PetscLogEventInfo - A registry entry about a logging event for `PetscLogState`.
196: Level: developer
198: .seealso: [](ch_profiling), `PetscLogEvent`, `PetscLogState`, `PetscLogStateEventGetInfo()`
199: S*/
200: typedef struct {
201: char *name; /* The name of this event */
202: PetscClassId classid; /* The class the event is associated with */
203: PetscBool collective; /* Flag this event as collective */
204: } PetscLogEventInfo;
206: /*S
207: PetscLogClassInfo - A registry entry about a class for `PetscLogState`.
209: Level: developer
211: .seealso: [](ch_profiling), `PetscLogClass`, `PetscLogState`, `PetscLogStateStageGetInfo()`
212: S*/
213: typedef struct {
214: char *name; /* The class name */
215: PetscClassId classid; /* The integer identifying this class */
216: } PetscLogClassInfo;
218: /*S
219: PetscLogStageInfo - A registry entry about a class for `PetscLogState`.
221: Level: developer
223: .seealso: [](ch_profiling), `PetscLogStage`, `PetscLogState`, `PetscLogStateClassGetInfo()`
224: S*/
225: typedef struct {
226: char *name; /* The stage name */
227: } PetscLogStageInfo;