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. In SAF__ONE parallel mode, all processes except the process identified by the rank argument of the SAF__ONE macro are free to pass SAF__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, pass SAF__CELLTYPE_SET. If this is a primitive collection of mixed cell type, pass SAF__CELLTYPE_MIXED. If this is a primitive collection of arbitrarily connected cells, pass SAF__CELLTYPE_ARB. Otherwise, it must be a primitive collection of homogeneous type and the caller should pass one of the cell types specified by SAF__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, and SAF__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 either SAF__DECOMP_TRUE or SAF__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: