Actual source code: dupl.c


  2: #include <petsc/private/viewerimpl.h>

  4: /*@C
  5:    PetscViewerGetSubViewer - Creates a new `PetscViewer` (same type as the old)
  6:     that lives on a subcommunicator of the original viewer's communicator

  8:     Collective

 10:    Input Parameter:
 11: .  viewer - the `PetscViewer` to be reproduced

 13:    Output Parameter:
 14: .  outviewer - new `PetscViewer`

 16:    Level: advanced

 18:    Notes:
 19:     The output of the subviewers is synchronized against the original viewer. For example, if a
 20:     viewer on two MPI processes is decomposed into two subviewers, the output from the first viewer is
 21:     all printed before the output from the second viewer. You must call `PetscViewerFlush()` after
 22:     the call to `PetscViewerRestoreSubViewer()`.

 24:     Call `PetscViewerRestoreSubViewer()` to destroy this `PetscViewer`, NOT `PetscViewerDestroy()`

 26:      This is most commonly used to view a sequential object that is part of a
 27:     parallel object. For example `PCView()` on a `PCBJACOBI` could use this to obtain a
 28:     `PetscViewer` that is used with the sequential `KSP` on one block of the preconditioner.

 30:     Between the calls to `PetscViewerGetSubViewer()` and `PetscViewerRestoreSubViewer()` the original
 31:     viewer should not be used

 33:     `PETSCVIEWERDRAW` and `PETSCVIEWERBINARY` only support returning a singleton viewer on MPI rank 0,
 34:     all other ranks will return a `NULL` viewer

 36:   Developer Notes:
 37:     There is currently incomplete error checking to ensure the user does not use the original viewer between the
 38:     the calls to `PetscViewerGetSubViewer()` and `PetscViewerRestoreSubViewer()`. If the user does there
 39:     could be errors in the viewing that go undetected or crash the code.

 41:     It would be nice if the call to `PetscViewerFlush()` was not required and was handled by
 42:     `PetscViewerRestoreSubViewer()`

 44: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerRestoreSubViewer()`
 45: @*/
 46: PetscErrorCode PetscViewerGetSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer)
 47: {
 48:   PetscFunctionBegin;
 51:   PetscUseTypeMethod(viewer, getsubviewer, comm, outviewer);
 52:   PetscFunctionReturn(PETSC_SUCCESS);
 53: }

 55: /*@C
 56:    PetscViewerRestoreSubViewer - Restores a  `PetscViewer` obtained with `PetscViewerGetSubViewer()`.

 58:     Collective

 60:    Input Parameters:
 61: +  viewer - the `PetscViewer` that was reproduced
 62: -  outviewer - the subviewer to be returned

 64:    Level: advanced

 66: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerGetSubViewer()`
 67: @*/
 68: PetscErrorCode PetscViewerRestoreSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer)
 69: {
 70:   PetscFunctionBegin;

 73:   PetscUseTypeMethod(viewer, restoresubviewer, comm, outviewer);
 74:   PetscFunctionReturn(PETSC_SUCCESS);
 75: }