Actual source code: prefix.c

      1: /*
      2:      Provides utility routines for manulating any type of PETSc object.
      3: */
      4: #include <petsc/private/petscimpl.h>

      6: /*@
      7:   PetscObjectGetOptions - Gets the options database used by the object that has been set with `PetscObjectSetOptions()`

      9:   Collective

     11:   Input Parameter:
     12: . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.

     14:   Output Parameter:
     15: . options - the options database

     17:   Level: advanced

     19:   Note:
     20:   If this is not called the object will use the default options database

     22:   Developer Notes:
     23:   This functionality is not used in PETSc and should, perhaps, be removed

     25: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
     26:           `PetscObjectGetOptionsPrefix()`, `PetscObjectSetOptions()`
     27: @*/
     28: PetscErrorCode PetscObjectGetOptions(PetscObject obj, PetscOptions *options)
     29: {
     30:   PetscFunctionBegin;
     32:   *options = obj->options;
     33:   PetscFunctionReturn(PETSC_SUCCESS);
     34: }

     36: /*@
     37:   PetscObjectSetOptions - Sets the options database used by the object. Call immediately after creating the object.

     39:   Collective

     41:   Input Parameters:
     42: + obj     - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
     43: - options - the options database, use NULL for default

     45:   Level: advanced

     47:   Note:
     48:   If this is not called the object will use the default options database

     50:   Developer Notes:
     51:   This functionality is not used in PETSc and should, perhaps, be removed

     53: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
     54:           `PetscObjectGetOptionsPrefix()`, `PetscObjectGetOptions()`
     55: @*/
     56: PetscErrorCode PetscObjectSetOptions(PetscObject obj, PetscOptions options)
     57: {
     58:   PetscFunctionBegin;
     60:   obj->options = options;
     61:   PetscFunctionReturn(PETSC_SUCCESS);
     62: }

     64: /*@
     65:   PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all
     66:   options for the given object in the database.

     68:   Collective

     70:   Input Parameters:
     71: + obj    - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
     72: - prefix - the prefix string to prepend to option requests of the object.

     74:   Level: advanced

     76:   Note:
     77:   A hyphen (-) must NOT be given at the beginning of the prefix name.
     78:   The first character of all runtime options is AUTOMATICALLY the
     79:   hyphen.

     81: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
     82:           `PetscObjectGetOptionsPrefix()`, `TSSetOptionsPrefix()`, `SNESSetOptionsPrefix()`, `KSPSetOptionsPrefix()`
     83: @*/
     84: PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject obj, const char prefix[])
     85: {
     86:   PetscFunctionBegin;
     88:   if (prefix) {
     89:     PetscAssertPointer(prefix, 2);
     90:     PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen");
     91:     if (prefix != obj->prefix) {
     92:       size_t len;

     94:       PetscCall(PetscFree(obj->prefix));
     95:       PetscCall(PetscStrlen(prefix, &len));
     96:       if (len) PetscCall(PetscStrallocpy(prefix, &obj->prefix));
     97:     }
     98:   } else PetscCall(PetscFree(obj->prefix));
     99:   PetscFunctionReturn(PETSC_SUCCESS);
    100: }

    102: /*@
    103:   PetscObjectAppendOptionsPrefix - Appends to the prefix used for searching for options for the given object in the database.

    105:   Input Parameters:
    106: + obj    - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
    107: - prefix - the prefix string to prepend to option requests of the object.

    109:   Level: advanced

    111:   Note:
    112:   A hyphen (-) must NOT be given at the beginning of the prefix name.
    113:   The first character of all runtime options is AUTOMATICALLY the
    114:   hyphen.

    116: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
    117:           `PetscObjectGetOptionsPrefix()`, `TSAppendOptionsPrefix()`, `SNESAppendOptionsPrefix()`, `KSPAppendOptionsPrefix()`
    118: @*/
    119: PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj, const char prefix[])
    120: {
    121:   size_t len1, len2, new_len;

    123:   PetscFunctionBegin;
    125:   if (!prefix) PetscFunctionReturn(PETSC_SUCCESS);
    126:   if (!obj->prefix) {
    127:     PetscCall(PetscObjectSetOptionsPrefix(obj, prefix));
    128:     PetscFunctionReturn(PETSC_SUCCESS);
    129:   }
    130:   PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen");

    132:   PetscCall(PetscStrlen(obj->prefix, &len1));
    133:   PetscCall(PetscStrlen(prefix, &len2));
    134:   new_len = len1 + len2 + 1;
    135:   PetscCall(PetscRealloc(new_len * sizeof(*obj->prefix), &obj->prefix));
    136:   PetscCall(PetscStrncpy(obj->prefix + len1, prefix, len2 + 1));
    137:   PetscFunctionReturn(PETSC_SUCCESS);
    138: }

    140: /*@
    141:   PetscObjectGetOptionsPrefix - Gets the prefix of the `PetscObject` used for searching in the options database

    143:   Input Parameter:
    144: . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.

    146:   Output Parameter:
    147: . prefix - pointer to the prefix string used is returned

    149:   Level: advanced

    151: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
    152:           `TSGetOptionsPrefix()`, `SNESGetOptionsPrefix()`, `KSPGetOptionsPrefix()`
    153: @*/
    154: PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj, const char *prefix[])
    155: {
    156:   PetscFunctionBegin;
    158:   PetscAssertPointer(prefix, 2);
    159:   *prefix = obj->prefix;
    160:   PetscFunctionReturn(PETSC_SUCCESS);
    161: }

    163: /*@
    164:   PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for options of for this object in the database.

    166:   Input Parameters:
    167: + obj    - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
    168: - prefix - the prefix string to prepend to option requests of the object.

    170:   Level: advanced

    172:   Note:
    173:   A hyphen (-) must NOT be given at the beginning of the prefix name.
    174:   The first character of all runtime options is AUTOMATICALLY the
    175:   hyphen.

    177: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`,
    178:           `PetscObjectGetOptionsPrefix()`
    179: @*/
    180: PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject obj, const char prefix[])
    181: {
    182:   char  *buf;
    183:   size_t len1, len2, new_len;

    185:   PetscFunctionBegin;
    187:   if (!prefix) PetscFunctionReturn(PETSC_SUCCESS);
    188:   if (!obj->prefix) {
    189:     PetscCall(PetscObjectSetOptionsPrefix(obj, prefix));
    190:     PetscFunctionReturn(PETSC_SUCCESS);
    191:   }
    192:   PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen");

    194:   PetscCall(PetscStrlen(prefix, &len1));
    195:   PetscCall(PetscStrlen(obj->prefix, &len2));
    196:   buf     = obj->prefix;
    197:   new_len = len1 + len2 + 1;
    198:   PetscCall(PetscMalloc1(new_len, &obj->prefix));
    199:   PetscCall(PetscStrncpy(obj->prefix, prefix, len1 + 1));
    200:   PetscCall(PetscStrncpy(obj->prefix + len1, buf, len2 + 1));
    201:   PetscCall(PetscFree(buf));
    202:   PetscFunctionReturn(PETSC_SUCCESS);
    203: }