Read the data for a field¶
saf_read_field
is a function defined in field.c.
Synopsis:
-
int
saf_read_field
(SAF_ParMode pmode, SAF_Field *field, SAF_FieldTarget *target, int member_count, SAF_RelRep *req_type, int *member_ids, void **Pbuf)¶
Formal Arguments:
pmode
: The parallel mode.field
: The field which is to be read.target
: Field targeting information.member_count
: A count of the number of members of the collection in which the field’s dofs aren:1
associated with that are actually being written in this call. This value is ignored if you are reading the entire field’s dofs in this call (i.e.,req_type
=SAF__TOTALITY
). Also note that as a convenience, we provide the macroSAF__WHOLE_FIELD
which expands to a comma separated list of appropriate values for this argument and the next two, for the case in which the whole field is being read in this call.req_type
: The type of I/O request. We use a relation representation type here to specify the type of the partial request because it captures the necessary information. PassSAF__HSLAB
if you are reading the dofs of a partial hyperslab of the members of the associated collection. In this case,member_ids
points to 3N
-tuples of starts, counts and strides of the hyperslab (hypersample) request. PassSAF__TUPLES
, if you are reading the dofs for an arbitrary list of members of the associated collection. In this case, themember_ids
points to a list ofN
-tuples. In both cases, ‘N
’ is the number of indexing dimensions in the associated collection. Finally, passSAF__TOTALITY
if you are reading the entire field’s set of dofs.member_ids
: Depending on the value ofreq_type
, this argument points to 3N
-tuples storing, respectively, the starts, counts and strides in each dimension of the associated collection or to a list ofmember_count
N
-tuples, each one identifying a single member of the associated collection or toNULL
in the case of aSAF__TOTALITY
request.Pbuf
: [IN``|``OUT
] A pointer to a buffer pointer which is to receive the values read. The caller may supply a pointer to a value ofNULL
if this function is to allocate a buffer. If the caller supplies a pointer to a non-NULL
pointer (to a buffer) then it is up to the caller to ensure that the buffer is of sufficient size to hold all of the data retrieved. The caller should use saf_describe_field or saf_get_count_and_type_for_field to determine the datatype of the values read.
Description: This is function is used to read a field’s data. If the field is not an indirect reference to other fields, this call involves real disk I/O. All functions in SAF with either “read” or “write” in the name potentially involve real disk I/O.
This function allows a client to read either the entire field’s data or a portion of the field’s data. Recall
that the degrees of freedom (dofs) of a field are n:1
associated with the members of some collection in
the set upon which the field is defined. We call this collection the associated collection.
In order to specify a partial request, the client is required to
specify which members of the associated collection it is reading the dofs for. Ultimately, those members may be
specified using a N
dimensional hyperslab (or hypersample) or an arbitrary list of N
-tuples. In either case,
the number of dimensions, ‘N
’, is the number of indexing dimensions in the associated collection.
At present, there are several limitations. First, the collection must be 1 dimensionally indexed. Next,
only the hyperslab mode or a single member in tuple-mode are supported; not hypersamples and not an
arbitrary list. Also, if the field is a multi-component field, then the only supported interleave mode is
SAF__INTERLEAVE_VECTOR
.
Finally, we provide as a convenience the macro SAF__WHOLE_FIELD
which expands to a comma separated list of
values, 0, SAF__TOTALITY
, NULL
, for the three arguments member_count
, req_type
, member_ids
for the case in
which the client is reading the whole field in this call.
Preconditions:
pmode
must be valid. (low-cost)field
must be a valid field handle. (low-cost)Pbuf
must be non-null. (low-cost)- If partial I/O request, associated collection must be 1D indexed,
req_type
must beSAF__HSLAB
. (high-cost) - If field targeting of storage decomposition is used, the read must be a
SAF__ALL
mode read or the. (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: A partial I/O request looks a lot like a subset relation. In fact, we even use the same data type, SAF__SRType
,
to identify the type of partial I/O request. It may be difficult for a client to distinguish between making
a partial I/O request and making real subsets. In theory, there really should be no difference. The act
of reading/writing a portion of a field is the act of defining a subset of the base space the field is defined
on and then restricting the field to that subset. In the current implementation, this requires, at a minimum, the
ability to create transient objects such as the subset representing the piece of the field being read/written in
this call. In addition, it really requires decoupling the storage containers into which field’s data goes
from declaring and reading/writing fields.
For an indirect field the the local fields are all “similar”. That is, they have the same algebraic type, association category, units and such. This function should check for this but doesn’t. In the future some differences can be smoothed-over (such as units) but some probably can not (such as algebraic type).
The proper use of pmode
is not fully worked out.
Multiple indirection may actually fall out of this solution but that is not at all clear.
When remapping an indirect field we only look in the top-scope of the file containing the field’s base space when searching for the subset relations. [rpm 2004-05-24]
See Also:
- saf_describe_field: 16.13: Get a description of a field
- saf_get_count_and_type_for_field: 16.17: Get datatype and size for a field
- Fields: Introduction for current chapter