2: /*
  3:      Provides utility routines for manulating any type of PETSc object.
  4: */
  5: #include <petsc/private/petscimpl.h>

  7: /*@C
  8:    PetscObjectComm - Gets the MPI communicator for any `PetscObject` regardless of the type.

 10:    Not Collective

 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,
 15:          `PetscObjectComm`((`PetscObject`)mat,...);

 17:    Output Parameter:
 18: .  comm - the MPI communicator or `MPI_COMM_NULL` if `obj` is not valid

 20:    Level: advanced

 22:    Note:
 23:    This is one of the rare PETSc routines that does not return an error code. Use `PetscObjectGetComm()`
 24:    when appropriate for error handling.

 26: .seealso: `PetscObject`, `PetscObjectGetComm()`
 27: @*/
 28: MPI_Comm PetscObjectComm(PetscObject obj)
 29: {
 30:   return obj ? obj->comm : MPI_COMM_NULL;
 31: }

 33: /*@C
 34:    PetscObjectGetComm - Gets the MPI communicator for any `PetscObject`,
 35:    regardless of the type.

 37:    Not Collective

 39:    Input Parameter:
 40: .  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be
 41:          cast with a (`PetscObject`), for example,
 42:          `PetscObjectGetComm`((`PetscObject`)mat,&comm);

 44:    Output Parameter:
 45: .  comm - the MPI communicator

 47:    Level: advanced

 49: .seealso: `PetscObject`, `PetscObjectComm()`
 50: @*/
 51: PetscErrorCode PetscObjectGetComm(PetscObject obj, MPI_Comm *comm)
 52: {
 53:   PetscFunctionBegin;
 56:   *comm = obj->comm;
 57:   PetscFunctionReturn(PETSC_SUCCESS);
 58: }

 60: /*@
 61:    PetscObjectGetTabLevel - Gets the number of tabs that `PETSCVIEWERASCII` output for that object uses

 63:    Not Collective

 65:    Input Parameter:
 66: .  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be
 67:          cast with a (`PetscObject`), for example,
 68:          `PetscObjectGetTabLevel`((`PetscObject`)mat,&tab);

 70:    Output Parameter:
 71: .   tab - the number of tabs

 73:    Level: developer

 75:     Note:
 76:     This is used to manage the output from options that are embedded in other objects. For example
 77:       the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects
 78:       is very clear.

 80: .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectSetTabLevel()`, `PETSCVIEWERASCII`, `PetscObject`
 81: @*/
 82: PetscErrorCode PetscObjectGetTabLevel(PetscObject obj, PetscInt *tab)
 83: {
 84:   PetscFunctionBegin;
 87:   *tab = obj->tablevel;
 88:   PetscFunctionReturn(PETSC_SUCCESS);
 89: }

 91: /*@
 92:    PetscObjectSetTabLevel - Sets the number of tabs that `PETSCVIEWERASCII` output for that object uses

 94:    Not Collective

 96:    Input Parameters:
 97: +  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be
 98:          cast with a (`PetscObject`), for example,
 99:          `PetscObjectSetTabLevel`((`PetscObject`)mat,tab;
100: -   tab - the number of tabs

102:    Level: developer

104:     Notes:
105:     this is used to manage the output from options that are embedded in other objects. For example
106:       the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects
107:       is very clear.

109:     `PetscObjectIncrementTabLevel()` is the preferred API

111: .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectGetTabLevel()`
112: @*/
113: PetscErrorCode PetscObjectSetTabLevel(PetscObject obj, PetscInt tab)
114: {
115:   PetscFunctionBegin;
117:   obj->tablevel = tab;
118:   PetscFunctionReturn(PETSC_SUCCESS);
119: }

121: /*@
122:    PetscObjectIncrementTabLevel - Increments the number of tabs that `PETSCVIEWERASCII` output for that object use based on
123:          the tablevel of another object. This should be called immediately after the object is created.

125:    Not Collective

127:    Input Parameters:
128: +  obj - any PETSc object where we are changing the tab
129: .  oldobj - the object providing the tab, optional pass `NULL` to use 0 as the previous tablevel for `obj`
130: -  tab - the increment that is added to the old objects tab

132:    Level: developer

134:     Note:
135:     this is used to manage the output from options that are embedded in other objects. For example
136:       the `KSP` object inside a `SNES` object. By indenting each lower level further the hierarchy of objects
137:       is very clear.

139: .seealso: `PETSCVIEWERASCII`, `PetscObjectSetTabLevel()`, `PetscObjectGetTabLevel()`
140: @*/
141: PetscErrorCode PetscObjectIncrementTabLevel(PetscObject obj, PetscObject oldobj, PetscInt tab)
142: {
143:   PetscFunctionBegin;
146:   obj->tablevel = (oldobj ? oldobj->tablevel : 0) + tab;
147:   PetscFunctionReturn(PETSC_SUCCESS);
148: }