1 #include <petsc/private/viewerimpl.h> /*I "petscviewer.h" I*/ 2 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 6 7 Collective 8 9 Input Parameters: 10 + viewer - the `PetscViewer` to be reproduced 11 - comm - the sub communicator to use 12 13 Output Parameter: 14 . outviewer - new `PetscViewer` 15 16 Level: advanced 17 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()`. 23 24 Call `PetscViewerRestoreSubViewer()` to destroy this `PetscViewer`, NOT `PetscViewerDestroy()` 25 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. 29 30 Between the calls to `PetscViewerGetSubViewer()` and `PetscViewerRestoreSubViewer()` the original 31 viewer should not be used 32 33 `PETSCVIEWERDRAW` and `PETSCVIEWERBINARY` only support returning a singleton viewer on MPI rank 0, 34 all other ranks will return a `NULL` viewer 35 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. 40 41 It would be nice if the call to `PetscViewerFlush()` was not required and was handled by 42 `PetscViewerRestoreSubViewer()` 43 44 .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerRestoreSubViewer()` 45 @*/ 46 PetscErrorCode PetscViewerGetSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer) 47 { 48 PetscFunctionBegin; 49 PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 50 PetscAssertPointer(outviewer, 3); 51 PetscUseTypeMethod(viewer, getsubviewer, comm, outviewer); 52 PetscFunctionReturn(PETSC_SUCCESS); 53 } 54 55 /*@C 56 PetscViewerRestoreSubViewer - Restores a `PetscViewer` obtained with `PetscViewerGetSubViewer()`. 57 58 Collective 59 60 Input Parameters: 61 + viewer - the `PetscViewer` that was reproduced 62 . comm - the sub communicator 63 - outviewer - the subviewer to be returned 64 65 Level: advanced 66 67 .seealso: [](sec_viewers), `PetscViewer`, `PetscViewerSocketOpen()`, `PetscViewerASCIIOpen()`, `PetscViewerDrawOpen()`, `PetscViewerGetSubViewer()` 68 @*/ 69 PetscErrorCode PetscViewerRestoreSubViewer(PetscViewer viewer, MPI_Comm comm, PetscViewer *outviewer) 70 { 71 PetscFunctionBegin; 72 PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 73 74 PetscUseTypeMethod(viewer, restoresubviewer, comm, outviewer); 75 PetscFunctionReturn(PETSC_SUCCESS); 76 } 77