Read the data for a subset relation¶
saf_read_subset_relation
is a function defined in rel.c.
Synopsis:
-
int
saf_read_subset_relation
(SAF_ParMode pmode, SAF_Rel *rel, SAF_RelTarget *target, void **abuf, void **bbuf)¶
Formal Arguments:
pmode
: The parallel mode.rel
: The relation whose data is to be read.target
: Relation targeting information.abuf
: The data representing those members in the range collection (on the superset) that are related to the members in the domain collection (on the subset).bbuf
: Optional data for boundary subsets indicating which local piece of boundary each member in the domain collection represents in each member of the range collection (see saf_declare_subset_relation)
Description: Read the data associated with a subset relation. Note that there is no information about the buffers passed as formal arguments to this call. Why? Because any information about the “native” buffers is known via the saf_describe_subset_relation call. The client may “target” the data read in this call for a particular data-type, etc. by using the saf_target_subset_relation call.
Preconditions:
pmode
must be valid. (low-cost)rel
must be a valid relation handle. (low-cost)abuf
cannot be null for all participating processes. (low-cost)
Return Value: The constant SAF__SUCCESS
is returned when this function is successful. Otherwise this function either returns
an error number or throws an exception, depending on the value of the library’s error handling property.
Issues: If the client requests bbuf
but none was written, is that an error? Unfortunately, the only answer that
works in all cases is to declare this an error. This is so because it is not possible to notify the client
that none was written except by returning ``bbuf``==``NULL`` and that is **not* possible in the case that the client
has pre-allocated bbuf
(except if we opt to free the pre-allocated bbuf
, and then set it to NULL
which I
don’t think would be a good idea). We limit returning error to only this case. The other case returns
bbuf``==``NULL
See Also:
- saf_declare_subset_relation: 12.5: Declare a subset relation
- saf_describe_subset_relation: 12.6: Get a description of a subset relation
- saf_target_subset_relation: 12.10: Set the destination form of a subset relation
- Subset Relations: Introduction for current chapter