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

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

 10:   Collective

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

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

 18:   Level: developer

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

 23:   See `PetscLogHandler` for example usage.

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

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

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

 44:   Logically collective

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

 49:   Level: developer

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

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

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

 74:   Logically collective

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

 80:   Level: developer

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

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

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

103:   Logically collective

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

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

111:   Level: developer

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

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

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

130:   Not collective

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

140:   Level: developer

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

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

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

158:   Not collective

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

168:   Level: developer

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

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

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

186:   Collective

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

193:   Level: developer

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

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

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

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

224:   Not collective

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

230:   Level: developer

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

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

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

248:   Not collective

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

254:   Level: developer

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

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

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

272:   Not collective

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

278:   Level: developer

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

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

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

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

299:   Not collective

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

305:   Level: developer

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

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

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

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

326:   Collective

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

332:   Level: developer

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

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

348:   Not collective, No Fortran Support

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

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

360:   Level: developer

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

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

377:   Not collective, No Fortran Support

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

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

387:   Level: developer

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

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

404:   Not Collective

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

410:   Level: developer

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

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

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

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

433:   Not Collective

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

439:   Level: developer

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

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

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

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

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

469:   Not Collective, No Fortran Support

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

477:   Level: developer

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

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

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

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

503:   Not Collective

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

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

513:   Level: developer

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

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

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

532:   Not collective

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

539:   Level: developer

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

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

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

559:   Not collective

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

566:   Level: developer

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

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

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

586:   Not collective

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

591:   Level: developer

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

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

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

611:   Not collective

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

616:   Level: developer

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

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

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

636:   Not collective

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

642:   Level: developer

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

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

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

661:   Not collective

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

668:   Level: developer

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

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

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

688:   Not collective

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

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

697:   Level: developer

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

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