Actual source code: dupl.c

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

      3: /*@
      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.

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

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

     29:   `PetscViewerFlush()` is run automatically at the beginning of `PetscViewerGetSubViewer()` and with `PetscViewerRestoreSubViewer()`
     30:   for `PETSCVIEWERASCII`

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

     35:   Must be called by all MPI processes that share `viewer`, for processes that are not of interest you can pass
     36:   `PETSC_COMM_SELF`.

     38:   For `PETSCVIEWERASCII` the viewers behavior is as follows\:
     39: .vb
     40:   Recursive calls are allowed
     41:   A call to `PetscViewerASCIIPrintf()` on a subviewer results in output for the first MPI process in the `outviewer` only
     42:   Calls to  `PetscViewerASCIIPrintf()` and `PetscViewerASCIISynchronizedPrintf()` are immediately passed up through all
     43:   the parent viewers to the higher most parent with `PetscViewerASCIISynchronizedPrintf()` where they are immediately
     44:   printed on the first MPI process or stashed on the other processes.
     45:   At the higher most `PetscViewerRestoreSubViewer()` the viewer is automatically flushed with `PetscViewerFlush()`
     46: .ve

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

     53:   Complex use of this functionality with `PETSCVIEWERASCII` can result in output in unexpected order. This seems unavoidable.

     55: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`,
     56:           `PetscViewerFlush()`, `PetscViewerRestoreSubViewer()`
     57: @*/
     58: PetscErrorCode PetscViewerGetSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer)
     59: {
     60:   PetscFunctionBegin;
     62:   PetscAssertPointer(outviewer, 3);
     63:   PetscUseTypeMethod(viewer, getsubviewer, comm, outviewer);
     64:   PetscFunctionReturn(PETSC_SUCCESS);
     65: }

     67: /*@
     68:   PetscViewerRestoreSubViewer - Restores a  `PetscViewer` obtained with `PetscViewerGetSubViewer()`.

     70:   Collective

     72:   Input Parameters:
     73: + viewer    - the `PetscViewer` that was reproduced
     74: . comm      - the sub communicator
     75: - outviewer - the subviewer to be returned

     77:   Level: advanced

     79:   Notes:
     80:   Automatically runs `PetscViewerFlush()` on `outviewer`

     82:   Must be called by all MPI processes that share `viewer`, for processes that are not of interest you can pass
     83:   `PETSC_COMM_SELF`.

     85: .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerGetSubViewer()`,
     86:           `PetscViewerFlush()`
     87: @*/
     88: PetscErrorCode PetscViewerRestoreSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer)
     89: {
     90:   PetscFunctionBegin;

     93:   PetscUseTypeMethod(viewer, restoresubviewer, comm, outviewer);
     94:   PetscFunctionReturn(PETSC_SUCCESS);
     95: }