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: {
 51:   *comm = obj->comm;
 52:   return 0;
 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`. Thus must be
 62:          cast with a (`PetscObject`), for example,
 63:          `PetscObjectGetTabLevel`((`PetscObject`)mat,&tab);

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

 68:    Level: developer

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

 75: .seealso: `PetscObjectIncrementTabLevel()`, `PETSCVIEWERASCII`
 76: @*/
 77: PetscErrorCode PetscObjectGetTabLevel(PetscObject obj, PetscInt *tab)
 78: {
 81:   *tab = obj->tablevel;
 82:   return 0;
 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`. Thus must be
 92:          cast with a (`PetscObject`), for example,
 93:          `PetscObjectSetTabLevel`((`PetscObject`)mat,tab;
 94: -   tab - the number of tabs

 96:    Level: developer

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

103:     `PetscObjectIncrementTabLevel()` is the preferred API

105: .seealso: `PetscObjectIncrementTabLevel()`
106: @*/
107: PetscErrorCode PetscObjectSetTabLevel(PetscObject obj, PetscInt tab)
108: {
110:   obj->tablevel = tab;
111:   return 0;
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
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 very clear.

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