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