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

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

  7:   Collective

  9:   Input Parameters:
 10: + viewer - the `PetscViewer` to be reproduced
 11: - comm   - the sub communicator to use

 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;
 50:   PetscAssertPointer(outviewer, 3);
 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: . comm      - the sub communicator
 63: - outviewer - the subviewer to be returned

 65:   Level: advanced

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

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