Date: 2025-03-28T21:11:12+00:00

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, No Fortran Support

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