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