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. 22 23 Call `PetscViewerRestoreSubViewer()` to destroy this `PetscViewer`, NOT `PetscViewerDestroy()` 24 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. 28 29 `PetscViewerFlush()` is run automatically at the beginning of `PetscViewerGetSubViewer()` and with `PetscViewerRestoreSubViewer()` 30 for `PETSCVIEWERASCII` 31 32 `PETSCVIEWERDRAW` and `PETSCVIEWERBINARY` only support returning a singleton viewer on MPI rank 0, 33 all other ranks will return a `NULL` viewer 34 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`. 37 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 47 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. 52 53 Complex use of this functionality with `PETSCVIEWERASCII` can result in output in unexpected order. This seems unavoidable. 54 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; 61 PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 62 PetscAssertPointer(outviewer, 3); 63 PetscUseTypeMethod(viewer, getsubviewer, comm, outviewer); 64 PetscFunctionReturn(PETSC_SUCCESS); 65 } 66 67 /*@C 68 PetscViewerRestoreSubViewer - Restores a `PetscViewer` obtained with `PetscViewerGetSubViewer()`. 69 70 Collective 71 72 Input Parameters: 73 + viewer - the `PetscViewer` that was reproduced 74 . comm - the sub communicator 75 - outviewer - the subviewer to be returned 76 77 Level: advanced 78 79 Notes: 80 Automatically runs `PetscViewerFlush()` on `outviewer` 81 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`. 84 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; 91 PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 1); 92 93 PetscUseTypeMethod(viewer, restoresubviewer, comm, outviewer); 94 PetscFunctionReturn(PETSC_SUCCESS); 95 } 96