Date: 2025-03-28T21:10:40+00:00

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;