1 #ifndef PETSCLOGTYPES_H 2 #define PETSCLOGTYPES_H 3 #include <petscsystypes.h> 4 5 /* SUBMANSEC = Profiling */ 6 7 /*S 8 PetscEventPerfInfo - statistics on how many times the event is used, how much time it takes, etc. 9 10 Level: advanced 11 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()`. 15 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 #endif 48 } PetscEventPerfInfo; 49 50 typedef struct _n_PetscIntStack *PetscIntStack; 51 52 /*MC 53 PetscLogEvent - id used to identify PETSc or user events which timed portions (blocks of executable) 54 code. 55 56 Level: intermediate 57 58 .seealso: [](ch_profiling), `PetscLogEventRegister()`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogStage` 59 M*/ 60 typedef int PetscLogEvent; 61 62 /*MC 63 PetscLogStage - id used to identify user stages (phases, sections) of runs - for logging 64 65 Level: intermediate 66 67 .seealso: [](ch_profiling), `PetscLogStageRegister()`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogEvent` 68 M*/ 69 typedef int PetscLogStage; 70 71 /*MC 72 PetscLogClass - id used to identify classes for logging purposes only. It 73 is not equal to its `PetscClassId`, which is the identifier used for other 74 purposes. 75 76 Level: developer 77 78 .seealso: [](ch_profiling), `PetscLogStateClassRegister()` 79 M*/ 80 typedef int PetscLogClass; 81 82 /*S 83 PetscLogHandler - Interface for performance logging. A log handler receives a `PetscLogState` that has 84 information about the events (`PetscLogEvent`) and stages (`PetscLogStage`) in the logging environment. 85 86 Example Usage: 87 .vb 88 #include <petscsys.h> 89 90 int main() { 91 UserCtx ctx; 92 PetscLogHandlerType handler_type; 93 94 PetscInitialize(...); 95 // ... fill in ctx 96 PetscLogHandlerCreate(PETSC_COMM_WORLD, &handler); 97 PetscLogHandlerSetType(handler, handler_type); 98 PetscLogHandlerStart(handler); // connect your handler to global logging state 99 // ... run code to be profiled 100 PetscLogHandlerStop(handler); // disconnect your handler from the global logging state 101 PetscLogHandlerView(handler, PETSC_VIEWER_STDOUT_WORLD); // view the results 102 PetscLogHandlerDestroy(&handler); 103 PetscFinalize(); 104 } 105 .ve 106 107 Level: developer 108 109 .seealso: [](ch_profiling), 110 `PetscLogHandlerCreate()`, 111 `PetscLogHandlerStart()`, `PetscLogHandlerStop()`, 112 `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()`, 113 `PetscLogHandlerSetState()`, `PetscLogHandlerGetState()`, 114 `PetscLogHandlerEventBegin()`, `PetscLogHandlerEventEnd()`, 115 `PetscLogHandlerEventSync()`, 116 `PetscLogHandlerObjectCreate()`, `PetscLogHandlerObjectDestroy()`, 117 `PetscLogHandlerStagePush()`, `PetscLogHandlerStagePop()`, 118 `PetscLogHandlerView()`, 119 `PetscLogHandlerDestroy()`, 120 S*/ 121 typedef struct _p_PetscLogHandler *PetscLogHandler; 122 123 /*J 124 PetscLogHandlerType - String with the name of a `PetscLogHandler` type 125 126 Level: Developer 127 128 Note: 129 Implementations included with PETSc include\: 130 + `PETSC_LOG_HANDLER_DEFAULT` (`PetscLogDefaultBegin()`) - formats data for PETSc's default summary (`PetscLogView()`) and data-dump (`PetscLogDump()`) formats. 131 . `PETSC_LOG_HANDLER_NESTED` (`PetscLogNestedBegin()`) - formats data for XML or flamegraph output 132 . `PETSC_LOG_HANDLER_TRACE` (`PetscLogTraceBegin()`) - traces profiling events in an output stream 133 . `PETSC_LOG_HANDLER_MPE` (`PetscLogMPEBegin()`) - outputs parallel performance visualization using MPE 134 . `PETSC_LOG_HANDLER_PERFSTUBS` (`PetscLogPerfstubsBegin()`) - outputs instrumentation data for PerfStubs/TAU 135 - `PETSC_LOG_HANDLER_LEGACY` (`PetscLogLegacyCallbacksBegin()`) - adapts legacy callbacks to the `PetscLogHandler` interface 136 137 .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogHandlerSetType()`, `PetscLogHandlerGetType()` 138 J*/ 139 typedef const char *PetscLogHandlerType; 140 141 #define PETSC_LOG_HANDLER_DEFAULT "default" 142 #define PETSC_LOG_HANDLER_NESTED "nested" 143 #define PETSC_LOG_HANDLER_TRACE "trace" 144 #define PETSC_LOG_HANDLER_MPE "mpe" 145 146 typedef struct _n_PetscLogRegistry *PetscLogRegistry; 147 148 /*S 149 PetscLogState - Interface for the shared state information used by `PetscLogHandler`s. It holds 150 a registry of events (`PetscLogStateEventRegister()`), stages (`PetscLogStateStageRegister()`), and 151 classes (`PetscLogStateClassRegister()`). It keeps track of when the user has activated 152 events (`PetscLogStateEventSetActive()`) and stages (`PetscLogStateStageSetActive()`). It 153 also keeps a stack of running stages (`PetscLogStateStagePush()`, `PetscLogStateStagePop()`). 154 155 Level: developer 156 157 Note: 158 The struct defining `PetscLogState` is in a public header so that `PetscLogEventBegin()`, 159 `PetscLogEventEnd()`, `PetscLogObjectCreate()`, and `PetscLogObjectDestroy()` can be defined 160 as macros rather than function calls, but users are discouraged from directly accessing 161 the struct's fields, which are subject to change. 162 163 .seealso: [](ch_profiling), `PetscLogStateCreate()`, `PetscLogStateDestroy()` 164 S*/ 165 typedef struct _n_PetscLogState *PetscLogState; 166 struct _n_PetscLogState { 167 PetscLogRegistry registry; 168 PetscBT active; 169 PetscIntStack stage_stack; 170 int current_stage; 171 int bt_num_stages; 172 int bt_num_events; 173 int refct; 174 }; 175 176 /*S 177 PetscLogEventInfo - A registry entry about a logging event for `PetscLogState`. 178 179 Level: developer 180 181 .seealso: [](ch_profiling), `PetscLogEvent`, `PetscLogState`, `PetscLogStateEventGetInfo()` 182 S*/ 183 typedef struct { 184 char *name; /* The name of this event */ 185 PetscClassId classid; /* The class the event is associated with */ 186 PetscBool collective; /* Flag this event as collective */ 187 } PetscLogEventInfo; 188 189 /*S 190 PetscLogClassInfo - A registry entry about a class for `PetscLogState`. 191 192 Level: developer 193 194 .seealso: [](ch_profiling), `PetscLogClass`, `PetscLogState`, `PetscLogStateStageGetInfo()` 195 S*/ 196 typedef struct { 197 char *name; /* The class name */ 198 PetscClassId classid; /* The integer identifying this class */ 199 } PetscLogClassInfo; 200 201 /*S 202 PetscLogStageInfo - A registry entry about a class for `PetscLogState`. 203 204 Level: developer 205 206 .seealso: [](ch_profiling), `PetscLogStage`, `PetscLogState`, `PetscLogStateClassGetInfo()` 207 S*/ 208 typedef struct _PetscLogStageInfo { 209 char *name; /* The stage name */ 210 } PetscLogStageInfo; 211 212 #endif 213