1 2 /* 3 Provides utility routines for manulating any type of PETSc object. 4 */ 5 #include <petsc/private/petscimpl.h> /*I "petscsys.h" I*/ 6 7 /*@C 8 PetscObjectGetOptions - Gets the options database used by the object that has been set with `PetscObjectSetOptions()` 9 10 Collective 11 12 Input Parameter: 13 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 14 15 Output Parameter: 16 . options - the options database 17 18 Note: 19 If this is not called the object will use the default options database 20 21 Developer Note: 22 This functionality is not used in PETSc and should, perhaps, be removed 23 24 Level: advanced 25 26 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 27 `PetscObjectGetOptionsPrefix()`, `PetscObjectSetOptions()` 28 @*/ 29 PetscErrorCode PetscObjectGetOptions(PetscObject obj, PetscOptions *options) 30 { 31 PetscFunctionBegin; 32 PetscValidHeader(obj, 1); 33 *options = obj->options; 34 PetscFunctionReturn(PETSC_SUCCESS); 35 } 36 37 /*@C 38 PetscObjectSetOptions - Sets the options database used by the object. Call immediately after creating the object. 39 40 Collective 41 42 Input Parameters: 43 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 44 - options - the options database, use NULL for default 45 46 Note: 47 If this is not called the object will use the default options database 48 49 Developer Note: 50 This functionality is not used in PETSc and should, perhaps, be removed 51 52 Level: advanced 53 54 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 55 `PetscObjectGetOptionsPrefix()`, `PetscObjectGetOptions()` 56 @*/ 57 PetscErrorCode PetscObjectSetOptions(PetscObject obj, PetscOptions options) 58 { 59 PetscFunctionBegin; 60 PetscValidHeader(obj, 1); 61 obj->options = options; 62 PetscFunctionReturn(PETSC_SUCCESS); 63 } 64 65 /*@C 66 PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all 67 options for the given object in the database. 68 69 Collective 70 71 Input Parameters: 72 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 73 - prefix - the prefix string to prepend to option requests of the object. 74 75 Note: 76 A hyphen (-) must NOT be given at the beginning of the prefix name. 77 The first character of all runtime options is AUTOMATICALLY the 78 hyphen. 79 80 Level: advanced 81 82 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 83 `PetscObjectGetOptionsPrefix()`, `TSSetOptionsPrefix()`, `SNESSetOptionsPrefix()`, `KSPSetOptionsPrefix()` 84 @*/ 85 PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject obj, const char prefix[]) 86 { 87 PetscFunctionBegin; 88 PetscValidHeader(obj, 1); 89 if (prefix) { 90 PetscValidCharPointer(prefix, 2); 91 PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen"); 92 if (prefix != obj->prefix) { 93 PetscCall(PetscFree(obj->prefix)); 94 PetscCall(PetscStrallocpy(prefix, &obj->prefix)); 95 } 96 } else PetscCall(PetscFree(obj->prefix)); 97 PetscFunctionReturn(PETSC_SUCCESS); 98 } 99 100 /*@C 101 PetscObjectAppendOptionsPrefix - Appends to the prefix used for searching for options for the given object in the database. 102 103 Input Parameters: 104 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 105 - prefix - the prefix string to prepend to option requests of the object. 106 107 Note: 108 A hyphen (-) must NOT be given at the beginning of the prefix name. 109 The first character of all runtime options is AUTOMATICALLY the 110 hyphen. 111 112 Level: advanced 113 114 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 115 `PetscObjectGetOptionsPrefix()`, `TSAppendOptionsPrefix()`, `SNESAppendOptionsPrefix()`, `KSPAppendOptionsPrefix()` 116 @*/ 117 PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj, const char prefix[]) 118 { 119 char *buf = obj->prefix; 120 size_t len1, len2; 121 122 PetscFunctionBegin; 123 PetscValidHeader(obj, 1); 124 if (!prefix) PetscFunctionReturn(PETSC_SUCCESS); 125 if (!buf) { 126 PetscCall(PetscObjectSetOptionsPrefix(obj, prefix)); 127 PetscFunctionReturn(PETSC_SUCCESS); 128 } 129 PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen"); 130 131 PetscCall(PetscStrlen(prefix, &len1)); 132 PetscCall(PetscStrlen(buf, &len2)); 133 PetscCall(PetscMalloc1(1 + len1 + len2, &obj->prefix)); 134 PetscCall(PetscStrcpy(obj->prefix, buf)); 135 PetscCall(PetscStrcat(obj->prefix, prefix)); 136 PetscCall(PetscFree(buf)); 137 PetscFunctionReturn(PETSC_SUCCESS); 138 } 139 140 /*@C 141 PetscObjectGetOptionsPrefix - Gets the prefix of the `PetscObject` used for searching in the options database 142 143 Input Parameters: 144 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 145 146 Output Parameters: 147 . prefix - pointer to the prefix string used is returned 148 149 Level: advanced 150 151 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 152 `TSGetOptionsPrefix()`, `SNESGetOptionsPrefix()`, `KSPGetOptionsPrefix()` 153 @*/ 154 PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj, const char *prefix[]) 155 { 156 PetscFunctionBegin; 157 PetscValidHeader(obj, 1); 158 PetscValidPointer(prefix, 2); 159 *prefix = obj->prefix; 160 PetscFunctionReturn(PETSC_SUCCESS); 161 } 162 163 /*@C 164 PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for options of for this object in the database. 165 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. 169 170 Note: 171 A hyphen (-) must NOT be given at the beginning of the prefix name. 172 The first character of all runtime options is AUTOMATICALLY the 173 hyphen. 174 175 Level: advanced 176 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; 184 185 PetscFunctionBegin; 186 PetscValidHeader(obj, 1); 187 buf = obj->prefix; 188 if (!prefix) PetscFunctionReturn(PETSC_SUCCESS); 189 if (!buf) { 190 PetscCall(PetscObjectSetOptionsPrefix(obj, prefix)); 191 PetscFunctionReturn(PETSC_SUCCESS); 192 } 193 PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen"); 194 195 PetscCall(PetscStrlen(prefix, &len1)); 196 PetscCall(PetscStrlen(buf, &len2)); 197 PetscCall(PetscMalloc1(1 + len1 + len2, &obj->prefix)); 198 PetscCall(PetscStrcpy(obj->prefix, prefix)); 199 PetscCall(PetscStrcat(obj->prefix, buf)); 200 PetscCall(PetscFree(buf)); 201 PetscFunctionReturn(PETSC_SUCCESS); 202 } 203