Write data to a blob

ss_blob_write is a function defined in ssblob.c.

Synopsis:

herr_t ss_blob_write(ss_blob_t *blob, hid_t iospace, unsigned flags, ss_prop_t UNUSED *props)

Formal Arguments:

  • blob: The blob for which data is written, which must be bound to both memory and a dataset. Any task that is part of the file communicator but not the scope communicator is participating soley for the sake of collectivity and should pass the blob’s top scope here instead.
  • iospace: This is an optional hyperslab describing the part of the blob that is to be written. The extent and selection are relative to the portion of the dataset owned by the blob and described in some previous call to ss_blob_bind_f (perhaps in an earlier execution). If not specified then all of the blob’s data is written.
  • flags: Various bit flags commonly passed to this function.
  • props: See *Blob Properties*. (Unused at this time.)

Description: Given a blob that has been bound to both memory and a dataset, transfer data from memory to the file. The portion of the blob to write is described by the iospace argument.

The flags argument determines specifics about the write operation and the following bits are defined:

SS_BLOB_COLLECTIVE: The operation is to be considered collective across the blob’s file communicator.
SSlib can use two-phase I/O for this situation. If this bit is not set then the operation is considered independent of any other task.
SS_BLOB_ASYNC: The I/O for this call can be performed asynchronously, allowing SSlib to use two-phase
I/O even when the call is independent. Asynchronous writes are guaranteed to be completed after a call to ss_blob_flush on the affected dataset.
SS_BLOB_COPY: In the case of asynchronous I/O it is important that the caller doesn’t modify the
memory being written until the data has been shipped to the aggregator. However, if this bit is turned on then SSlib will make a copy of the data before this call returns. Only the data actually being written is copied, which could be substantially smaller than the entire memory array that was supplied in the case of partial I/O.
SS_BLOB_UNBIND: The memory and blob are disassociated from each other when this function returns,
whether the return status indicates success or failure. However, if the failure occurs early enough (e.g., the blob is invalid) then no disassociation will occur.
SS_BLOB_FREE: The memory bound to this blob should be freed as soon as it is no longer needed. For
synchronous writes it will be freed before this function returns, but asynchronous writes may retain the memory longer. The SS_BLOB_UNBIND flag must also be set when SS_BLOB_FREE is set.
SS_ALLSAME: This bit flag indicates that all blob tasks are calling this function collectively and
they are all providing the same data values to be written all at the same offset. Thus only one task needs to actually do any writing. There are three main reasons to use this flag: (1) for convenience so the caller doesn’t need to choose a particular task, (2) so that if the caller doesn’t choose a particular task that tasks aren’t duplicating effort, and (3) so that the aggregation tasks know that they might be able to get data without doing any communication.

The data spaces of the memory, the blob, the dataset, and the iospace must all be compatible. SSlib allows the dataset dimensionality to be larger than the blob dimensionality, but the memory, blob, and iospace data spaces must all be the same dimensionality.

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

For asynchronous operations there is currently no good way to determine whether this particular write was successful, only whether the entire flush was successful.

Parallel Notes: Independent unless the SS_BLOB_COLLECTIVE or SS_ALLSAME bits are turned on in the flags argument, in which case the function should be called collectively across all tasks in the file communicator to which the blob belongs. The tasks that are part of the file communicator but not part of the blob’s scope communicator should pass the top scope of the blob’s file as the blob argument.

The order of reads and writes is indeterminate when SSlib is doing asynchronous I/O and it is up to the caller to issue the appropriate ss_blob_flush calls to ensure an ordering.

Example: .. _SC_ss_blob_write:

1
 See ss_blob_read() for examples since this function is almost identical in nature.

Issues: I don’t think an MPI_Barrier is sufficient to make the aggregators’ independent H5Dwrite data to become available to the other tasks for reading. We may need either an MPI_File_sync or we may need to have the tasks write collectively. [rpm 2004-07-26]

I don’t think an MPI_Barrier is sufficient here. We may need either an MPI_File_sync or we may need to have the tasks write collectively but only one supplying data. [rpm 2004-07-26]

See Also: