1 2 /* 3 Provides utility routines for manulating any type of PETSc object. 4 */ 5 #include <petsc/private/petscimpl.h> /*I "petscsys.h" I*/ 6 7 /*@C 8 PetscObjectComm - Gets the MPI communicator for any `PetscObject` regardless of the type. 9 10 Not Collective 11 12 Input Parameter: 13 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be 14 cast with a (`PetscObject`), for example, `PetscObjectComm`((`PetscObject`)mat,...); 15 16 Level: advanced 17 18 Note: 19 Returns the MPI communicator or `MPI_COMM_NULL` if `obj` is not valid. 20 21 This is one of the rare PETSc routines that does not return an error code. Use `PetscObjectGetComm()` 22 when appropriate for error handling. 23 24 .seealso: `PetscObject`, `PetscObjectGetComm()` 25 @*/ 26 MPI_Comm PetscObjectComm(PetscObject obj) 27 { 28 return obj ? obj->comm : MPI_COMM_NULL; 29 } 30 31 /*@C 32 PetscObjectGetComm - Gets the MPI communicator for any `PetscObject`, 33 regardless of the type. 34 35 Not Collective 36 37 Input Parameter: 38 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be 39 cast with a (`PetscObject`), for example, 40 `PetscObjectGetComm`((`PetscObject`)mat,&comm); 41 42 Output Parameter: 43 . comm - the MPI communicator 44 45 Level: advanced 46 47 .seealso: `PetscObject`, `PetscObjectComm()` 48 @*/ 49 PetscErrorCode PetscObjectGetComm(PetscObject obj, MPI_Comm *comm) 50 { 51 PetscFunctionBegin; 52 PetscValidHeader(obj, 1); 53 PetscValidPointer(comm, 2); 54 *comm = obj->comm; 55 PetscFunctionReturn(PETSC_SUCCESS); 56 } 57 58 /*@ 59 PetscObjectGetTabLevel - Gets the number of tabs that `PETSCVIEWERASCII` output for that object uses 60 61 Not Collective 62 63 Input Parameter: 64 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be 65 cast with a (`PetscObject`), for example, 66 `PetscObjectGetTabLevel`((`PetscObject`)mat,&tab); 67 68 Output Parameter: 69 . tab - the number of tabs 70 71 Level: developer 72 73 Note: 74 This is used to manage the output from options that are embedded in other objects. For example 75 the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects 76 is very clear. 77 78 .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectSetTabLevel()`, `PETSCVIEWERASCII`, `PetscObject` 79 @*/ 80 PetscErrorCode PetscObjectGetTabLevel(PetscObject obj, PetscInt *tab) 81 { 82 PetscFunctionBegin; 83 PetscValidHeader(obj, 1); 84 PetscValidIntPointer(tab, 2); 85 *tab = obj->tablevel; 86 PetscFunctionReturn(PETSC_SUCCESS); 87 } 88 89 /*@ 90 PetscObjectSetTabLevel - Sets the number of tabs that `PETSCVIEWERASCII` output for that object uses 91 92 Not Collective 93 94 Input Parameters: 95 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be 96 cast with a (`PetscObject`), for example, 97 `PetscObjectSetTabLevel`((`PetscObject`)mat,tab; 98 - tab - the number of tabs 99 100 Level: developer 101 102 Notes: 103 this is used to manage the output from options that are embedded in other objects. For example 104 the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects 105 is very clear. 106 107 `PetscObjectIncrementTabLevel()` is the preferred API 108 109 .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectGetTabLevel()` 110 @*/ 111 PetscErrorCode PetscObjectSetTabLevel(PetscObject obj, PetscInt tab) 112 { 113 PetscFunctionBegin; 114 PetscValidHeader(obj, 1); 115 obj->tablevel = tab; 116 PetscFunctionReturn(PETSC_SUCCESS); 117 } 118 119 /*@ 120 PetscObjectIncrementTabLevel - Increments the number of tabs that `PETSCVIEWERASCII` output for that object use based on 121 the tablevel of another object. This should be called immediately after the object is created. 122 123 Not Collective 124 125 Input Parameters: 126 + obj - any PETSc object where we are changing the tab 127 . oldobj - the object providing the tab, optional pass `NULL` to use 0 as the previous tablevel for `obj` 128 - tab - the increment that is added to the old objects tab 129 130 Level: developer 131 132 Note: 133 this is used to manage the output from options that are embedded in other objects. For example 134 the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects 135 is very clear. 136 137 .seealso: `PETSCVIEWERASCII`, `PetscObjectSetTabLevel()`, `PetscObjectGetTabLevel()` 138 @*/ 139 PetscErrorCode PetscObjectIncrementTabLevel(PetscObject obj, PetscObject oldobj, PetscInt tab) 140 { 141 PetscFunctionBegin; 142 PetscValidHeader(obj, 1); 143 if (oldobj) PetscValidHeader(oldobj, 2); 144 obj->tablevel = (oldobj ? oldobj->tablevel : 0) + tab; 145 PetscFunctionReturn(PETSC_SUCCESS); 146 } 147