Create storage for a blob

ss_blob_mkstorage is a function defined in ssblob.c.

Synopsis:

herr_t ss_blob_mkstorage(ss_blob_t *blob, hsize_t *size, unsigned flags, ss_prop_t *props)

Formal Arguments:

  • blob: The blob for which a dataset should be created. As a temporary work around for HDF5 limitations, tasks that are part of the blob’s file communicator but not the blob’s scope communicator should pass the top-level scope for the file that contains the blob. See the parallel notes for details.
  • size [OUT]: Optional pointer which, upon successful return, will point to the
  • flags: Certain bit flags that affect the operation of this function. See the description for details.
  • props: Optional properties (see *Blob Properties*). If a dataset creation property list and/or dataset name is supplied then they must be the same across all calling tasks.

Description: If a blob is bound only to memory then a call to this function will create a dataset to hold that data and will bind the dataset to the blob. The created dataset is large enough to hold the memory data to which the blob is currently bound.

Bit Flags

The following bit flags are supported in the flags argument:

SS_ALLSAME: All tasks must be bound to identical memory buffer sizes and only one of those tasks will be
used to compute the total size of the new dataset. In this case the returned size will be zero for all tasks.
SS_BLOB_RANK: All tasks pass the same blob, which is bound to an identical amount of memory across all
tasks, making it unecessary to do any communication to calculate total dataset size or the return values for the size argument. This is useful when T tasks are about to each write N elements in task rank order, creating a dataset whose total size is T``*``N.
SS_BLOB_EACH: Each task is passing its own unique blob and all those blobs will point to the same HDF5
dataset with the blobs layed out onto that dataset in task rank order. All of the blobs must belong to the same scope because that scope determines the communicator that is used for collective message passing operations.
SS_BLOB_EXTEND: The blob and its new dataset will be extendible in one or more dimensions. If the caller
supplies a dataset creation property list with the “dcpl” property of props (see *Blob Properties*) then that list should contain chunk size information. If no “dcpl” property is supplied then SSlib will create a dataset with some default chunk size near 64kB.

All tasks should pass the same blob (except when SS_BLOB_EACH is specified) and the total size of the resulting dataset is the sum of sizes of the bound memory across all tasks (unless SS_ALLSAME is specified).

Return Value: Returns non-negative on success; negative on failure.

Parallel Notes: Conceptually, this function is collective across the communicator of the scope to which the blob belongs. However, since HDF5 metadata operations are file-collective this function must also be collective across the blob’s file communicator. But since the blob doesn’t exist on the “extra” tasks those tasks should pass the blob’s top-level scope instead in order to describe the file in which the dataset is being created.

Issues: It might be nice if this function also took a datatype to use when creating the dataset. But it’s no big deal because the caller can create the dataset outside SSlib if need be, and then bind it to the blob with ss_blob_bind_f.

This function currently only creates one-dimensional datasets even when the memory spaces are multi-dimensional. This should eventually be fixed. [2003-09-11]

See Also:

  • ss_blob_bind_f: 15.4: Bind a blob to a dataset
  • I/O: Introduction for current chapter