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: }