Actual source code: gcomm.c


  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 object is not valid

 20:    Level: advanced

 22: .seealso: `PetscObject`, `PetscObjectGetComm()`
 23: @*/
 24: MPI_Comm PetscObjectComm(PetscObject obj)
 25: {
 26:   return obj ? obj->comm : MPI_COMM_NULL;
 27: }

 29: /*@C
 30:    PetscObjectGetComm - Gets the MPI communicator for any `PetscObject`,
 31:    regardless of the type.

 33:    Not Collective

 35:    Input Parameter:
 36: .  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be
 37:          cast with a (`PetscObject`), for example,
 38:          `PetscObjectGetComm`((`PetscObject`)mat,&comm);

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

 43:    Level: advanced

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

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

 59:    Not Collective

 61:    Input Parameter:
 62: .  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. Thus must be
 63:          cast with a (`PetscObject`), for example,
 64:          `PetscObjectGetTabLevel`((`PetscObject`)mat,&tab);

 66:    Output Parameter:
 67: .   tab - the number of tabs

 69:    Level: developer

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

 76: .seealso: `PetscObjectIncrementTabLevel()`, `PETSCVIEWERASCII`
 77: @*/
 78: PetscErrorCode PetscObjectGetTabLevel(PetscObject obj, PetscInt *tab)
 79: {
 80:   PetscFunctionBegin;
 83:   *tab = obj->tablevel;
 84:   PetscFunctionReturn(PETSC_SUCCESS);
 85: }

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

 90:    Not Collective

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

 98:    Level: developer

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

105:     `PetscObjectIncrementTabLevel()` is the preferred API

107: .seealso: `PetscObjectIncrementTabLevel()`
108: @*/
109: PetscErrorCode PetscObjectSetTabLevel(PetscObject obj, PetscInt tab)
110: {
111:   PetscFunctionBegin;
113:   obj->tablevel = tab;
114:   PetscFunctionReturn(PETSC_SUCCESS);
115: }

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

121:    Not Collective

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

128:    Level: developer

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

135: .seealso: `PETSCVIEWERASCII`, `PetscObjectSetTabLevel()`, `PetscObjectGetTabLevel()`
136: @*/
137: PetscErrorCode PetscObjectIncrementTabLevel(PetscObject obj, PetscObject oldobj, PetscInt tab)
138: {
139:   PetscFunctionBegin;
142:   obj->tablevel = (oldobj ? oldobj->tablevel : 0) + tab;
143:   PetscFunctionReturn(PETSC_SUCCESS);
144: }