1 /*
2 Provides utility routines for manulating any type of PETSc object.
3 */
4 #include <petsc/private/petscimpl.h> /*I "petscsys.h" I*/
5
6 /*@
7 PetscObjectGetOptions - Gets the options database used by the object that has been set with `PetscObjectSetOptions()`
8
9 Collective
10
11 Input Parameter:
12 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
13
14 Output Parameter:
15 . options - the options database
16
17 Level: advanced
18
19 Note:
20 If this is not called the object will use the default options database
21
22 Developer Notes:
23 This functionality is not used in PETSc and should, perhaps, be removed
24
25 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
26 `PetscObjectGetOptionsPrefix()`, `PetscObjectSetOptions()`
27 @*/
PetscObjectGetOptions(PetscObject obj,PetscOptions * options)28 PetscErrorCode PetscObjectGetOptions(PetscObject obj, PetscOptions *options)
29 {
30 PetscFunctionBegin;
31 PetscValidHeader(obj, 1);
32 *options = obj->options;
33 PetscFunctionReturn(PETSC_SUCCESS);
34 }
35
36 /*@
37 PetscObjectSetOptions - Sets the options database used by the object. Call immediately after creating the object.
38
39 Collective
40
41 Input Parameters:
42 + obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
43 - options - the options database, use NULL for default
44
45 Level: advanced
46
47 Note:
48 If this is not called the object will use the default options database
49
50 Developer Notes:
51 This functionality is not used in PETSc and should, perhaps, be removed
52
53 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
54 `PetscObjectGetOptionsPrefix()`, `PetscObjectGetOptions()`
55 @*/
PetscObjectSetOptions(PetscObject obj,PetscOptions options)56 PetscErrorCode PetscObjectSetOptions(PetscObject obj, PetscOptions options)
57 {
58 PetscFunctionBegin;
59 PetscValidHeader(obj, 1);
60 obj->options = options;
61 PetscFunctionReturn(PETSC_SUCCESS);
62 }
63
64 /*@
65 PetscObjectSetOptionsPrefix - Sets the prefix used for searching for all
66 options for the given object in the database.
67
68 Collective
69
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.
73
74 Level: advanced
75
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.
80
81 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectAppendOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
82 `PetscObjectGetOptionsPrefix()`, `TSSetOptionsPrefix()`, `SNESSetOptionsPrefix()`, `KSPSetOptionsPrefix()`
83 @*/
PetscObjectSetOptionsPrefix(PetscObject obj,const char prefix[])84 PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject obj, const char prefix[])
85 {
86 PetscFunctionBegin;
87 PetscValidHeader(obj, 1);
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;
93
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 }
101
102 /*@
103 PetscObjectAppendOptionsPrefix - Appends to the prefix used for searching for options for the given object in the database.
104
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.
108
109 Level: advanced
110
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.
115
116 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectPrependOptionsPrefix()`,
117 `PetscObjectGetOptionsPrefix()`, `TSAppendOptionsPrefix()`, `SNESAppendOptionsPrefix()`, `KSPAppendOptionsPrefix()`
118 @*/
PetscObjectAppendOptionsPrefix(PetscObject obj,const char prefix[])119 PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject obj, const char prefix[])
120 {
121 size_t len1, len2, new_len;
122
123 PetscFunctionBegin;
124 PetscValidHeader(obj, 1);
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");
131
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 }
139
140 /*@
141 PetscObjectGetOptionsPrefix - Gets the prefix of the `PetscObject` used for searching in the options database
142
143 Input Parameter:
144 . obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`.
145
146 Output Parameter:
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 @*/
PetscObjectGetOptionsPrefix(PetscObject obj,const char * prefix[])154 PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject obj, const char *prefix[])
155 {
156 PetscFunctionBegin;
157 PetscValidHeader(obj, 1);
158 PetscAssertPointer(prefix, 2);
159 *prefix = obj->prefix;
160 PetscFunctionReturn(PETSC_SUCCESS);
161 }
162
163 /*@
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 Level: advanced
171
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.
176
177 .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscObjectSetOptionsPrefix()`, `PetscObjectAppendOptionsPrefix()`,
178 `PetscObjectGetOptionsPrefix()`
179 @*/
PetscObjectPrependOptionsPrefix(PetscObject obj,const char prefix[])180 PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject obj, const char prefix[])
181 {
182 char *buf;
183 size_t len1, len2, new_len;
184
185 PetscFunctionBegin;
186 PetscValidHeader(obj, 1);
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");
193
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 }
204