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, (PetscObjectDestroyFunction)PetscLogHandlerDestroy, (PetscObjectViewFunction)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

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

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

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), `PetcLogObjectState`, `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: }