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`. It 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` regardless of the type.

 33:   Not Collective

 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);

 39:   Output Parameter:
 40: . comm - the MPI communicator

 42:   Level: advanced

 44: .seealso: `PetscObject`, `PetscObjectComm()`
 45: @*/
 46: PetscErrorCode PetscObjectGetComm(PetscObject obj, MPI_Comm *comm)
 47: {
 48:   PetscFunctionBegin;
 50:   PetscAssertPointer(comm, 2);
 51:   *comm = obj->comm;
 52:   PetscFunctionReturn(PETSC_SUCCESS);
 53: }

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

 58:   Not Collective

 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);

 64:   Output Parameter:
 65: . tab - the number of tabs

 67:   Level: developer

 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.

 74: .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectSetTabLevel()`, `PETSCVIEWERASCII`, `PetscObject`
 75: @*/
 76: PetscErrorCode PetscObjectGetTabLevel(PetscObject obj, PetscInt *tab)
 77: {
 78:   PetscFunctionBegin;
 80:   PetscAssertPointer(tab, 2);
 81:   *tab = obj->tablevel;
 82:   PetscFunctionReturn(PETSC_SUCCESS);
 83: }

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

 88:   Not Collective

 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

 95:   Level: developer

 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.

102:   `PetscObjectIncrementTabLevel()` is the preferred API

104: .seealso: `PetscObjectIncrementTabLevel()`, `PetscObjectGetTabLevel()`
105: @*/
106: PetscErrorCode PetscObjectSetTabLevel(PetscObject obj, PetscInt tab)
107: {
108:   PetscFunctionBegin;
110:   obj->tablevel = tab;
111:   PetscFunctionReturn(PETSC_SUCCESS);
112: }

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.

118:   Not Collective

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

125:   Level: developer

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.

132: .seealso: `PETSCVIEWERASCII`, `PetscObjectSetTabLevel()`, `PetscObjectGetTabLevel()`
133: @*/
134: PetscErrorCode PetscObjectIncrementTabLevel(PetscObject obj, PetscObject oldobj, PetscInt tab)
135: {
136:   PetscFunctionBegin;
139:   obj->tablevel = (oldobj ? oldobj->tablevel : 0) + tab;
140:   PetscFunctionReturn(PETSC_SUCCESS);
141: }