Actual source code: loghandler.c

      1: #include <petscviewer.h>
      2: #include <petsc/private/logimpl.h>
      3: #include <petsc/private/loghandlerimpl.h>
      4: #include <petsc/private/petscimpl.h>

      6: /*@
      7:   PetscLogHandlerCreate - Create a log handler for profiling events and stages.  PETSc
      8:   provides several implementations of `PetscLogHandler` that interface to different ways to
      9:   summarize or visualize profiling data: see `PetscLogHandlerType` for a list.

     11:   Collective

     13:   Input Parameter:
     14: . comm - the communicator for synchronizing and viewing events with this handler

     16:   Output Parameter:
     17: . handler - the `PetscLogHandler`

     19:   Level: developer

     21:   Notes:
     22:   This does not put the handler in use in PETSc's global logging system: use `PetscLogHandlerStart()` after creation.

     24:   See `PetscLogHandler` for example usage.

     26: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogHandlerSetType()`, `PetscLogHandlerStart()`, `PetscLogHandlerStop()`
     27: @*/
     28: PetscErrorCode PetscLogHandlerCreate(MPI_Comm comm, PetscLogHandler *handler)
     29: {
     30:   PetscLogHandler h;

     32:   PetscFunctionBegin;
     33:   *handler = NULL;
     34:   PetscCall(PetscLogHandlerPackageInitialize());
     35:   // We do not use PetscHeaderCreate() here because having PetscLogObjectCreate() run for PetscLogHandler would be very fragile
     36:   PetscCall(PetscNew(&h));
     37:   PetscCall(PetscHeaderCreate_Private((PetscObject)(h), PETSCLOGHANDLER_CLASSID, "PetscLogHandler", "Profile events, stages, and objects", "Profiling", comm, (PetscObjectDestroyFn *)PetscLogHandlerDestroy, (PetscObjectViewFn *)PetscLogHandlerView));
     38:   *handler = h;
     39:   PetscFunctionReturn(PETSC_SUCCESS);
     40: }

     42: /*@
     43:   PetscLogHandlerDestroy - Destroy a `PetscLogHandler`

     45:   Logically collective

     47:   Input Parameter:
     48: . handler - handler to be destroyed

     50:   Level: developer

     52: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogHandlerCreate()`
     53: @*/
     54: PetscErrorCode PetscLogHandlerDestroy(PetscLogHandler *handler)
     55: {
     56:   PetscLogHandler h;

     58:   PetscFunctionBegin;
     59:   if (!*handler) PetscFunctionReturn(PETSC_SUCCESS);
     60:   h        = *handler;
     61:   *handler = NULL;
     63:   if (--((PetscObject)h)->refct > 0) PetscFunctionReturn(PETSC_SUCCESS);
     64:   PetscTryTypeMethod(h, destroy);
     65:   PetscCall(PetscLogStateDestroy(&h->state));
     66:   // We do not use PetscHeaderDestroy() because having PetscLogObjectDestroy() run for PetscLgoHandler would be very fragile
     67:   PetscCall(PetscHeaderDestroy_Private((PetscObject)(h), PETSC_FALSE));
     68:   PetscCall(PetscFree(h));
     69:   PetscFunctionReturn(PETSC_SUCCESS);
     70: }

     72: /*@
     73:   PetscLogHandlerSetState - Set the logging state that provides the stream of events and stages for a log handler.

     75:   Logically collective

     77:   Input Parameters:
     78: + h     - the `PetscLogHandler`
     79: - state - the `PetscLogState`

     81:   Level: developer

     83:   Note:
     84:   Most users well not need to set a state explicitly: the global logging state (`PetscLogGetState()`) is set when calling `PetscLogHandlerStart()`

     86: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogState`, `PetscLogEventBegin()`, `PetscLogHandlerStart()`
     87: @*/
     88: PetscErrorCode PetscLogHandlerSetState(PetscLogHandler h, PetscLogState state)
     89: {
     90:   PetscFunctionBegin;
     92:   if (state) {
     93:     PetscAssertPointer(state, 2);
     94:     state->refct++;
     95:   }
     96:   PetscCall(PetscLogStateDestroy(&h->state));
     97:   h->state = state;
     98:   PetscFunctionReturn(PETSC_SUCCESS);
     99: }

    101: /*@
    102:   PetscLogHandlerGetState - Get the logging state that provides the stream of events and stages for a log handler.

    104:   Logically collective

    106:   Input Parameter:
    107: . h - the `PetscLogHandler`

    109:   Output Parameter:
    110: . state - the `PetscLogState`

    112:   Level: developer

    114:   Note:
    115:   For a log handler started with `PetscLogHandlerStart()`, this will be the PETSc global logging state (`PetscLogGetState()`)

    117: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogState`, `PetscLogEventBegin()`, `PetscLogHandlerStart()`
    118: @*/
    119: PetscErrorCode PetscLogHandlerGetState(PetscLogHandler h, PetscLogState *state)
    120: {
    121:   PetscFunctionBegin;
    123:   PetscAssertPointer(state, 2);
    124:   *state = h->state;
    125:   PetscFunctionReturn(PETSC_SUCCESS);
    126: }

    128: /*@
    129:   PetscLogHandlerEventBegin - Record the beginning of an event in a log handler

    131:   Not collective

    133:   Input Parameters:
    134: + h  - the `PetscLogHandler`
    135: . e  - a registered `PetscLogEvent`
    136: . o1 - `PetscObject` associated with the event (may be `NULL`)
    137: . o2 - `PetscObject` associated with the event (may be `NULL`)
    138: . o3 - `PetscObject` associated with the event (may be `NULL`)
    139: - o4 - `PetscObject` associated with the event (may be `NULL`)

    141:   Level: developer

    143:   Note:
    144:   Most users will use `PetscLogEventBegin()`, which will call this function for all handlers registered with `PetscLogHandlerStart()`

    146: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogEventSync()`, `PetscLogHandlerEventEnd()`, `PetscLogHandlerEventSync()`
    147: @*/
    148: PetscErrorCode PetscLogHandlerEventBegin(PetscLogHandler h, PetscLogEvent e, PetscObject o1, PetscObject o2, PetscObject o3, PetscObject o4)
    149: {
    150:   PetscFunctionBegin;
    152:   PetscTryTypeMethod(h, eventbegin, e, o1, o2, o3, o4);
    153:   PetscFunctionReturn(PETSC_SUCCESS);
    154: }

    156: /*@
    157:   PetscLogHandlerEventEnd - Record the end of an event in a log handler

    159:   Not collective

    161:   Input Parameters:
    162: + h  - the `PetscLogHandler`
    163: . e  - a registered `PetscLogEvent`
    164: . o1 - `PetscObject` associated with the event (may be `NULL`)
    165: . o2 - `PetscObject` associated with the event (may be `NULL`)
    166: . o3 - `PetscObject` associated with the event (may be `NULL`)
    167: - o4 - `PetscObject` associated with the event (may be `NULL`)

    169:   Level: developer

    171:   Note:
    172:   Most users will use `PetscLogEventEnd()`, which will call this function for all handlers registered with `PetscLogHandlerStart()`

    174: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogEventSync()`, `PetscLogHandlerEventBegin()`, `PetscLogHandlerEventSync()`
    175: @*/
    176: PetscErrorCode PetscLogHandlerEventEnd(PetscLogHandler h, PetscLogEvent e, PetscObject o1, PetscObject o2, PetscObject o3, PetscObject o4)
    177: {
    178:   PetscFunctionBegin;
    180:   PetscTryTypeMethod(h, eventend, e, o1, o2, o3, o4);
    181:   PetscFunctionReturn(PETSC_SUCCESS);
    182: }

    184: /*@
    185:   PetscLogHandlerEventSync - Synchronize a logging event

    187:   Collective

    189:   Input Parameters:
    190: + h    - the `PetscLogHandler`
    191: . e    - a registered `PetscLogEvent`
    192: - comm - the communicator over which to synchronize `e`

    194:   Level: developer

    196:   Note:
    197:   Most users will use `PetscLogEventSync()`, which will call this function for all handlers registered with `PetscLogHandlerStart()`

    199: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogEventBegin()`, `PetscLogEventEnd()`, `PetscLogEventSync()`, `PetscLogHandlerEventBegin()`, `PetscLogHandlerEventEnd()`
    200: @*/
    201: PetscErrorCode PetscLogHandlerEventSync(PetscLogHandler h, PetscLogEvent e, MPI_Comm comm)
    202: {
    203:   MPI_Comm    h_comm;
    204:   PetscMPIInt size;

    206:   PetscFunctionBegin;
    208:   PetscCall(PetscObjectGetComm((PetscObject)h, &h_comm));
    209:   PetscCallMPI(MPI_Comm_size(comm, &size));
    210:   if (comm == MPI_COMM_NULL || size == 1) PetscFunctionReturn(PETSC_SUCCESS); // nothing to sync
    211:   if (PetscDefined(USE_DEBUG)) {
    212:     PetscMPIInt h_comm_world, compare;
    213:     PetscCallMPI(MPI_Comm_compare(h_comm, PETSC_COMM_WORLD, &h_comm_world));
    214:     PetscCallMPI(MPI_Comm_compare(h_comm, comm, &compare));
    215:     // only synchronze if h->comm and comm have the same processes or h->comm is PETSC_COMM_WORLD
    216:     PetscCheck(h_comm_world != MPI_UNEQUAL || compare != MPI_UNEQUAL, comm, PETSC_ERR_SUP, "PetscLogHandlerSync does not support arbitrary mismatched communicators");
    217:   }
    218:   PetscTryTypeMethod(h, eventsync, e, comm);
    219:   PetscFunctionReturn(PETSC_SUCCESS);
    220: }

    222: /*@
    223:   PetscLogHandlerObjectCreate - Record the creation of an object in a log handler.

    225:   Not collective

    227:   Input Parameters:
    228: + h   - the `PetscLogHandler`
    229: - obj - a newly created `PetscObject`

    231:   Level: developer

    233:   Notes:
    234:   Most users will use `PetscLogObjectCreate()`, which will call this function for all handlers registered with `PetscLogHandlerStart()`.

    236: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogObjectCreate()`, `PetscLogObjectDestroy()`, `PetscLogHandlerObjectDestroy()`
    237: @*/
    238: PetscErrorCode PetscLogHandlerObjectCreate(PetscLogHandler h, PetscObject obj)
    239: {
    240:   PetscFunctionBegin;
    242:   PetscTryTypeMethod(h, objectcreate, obj);
    243:   PetscFunctionReturn(PETSC_SUCCESS);
    244: }

    246: /*@
    247:   PetscLogHandlerObjectDestroy - Record the destruction of an object in a log handler.

    249:   Not collective

    251:   Input Parameters:
    252: + h   - the `PetscLogHandler`
    253: - obj - a newly created `PetscObject`

    255:   Level: developer

    257:   Notes:
    258:   Most users will use `PetscLogObjectDestroy()`, which will call this function for all handlers registered with `PetscLogHandlerStart()`.

    260: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogObjectCreate()`, `PetscLogObjectDestroy()`, `PetscLogHandlerObjectCreate()`
    261: @*/
    262: PetscErrorCode PetscLogHandlerObjectDestroy(PetscLogHandler h, PetscObject obj)
    263: {
    264:   PetscFunctionBegin;
    266:   PetscTryTypeMethod(h, objectdestroy, obj);
    267:   PetscFunctionReturn(PETSC_SUCCESS);
    268: }

    270: /*@
    271:   PetscLogHandlerStagePush - Begin a new logging stage in a log handler.

    273:   Not collective

    275:   Input Parameters:
    276: + h     - the `PetscLogHandler`
    277: - stage - a registered `PetscLogStage`

    279:   Level: developer

    281:   Notes:
    282:   Most users will use `PetscLogStagePush()`, which will call this function for all handlers registered with `PetscLogHandlerStart()`.

    284:   This function is called right before the stage is pushed for the handler's `PetscLogState`, so `PetscLogStateGetCurrentStage()`
    285:   can be used to see what the previous stage was.

    287: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogHandlerStagePop()`
    288: @*/
    289: PetscErrorCode PetscLogHandlerStagePush(PetscLogHandler h, PetscLogStage stage)
    290: {
    291:   PetscFunctionBegin;
    293:   PetscTryTypeMethod(h, stagepush, stage);
    294:   PetscFunctionReturn(PETSC_SUCCESS);
    295: }

    297: /*@
    298:   PetscLogHandlerStagePop - End the current logging stage in a log handler.

    300:   Not collective

    302:   Input Parameters:
    303: + h     - the `PetscLogHandler`
    304: - stage - a registered `PetscLogStage`

    306:   Level: developer

    308:   Notes:
    309:   Most users will use `PetscLogStagePop()`, which will call this function for all handlers registered with `PetscLogHandlerStart()`.

    311:   This function is called right after the stage is popped for the handler's `PetscLogState`, so `PetscLogStateGetCurrentStage()`
    312:   can be used to see what the next stage will be.

    314: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogHandlerStagePush()`
    315: @*/
    316: PetscErrorCode PetscLogHandlerStagePop(PetscLogHandler h, PetscLogStage stage)
    317: {
    318:   PetscFunctionBegin;
    320:   PetscTryTypeMethod(h, stagepop, stage);
    321:   PetscFunctionReturn(PETSC_SUCCESS);
    322: }

    324: /*@
    325:   PetscLogHandlerView - View the data recorded in a log handler.

    327:   Collective

    329:   Input Parameters:
    330: + h      - the `PetscLogHandler`
    331: - viewer - the `PetscViewer`

    333:   Level: developer

    335: .seealso: [](ch_profiling), `PetscLogHandler`, `PetscLogView()`
    336: @*/
    337: PetscErrorCode PetscLogHandlerView(PetscLogHandler h, PetscViewer viewer)
    338: {
    339:   PetscFunctionBegin;
    342:   PetscTryTypeMethod(h, view, viewer);
    343:   PetscFunctionReturn(PETSC_SUCCESS);
    344: }

    346: /*@C
    347:   PetscLogHandlerGetEventPerfInfo - Get a direct reference to the `PetscEventPerfInfo` of a stage and event

    349:   Not collective, No Fortran Support

    351:   Input Parameters:
    352: + handler - a `PetscLogHandler`
    353: . stage   - a `PetscLogStage` (or `PETSC_DEFAULT` for the current stage)
    354: - event   - a `PetscLogEvent`

    356:   Output Parameter:
    357: . event_info - a pointer to a performance log for `event` during `stage` (or `NULL` if this handler does not use
    358:               `PetscEventPerfInfo` to record performance data); writing to `event_info` will change the record in
    359:               `handler`

    361:   Level: developer

    363: .seealso: [](ch_profiling), `PetscLogEventGetPerfInfo()`, `PETSCLOGHANDLERDEFAULT`
    364: @*/
    365: PetscErrorCode PetscLogHandlerGetEventPerfInfo(PetscLogHandler handler, PetscLogStage stage, PetscLogEvent event, PetscEventPerfInfo **event_info)
    366: {
    367:   PetscFunctionBegin;
    369:   PetscAssertPointer(event_info, 4);
    370:   *event_info = NULL;
    371:   PetscTryMethod(handler, "PetscLogHandlerGetEventPerfInfo_C", (PetscLogHandler, PetscLogStage, PetscLogEvent, PetscEventPerfInfo **), (handler, stage, event, event_info));
    372:   PetscFunctionReturn(PETSC_SUCCESS);
    373: }

    375: /*@C
    376:   PetscLogHandlerGetStagePerfInfo - Get a direct reference to the `PetscEventPerfInfo` of a stage

    378:   Not collective, No Fortran Support

    380:   Input Parameters:
    381: + handler - a `PetscLogHandler`
    382: - stage   - a `PetscLogStage` (or `PETSC_DEFAULT` for the current stage)

    384:   Output Parameter:
    385: . stage_info - a pointer to a performance log for `stage` (or `NULL` if this handler does not use `PetscEventPerfInfo`
    386:                to record performance data); writing to `stage_info` will change the record in `handler`

    388:   Level: developer

    390: .seealso: [](ch_profiling), `PetscLogEventGetPerfInfo()`, `PETSCLOGHANDLERDEFAULT`
    391: @*/
    392: PetscErrorCode PetscLogHandlerGetStagePerfInfo(PetscLogHandler handler, PetscLogStage stage, PetscEventPerfInfo **stage_info)
    393: {
    394:   PetscFunctionBegin;
    396:   PetscAssertPointer(stage_info, 3);
    397:   *stage_info = NULL;
    398:   PetscTryMethod(handler, "PetscLogHandlerGetStagePerfInfo_C", (PetscLogHandler, PetscLogStage, PetscEventPerfInfo **), (handler, stage, stage_info));
    399:   PetscFunctionReturn(PETSC_SUCCESS);
    400: }

    402: /*@
    403:   PetscLogHandlerSetLogActions - Determines whether actions are logged for a log handler.

    405:   Not Collective

    407:   Input Parameters:
    408: + handler - a `PetscLogHandler`
    409: - flag    - `PETSC_TRUE` if actions are to be logged (ignored if `handler` does not log actions)

    411:   Level: developer

    413:   Notes:
    414:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    415:   `PetscLogSetLogActions()` to call this function for the default log handler that is connected to the global
    416:   logging state (`PetscLogGetState()`).

    418:   Logging of actions continues to consume more memory as the program runs. Long running programs should consider
    419:   turning this feature off.

    421: .seealso: [](ch_profiling), `PetscLogSetLogActions()`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogGetDefaultHandler()`
    422: @*/
    423: PetscErrorCode PetscLogHandlerSetLogActions(PetscLogHandler handler, PetscBool flag)
    424: {
    425:   PetscFunctionBegin;
    427:   PetscTryMethod(handler, "PetscLogHandlerSetLogActions_C", (PetscLogHandler, PetscBool), (handler, flag));
    428:   PetscFunctionReturn(PETSC_SUCCESS);
    429: }

    431: /*@
    432:   PetscLogHandlerSetLogObjects - Determines whether objects are logged for a log handler.

    434:   Not Collective

    436:   Input Parameters:
    437: + handler - a `PetscLogHandler`
    438: - flag    - `PETSC_TRUE` if objects are to be logged (ignored if `handler` does not log objects)

    440:   Level: developer

    442:   Notes:
    443:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    444:   `PetscLogSetLogObjects()` to call this function for the default log handler that is connected to the global
    445:   logging state (`PetscLogGetState()`).

    447:   Logging of objects continues to consume more memory as the program runs. Long running programs should consider
    448:   turning this feature off.

    450: .seealso: [](ch_profiling), `PetscLogSetLogObjects()`, `PetscLogStagePush()`, `PetscLogStagePop()`, `PetscLogGetDefaultHandler()`
    451: @*/
    452: PetscErrorCode PetscLogHandlerSetLogObjects(PetscLogHandler handler, PetscBool flag)
    453: {
    454:   PetscFunctionBegin;
    456:   PetscTryMethod(handler, "PetscLogHandlerSetLogObjects_C", (PetscLogHandler, PetscBool), (handler, flag));
    457:   PetscFunctionReturn(PETSC_SUCCESS);
    458: }

    460: PetscErrorCode PetscLogHandlerLogObjectState_Internal(PetscLogHandler handler, PetscObject obj, const char format[], va_list argp)
    461: {
    462:   PetscFunctionBegin;
    463:   PetscTryMethod(handler, "PetscLogHandlerLogObjectState_C", (PetscLogHandler, PetscObject, const char *, va_list), (handler, obj, format, argp));
    464:   PetscFunctionReturn(PETSC_SUCCESS);
    465: }

    467: /*@C
    468:   PetscLogHandlerLogObjectState - Record information about an object with the default log handler

    470:   Not Collective, No Fortran Support

    472:   Input Parameters:
    473: + handler - a `PetscLogHandler`
    474: . obj     - the `PetscObject`
    475: . format  - a printf-style format string
    476: - ...     - printf arguments to format

    478:   Level: developer

    480:   Note:
    481:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    482:   `PetscLogObjectState()` to call this function for the default log handler that is connected to the global
    483:   logging state (`PetscLogGetState()`).

    485: .seealso: [](ch_profiling), `PetscLogObjectState`, `PetscLogObjectCreate()`, `PetscLogObjectDestroy()`, `PetscLogGetDefaultHandler()`
    486: @*/
    487: PetscErrorCode PetscLogHandlerLogObjectState(PetscLogHandler handler, PetscObject obj, const char format[], ...)
    488: {
    489:   va_list argp;

    491:   PetscFunctionBegin;
    494:   PetscAssertPointer(format, 3);
    495:   va_start(argp, format);
    496:   PetscCall(PetscLogHandlerLogObjectState_Internal(handler, obj, format, argp));
    497:   va_end(argp);
    498:   PetscFunctionReturn(PETSC_SUCCESS);
    499: }

    501: /*@
    502:   PetscLogHandlerGetNumObjects - Get the number of objects that were logged with a log handler

    504:   Not Collective

    506:   Input Parameter:
    507: . handler - a `PetscLogHandler`

    509:   Output Parameter:
    510: . num_objects - the number of objects whose creations and destructions were logged with `handler`
    511:                 (`PetscLogHandlerObjectCreate()` / `PetscLogHandlerObjectDestroy()`), or -1
    512:                 if the handler does not keep track of this number.

    514:   Level: developer

    516:   Note:
    517:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.

    519: .seealso: [](ch_profiling)
    520: @*/
    521: PetscErrorCode PetscLogHandlerGetNumObjects(PetscLogHandler handler, PetscInt *num_objects)
    522: {
    523:   PetscFunctionBegin;
    525:   PetscAssertPointer(num_objects, 2);
    526:   PetscTryMethod(handler, "PetscLogHandlerGetNumObjects_C", (PetscLogHandler, PetscInt *), (handler, num_objects));
    527:   PetscFunctionReturn(PETSC_SUCCESS);
    528: }

    530: /*@
    531:   PetscLogHandlerEventDeactivatePush - Temporarily deactivate a logging event for a log handler

    533:   Not collective

    535:   Input Parameters:
    536: + handler - a `PetscLogHandler`
    537: . stage   - a `PetscLogStage` (or `PETSC_DEFAULT` for the current stage)
    538: - event   - a `PetscLogEvent`

    540:   Level: developer

    542:   Note:
    543:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    544:   `PetscLogEventDeactivatePush()` to call this function for the default log handler that is connected to the global
    545:   logging state (`PetscLogGetState()`).

    547: .seealso: [](ch_profiling), `PetscLogHandlerEventDeactivatePop()`
    548: @*/
    549: PetscErrorCode PetscLogHandlerEventDeactivatePush(PetscLogHandler handler, PetscLogStage stage, PetscLogEvent event)
    550: {
    551:   PetscFunctionBegin;
    553:   PetscTryMethod(handler, "PetscLogHandlerEventDeactivatePush_C", (PetscLogHandler, PetscLogStage, PetscLogEvent), (handler, stage, event));
    554:   PetscFunctionReturn(PETSC_SUCCESS);
    555: }

    557: /*@
    558:   PetscLogHandlerEventDeactivatePop - Undo temporary deactivation a logging event for a log handler

    560:   Not collective

    562:   Input Parameters:
    563: + handler - a `PetscLogHandler`
    564: . stage   - a `PetscLogStage` (or `PETSC_DEFAULT` for the current stage)
    565: - event   - a `PetscLogEvent`

    567:   Level: developer

    569:   Note:
    570:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    571:   `PetscLogEventDeactivatePop()` to call this function for the default log handler that is connected to the global
    572:   logging state (`PetscLogGetState()`).

    574: .seealso: [](ch_profiling), `PetscLogHandlerEventDeactivatePush()`
    575: @*/
    576: PetscErrorCode PetscLogHandlerEventDeactivatePop(PetscLogHandler handler, PetscLogStage stage, PetscLogEvent event)
    577: {
    578:   PetscFunctionBegin;
    580:   PetscTryMethod(handler, "PetscLogHandlerEventDeactivatePop_C", (PetscLogHandler, PetscLogStage, PetscLogEvent), (handler, stage, event));
    581:   PetscFunctionReturn(PETSC_SUCCESS);
    582: }

    584: /*@
    585:   PetscLogHandlerEventsPause - Put event logging into "paused" mode (see `PetscLogEventsPause()` for details.) for a log handler

    587:   Not collective

    589:   Input Parameter:
    590: . handler - a `PetscLogHandler`

    592:   Level: developer

    594:   Note:
    595:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    596:   `PetscLogEventsPause()` to call this function for the default log handler that is connected to the global
    597:   logging state (`PetscLogGetState()`).

    599: .seealso: [](ch_profiling), `PetscLogHandlerEventsResume()`
    600: @*/
    601: PetscErrorCode PetscLogHandlerEventsPause(PetscLogHandler handler)
    602: {
    603:   PetscFunctionBegin;
    605:   PetscTryMethod(handler, "PetscLogHandlerEventsPause_C", (PetscLogHandler), (handler));
    606:   PetscFunctionReturn(PETSC_SUCCESS);
    607: }

    609: /*@
    610:   PetscLogHandlerEventsResume - Resume event logging that had been put into "paused" mode (see `PetscLogEventsPause()` for details.) for a log handler

    612:   Not collective

    614:   Input Parameter:
    615: . handler - a `PetscLogHandler`

    617:   Level: developer

    619:   Note:
    620:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    621:   `PetscLogEventsResume()` to call this function for the default log handler that is connected to the global
    622:   logging state (`PetscLogGetState()`).

    624: .seealso: [](ch_profiling), `PetscLogHandlerEventsPause()`
    625: @*/
    626: PetscErrorCode PetscLogHandlerEventsResume(PetscLogHandler handler)
    627: {
    628:   PetscFunctionBegin;
    630:   PetscTryMethod(handler, "PetscLogHandlerEventsResume_C", (PetscLogHandler), (handler));
    631:   PetscFunctionReturn(PETSC_SUCCESS);
    632: }

    634: /*@
    635:   PetscLogHandlerDump - Dump the records of a log handler to file

    637:   Not collective

    639:   Input Parameters:
    640: + handler - a `PetscLogHandler`
    641: - sname   - the name of the file to dump log data to

    643:   Level: developer

    645:   Note:
    646:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    647:   `PetscLogDump()` to call this function for the default log handler that is connected to the global
    648:   logging state (`PetscLogGetState()`).

    650: .seealso: [](ch_profiling)
    651: @*/
    652: PetscErrorCode PetscLogHandlerDump(PetscLogHandler handler, const char sname[])
    653: {
    654:   PetscFunctionBegin;
    655:   PetscTryMethod(handler, "PetscLogHandlerDump_C", (PetscLogHandler, const char *), (handler, sname));
    656:   PetscFunctionReturn(PETSC_SUCCESS);
    657: }

    659: /*@
    660:   PetscLogHandlerStageSetVisible - Set the visibility of logging stage in `PetscLogHandlerView()` for a log handler

    662:   Not collective

    664:   Input Parameters:
    665: + handler   - a `PetscLogHandler`
    666: . stage     - a `PetscLogStage`
    667: - isVisible - the visibility flag, `PETSC_TRUE` to print, else `PETSC_FALSE` (defaults to `PETSC_TRUE`)

    669:   Level: developer

    671:   Note:
    672:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    673:   `PetscLogStageSetVisible()` to call this function for the default log handler that is connected to the global
    674:   logging state (`PetscLogGetState()`).

    676: .seealso: [](ch_profiling), `PetscLogHandlerStageGetVisible()`
    677: @*/
    678: PetscErrorCode PetscLogHandlerStageSetVisible(PetscLogHandler handler, PetscLogStage stage, PetscBool isVisible)
    679: {
    680:   PetscFunctionBegin;
    682:   PetscTryMethod(handler, "PetscLogHandlerStageSetVisible_C", (PetscLogHandler, PetscLogStage, PetscBool), (handler, stage, isVisible));
    683:   PetscFunctionReturn(PETSC_SUCCESS);
    684: }

    686: /*@
    687:   PetscLogHandlerStageGetVisible - Get the visibility of logging stage in `PetscLogHandlerView()` for a log handler

    689:   Not collective

    691:   Input Parameters:
    692: + handler - a `PetscLogHandler`
    693: - stage   - a `PetscLogStage`

    695:   Output Parameter:
    696: . isVisible - the visibility flag, `PETSC_TRUE` to print, else `PETSC_FALSE` (defaults to `PETSC_TRUE`)

    698:   Level: developer

    700:   Note:
    701:   The default log handler `PETSCLOGHANDLERDEFAULT` implements this function, but others generally do not.  You can use
    702:   `PetscLogStageGetVisible()` to call this function for the default log handler that is connected to the global
    703:   logging state (`PetscLogGetState()`).

    705: .seealso: [](ch_profiling), `PetscLogHandlerStageSetVisible()`
    706: @*/
    707: PetscErrorCode PetscLogHandlerStageGetVisible(PetscLogHandler handler, PetscLogStage stage, PetscBool *isVisible)
    708: {
    709:   PetscFunctionBegin;
    711:   PetscTryMethod(handler, "PetscLogHandlerStageGetVisible_C", (PetscLogHandler, PetscLogStage, PetscBool *), (handler, stage, isVisible));
    712:   PetscFunctionReturn(PETSC_SUCCESS);
    713: }