Actual source code: state.c


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

  7: /*@C
  8:    PetscObjectStateGet - Gets the state of any `PetscObject`,
  9:    regardless of the type.

 11:    Not Collective

 13:    Input Parameter:
 14: .  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. This must be
 15:          cast with a (`PetscObject`), for example,
 16:          `PetscObjectStateGet`((`PetscObject`)mat,&state);

 18:    Output Parameter:
 19: .  state - the object state

 21:    Note:
 22:    Object state is an integer which gets increased every time
 23:    the object is changed. By saving and later querying the object state
 24:    one can determine whether information about the object is still current.
 25:    Currently, state is maintained for `Vec` and `Mat` objects.

 27:    Level: advanced

 29: .seealso: `PetscObjectStateIncrease()`, `PetscObjectStateSet()`
 30: @*/
 31: PetscErrorCode PetscObjectStateGet(PetscObject obj, PetscObjectState *state)
 32: {
 35:   *state = obj->state;
 36:   return 0;
 37: }

 39: /*@C
 40:    PetscObjectStateSet - Sets the state of any `PetscObject`,
 41:    regardless of the type.

 43:    Logically Collective

 45:    Input Parameters:
 46: +  obj - any PETSc object, for example a `Vec`, `Mat` or `KSP`. This must be
 47:          cast with a (`PetscObject`), for example,
 48:          `PetscObjectStateSet`((`PetscObject`)mat,state);
 49: -  state - the object state

 51:    Note:
 52:     This function should be used with extreme caution. There is
 53:    essentially only one use for it: if the user calls Mat(Vec)GetRow(Array),
 54:    which increases the state, but does not alter the data, then this
 55:    routine can be used to reset the state.  Such a reset must be collective.

 57:    Level: advanced

 59: .seealso: `PetscObjectStateGet()`, `PetscObjectStateIncrease()`
 60: @*/
 61: PetscErrorCode PetscObjectStateSet(PetscObject obj, PetscObjectState state)
 62: {
 64:   obj->state = state;
 65:   return 0;
 66: }

 68: PetscInt PetscObjectComposedDataMax = 10;

 70: /*@C
 71:    PetscObjectComposedDataRegister - Get an available id for composing data with a `PetscObject`

 73:    Not Collective

 75:    Output parameter:
 76: .  id - an identifier under which data can be stored

 78:    Level: developer

 80:    Notes:
 81:    You must keep this value (for example in a global variable) in order to attach the data to an object or access in an object.

 83:    `PetscObjectCompose()` and  `PetscObjectQuery()` provide a way to attach any data to an object

 85: .seealso: `PetscObjectComposedDataSetInt()`, `PetscObjectComposedDataSetReal()`, `PetscObjectComposedDataGetReal()`, `PetscObjectComposedDataSetIntstar()`,
 86:           `PetscObjectComposedDataSetIntstar()`, `PetscObjectComposedDataGetInt()`, `PetscObject`,
 87:           `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscObjectComposedDataSetRealstar()`, `PetscObjectComposedDataGetScalarstar()`,
 88:           `PetscObjectComposedDataSetScalarstar()`, `PetscObjectComposedDataSetScalarstar()`
 89: @*/
 90: PetscErrorCode PetscObjectComposedDataRegister(PetscInt *id)
 91: {
 92:   static PetscInt globalcurrentstate = 0;

 94:   *id = globalcurrentstate++;
 95:   if (globalcurrentstate > PetscObjectComposedDataMax) PetscObjectComposedDataMax += 10;
 96:   return 0;
 97: }

 99: PetscErrorCode PetscObjectComposedDataIncreaseInt(PetscObject obj)
100: {
101:   PetscInt         *ar = obj->intcomposeddata, *new_ar, n = obj->int_idmax, new_n;
102:   PetscObjectState *ir = obj->intcomposedstate, *new_ir;

104:   new_n = PetscObjectComposedDataMax;
105:   PetscCalloc2(new_n, &new_ar, new_n, &new_ir);
106:   PetscMemcpy(new_ar, ar, n * sizeof(PetscInt));
107:   PetscMemcpy(new_ir, ir, n * sizeof(PetscObjectState));
108:   PetscFree2(ar, ir);
109:   obj->int_idmax        = new_n;
110:   obj->intcomposeddata  = new_ar;
111:   obj->intcomposedstate = new_ir;
112:   return 0;
113: }

115: PetscErrorCode PetscObjectComposedDataIncreaseIntstar(PetscObject obj)
116: {
117:   PetscInt        **ar = obj->intstarcomposeddata, **new_ar, n = obj->intstar_idmax, new_n;
118:   PetscObjectState *ir = obj->intstarcomposedstate, *new_ir;

120:   new_n = PetscObjectComposedDataMax;
121:   PetscCalloc2(new_n, &new_ar, new_n, &new_ir);
122:   PetscMemcpy(new_ar, ar, n * sizeof(PetscInt *));
123:   PetscMemcpy(new_ir, ir, n * sizeof(PetscObjectState));
124:   PetscFree2(ar, ir);
125:   obj->intstar_idmax        = new_n;
126:   obj->intstarcomposeddata  = new_ar;
127:   obj->intstarcomposedstate = new_ir;
128:   return 0;
129: }

131: PetscErrorCode PetscObjectComposedDataIncreaseReal(PetscObject obj)
132: {
133:   PetscReal        *ar = obj->realcomposeddata, *new_ar;
134:   PetscObjectState *ir = obj->realcomposedstate, *new_ir;
135:   PetscInt          n  = obj->real_idmax, new_n;

137:   new_n = PetscObjectComposedDataMax;
138:   PetscCalloc2(new_n, &new_ar, new_n, &new_ir);
139:   PetscMemcpy(new_ar, ar, n * sizeof(PetscReal));
140:   PetscMemcpy(new_ir, ir, n * sizeof(PetscObjectState));
141:   PetscFree2(ar, ir);
142:   obj->real_idmax        = new_n;
143:   obj->realcomposeddata  = new_ar;
144:   obj->realcomposedstate = new_ir;
145:   return 0;
146: }

148: PetscErrorCode PetscObjectComposedDataIncreaseRealstar(PetscObject obj)
149: {
150:   PetscReal       **ar = obj->realstarcomposeddata, **new_ar;
151:   PetscObjectState *ir = obj->realstarcomposedstate, *new_ir;
152:   PetscInt          n  = obj->realstar_idmax, new_n;

154:   new_n = PetscObjectComposedDataMax;
155:   PetscCalloc2(new_n, &new_ar, new_n, &new_ir);
156:   PetscMemcpy(new_ar, ar, n * sizeof(PetscReal *));
157:   PetscMemcpy(new_ir, ir, n * sizeof(PetscObjectState));
158:   PetscFree2(ar, ir);
159:   obj->realstar_idmax        = new_n;
160:   obj->realstarcomposeddata  = new_ar;
161:   obj->realstarcomposedstate = new_ir;
162:   return 0;
163: }

165: PetscErrorCode PetscObjectComposedDataIncreaseScalar(PetscObject obj)
166: {
167:   PetscScalar      *ar = obj->scalarcomposeddata, *new_ar;
168:   PetscObjectState *ir = obj->scalarcomposedstate, *new_ir;
169:   PetscInt          n  = obj->scalar_idmax, new_n;

171:   new_n = PetscObjectComposedDataMax;
172:   PetscCalloc2(new_n, &new_ar, new_n, &new_ir);
173:   PetscMemcpy(new_ar, ar, n * sizeof(PetscScalar));
174:   PetscMemcpy(new_ir, ir, n * sizeof(PetscObjectState));
175:   PetscFree2(ar, ir);
176:   obj->scalar_idmax        = new_n;
177:   obj->scalarcomposeddata  = new_ar;
178:   obj->scalarcomposedstate = new_ir;
179:   return 0;
180: }

182: PetscErrorCode PetscObjectComposedDataIncreaseScalarstar(PetscObject obj)
183: {
184:   PetscScalar     **ar = obj->scalarstarcomposeddata, **new_ar;
185:   PetscObjectState *ir = obj->scalarstarcomposedstate, *new_ir;
186:   PetscInt          n  = obj->scalarstar_idmax, new_n;

188:   new_n = PetscObjectComposedDataMax;
189:   PetscCalloc2(new_n, &new_ar, new_n, &new_ir);
190:   PetscMemcpy(new_ar, ar, n * sizeof(PetscScalar *));
191:   PetscMemcpy(new_ir, ir, n * sizeof(PetscObjectState));
192:   PetscFree2(ar, ir);
193:   obj->scalarstar_idmax        = new_n;
194:   obj->scalarstarcomposeddata  = new_ar;
195:   obj->scalarstarcomposedstate = new_ir;
196:   return 0;
197: }

199: /*@
200:    PetscObjectGetId - get a unique object ID for the `PetscObject`

202:    Not Collective

204:    Input Parameter:
205: .  obj - object

207:    Output Parameter:
208: .  id - integer ID

210:    Level: developer

212:    Note:
213:    The object ID may be different on different processes, but object IDs are never reused so local equality implies global equality.

215: .seealso: `PetscObjectStateGet()`, `PetscObjectCompareId()`
216: @*/
217: PetscErrorCode PetscObjectGetId(PetscObject obj, PetscObjectId *id)
218: {
221:   *id = obj->id;
222:   return 0;
223: }

225: /*@
226:    PetscObjectCompareId - compares the objects ID with a given id

228:    Not Collective

230:    Input Parameters:
231: +  obj - object
232: -  id - integer ID

234:    Output Parameter;
235: .  eq - the ids are equal

237:    Level: developer

239:    Note:
240:    The object ID may be different on different processes, but object IDs are never reused so local equality implies global equality.

242: .seealso: `PetscObjectStateGet()`, `PetscObjectGetId()`
243: @*/
244: PetscErrorCode PetscObjectCompareId(PetscObject obj, PetscObjectId id, PetscBool *eq)
245: {
246:   PetscObjectId oid;

250:   PetscObjectGetId(obj, &oid);
251:   *eq = (id == oid) ? PETSC_TRUE : PETSC_FALSE;
252:   return 0;
253: }