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: