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 size_t len1, len2, new_len; 120 121 PetscFunctionBegin; 122 PetscValidHeader(obj, 1); 123 if (!prefix) PetscFunctionReturn(PETSC_SUCCESS); 124 if (!obj->prefix) { 125 PetscCall(PetscObjectSetOptionsPrefix(obj, prefix)); 126 PetscFunctionReturn(PETSC_SUCCESS); 127 } 128 PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen"); 129 130 PetscCall(PetscStrlen(obj->prefix, &len1)); 131 PetscCall(PetscStrlen(prefix, &len2)); 132 new_len = len1 + len2 + 1; 133 PetscCall(PetscRealloc(new_len * sizeof(*(obj->prefix)), &obj->prefix)); 134 PetscCall(PetscStrncpy(obj->prefix + len1, prefix, len2 + 1)); 135 PetscFunctionReturn(PETSC_SUCCESS); 136 } 137 138 /*@C 139 PetscObjectGetOptionsPrefix - Gets the prefix of the `PetscObject` used for searching in the options database 140 141 Input Parameters: 142 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 143 144 Output Parameters: 145 . prefix - pointer to the prefix string used is returned 146 147 Level: advanced 148 149 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`, 150 `TSGetOptionsPrefix()`, `SNESGetOptionsPrefix()`, `KSPGetOptionsPrefix()` 151 @*/ 152 PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj, const char *prefix[]) 153 { 154 PetscFunctionBegin; 155 PetscValidHeader(obj, 1); 156 PetscValidPointer(prefix, 2); 157 *prefix = obj->prefix; 158 PetscFunctionReturn(PETSC_SUCCESS); 159 } 160 161 /*@C 162 PetscObjectPrependOptionsPrefix - Sets the prefix used for searching for options of for this object in the database. 163 164 Input Parameters: 165 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. 166 - prefix - the prefix string to prepend to option requests of the object. 167 168 Note: 169 A hyphen (-) must NOT be given at the beginning of the prefix name. 170 The first character of all runtime options is AUTOMATICALLY the 171 hyphen. 172 173 Level: advanced 174 175 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, 176 `PetscObjectGetOptionsPrefix()` 177 @*/ 178 PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject obj, const char prefix[]) 179 { 180 char *buf; 181 size_t len1, len2, new_len; 182 183 PetscFunctionBegin; 184 PetscValidHeader(obj, 1); 185 if (!prefix) PetscFunctionReturn(PETSC_SUCCESS); 186 if (!obj->prefix) { 187 PetscCall(PetscObjectSetOptionsPrefix(obj, prefix)); 188 PetscFunctionReturn(PETSC_SUCCESS); 189 } 190 PetscCheck(prefix[0] != '-', PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG, "Options prefix should not begin with a hyphen"); 191 192 PetscCall(PetscStrlen(prefix, &len1)); 193 PetscCall(PetscStrlen(obj->prefix, &len2)); 194 buf = obj->prefix; 195 new_len = len1 + len2 + 1; 196 PetscCall(PetscMalloc1(new_len, &obj->prefix)); 197 PetscCall(PetscStrncpy(obj->prefix, prefix, len1 + 1)); 198 PetscCall(PetscStrncpy(obj->prefix + len1, buf, len2 + 1)); 199 PetscCall(PetscFree(buf)); 200 PetscFunctionReturn(PETSC_SUCCESS); 201 } 202