Declare a collection¶
saf_declare_collection
is a function defined in coll.c.
Synopsis:
-
int
saf_declare_collection
(SAF_ParMode pmode, SAF_Set *containing_set, SAF_Cat *cat, SAF_CellType ctype, int count, SAF_IndexSpec ispec, SAF_DecompMode is_decomp)¶
Formal Arguments:
pmode
: The parallel mode.containing_set
: The containing set of the collection. InSAF__ONE
parallel mode, all processes except the process identified by the rank argument of theSAF__ONE
macro are free to passSAF__NULL_SET
with the set’s database handle.cat
: The collection category.ctype
: The cell type of the members of the collection. If this is a non-primitive collection, passSAF__CELLTYPE_SET
. If this is a primitive collection of mixed cell type, passSAF__CELLTYPE_MIXED
. If this is a primitive collection of arbitrarily connected cells, passSAF__CELLTYPE_ARB
. Otherwise, it must be a primitive collection of homogeneous type and the caller should pass one of the cell types specified bySAF__CellType
.count
: The number of members of the collection. If the containing set is an extendible set, the count can be changed by a call to saf_extend_collection.ispec
: The indexing scheme of the collection (e.g., how are members of the collection identified within the collection). We have predefined some macros for common cases:SAF__1DC
,SAF__2DC
, andSAF__3DC
for C-ordered and indexed arrays and likewise for Fortran-ordered and indexed arrays (replace the “C” with an “F
” in the macro name).is_decomp
: Indicates if the specified collection is a decomposition of its containing set. That is, if we take the union of all the members of the collection do we form a set that is equal to the containing set?
Description: Collections are contained in sets. Thus there is no explicit object handle for a collection. Instead, a collection is referenced by a pair: the containing set handle and the category handle.
If the set is extendible, then any collection declared on it is considered extendible.
Preconditions:
pmode
must be valid. (low-cost)containing_set
must be a valid set handle for participating processes. (low-cost)cat
must be a valid category handle for participating processes. (low-cost)is_decomp
must be eitherSAF__DECOMP_TRUE
orSAF__DECOMP_FALSE
for participating processes. (low-cost)ispec
rank and sizes must be valid for 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: As currently implemented, the count
and ispec
args are redundant. However, in general, the indexing schema
used to identify members of the collection is nearly totally independent of the count. A common example SAF
does not yet support is the case in which the indexing ids for the members of the collection is some other
arbitrary list of ints (or character string names, etc). For example, all of the nodes on the top set is not
necessarily indexed 0…``num_nodes``-1. Under these conditions, the indexing scheme is another, problem sized
array of ints. However, to handle this, we probably need a saf_write_collection_indexing
function to actually
write that data to a file. Writing it in this call would violate our current policy where problem-sized disk
I/O occurs only on calls with “write” or “read” in their names.
See Also:
- saf_extend_collection: 11.3: Add members to a collection
- Collections: Introduction for current chapter