hdf5/docs/doxygen/dox/IOFlow.dox

/** \page IOFLOW HDF5 Raw I/O Flow Notes

Navigate back: \ref index "Main" / \ref TN
<hr>

\li Created by Quincey Koziol, August 20, 2003
\li Document's Audience: Current H5 library designers and knowledgeable external developers.

\section sec_ioflow_intro Introduction
What is this document about?<br />
This document attempts to supplement the flow charts describing the flow of control for raw data
I/O in the library.
The following figures provide the main information:
<table>
  <tr><td><img src="IOFlow.gif" alt="High-Level View of Writing Raw Data" style="height:50%;"></td></tr>
  <tr><td><img src="IOFlow2.gif" alt="Perform Serial or Parallel I/O" style="height:50%;"></td></tr>
  <tr><td><img src="IOFlow3.gif" alt="Gather/Convert/Scatter" style="height:50%;"></td></tr>
</table>

\section sec_ioflow_notes Notes From Accompanying Figures
This section provides notes to augment the information in the accompanying figures.

<ol>
    <li><b>Validate Parameters</b> - Resolve any H5S_ALL parameters
        for dataspace selections to actual dataspaces, allocate
        conversion buffers, etc.
    </li>

    <li><b>Space Allocated in File?</b> - Space may not have been allocated
        in the file to store the dataset data, if "late allocation" was chosen
        for the allocation time when the dataset was created.
    </li>

    <li><b>Allocate &amp; Fill Space</b> - These operations allocate both contiguous
        and chunked dataset's space in the file.  The chunked dataset space
        allocation iterates through all the chunks in the file and allocates
        both the B-tree information and the raw data in the file.  Because of
        the way filters work, fill-values are written out for chunked datasets
        as they are allocated, instead of as a separate step.
        In parallel
        I/O, the chunked dataset allocation can potentially be time-consuming,
        since all the raw data in the dataset is allocated from one process.
    </li>

    <li><b>Datatype Conversion Needed?</b> - This currently is the deciding
        factor between doing "direct I/O" (in serial or parallel) and needing
        to perform gather/convert/scatter operations.  I believe that MPI
        is capable of performing a limited range of type conversions and if so,
        we should add support to detect when they can be used.  This will
        allow more I/O operations to be performed collectively.
    </li>

    <li><b>Collective I/O Requested/Allowed?</b> - A user has to both request
        that collective I/O occur and also their I/O operation must meet the
        requirements that the library sets for supporting collective parallel
        I/O:
        <ul>
            <li>The dataspace must be scalar or simple (which is a no-op really,
                since we don't support "complex" dataspaces in the library
                currently).
            </li>
            <li>The selection must be regular.  "all" selections
                and hyperslab selections that were
                made with only one call to H5Sselect_hyperslab() (i.e. not a
                hyperslab selection that has been aggregated over multiple
                selection calls) are regular.  Supporting point and
                irregular hyperslab selections are on the "to do" list.
            </li>
            <li>The dataset must be stored contiguously on disk (as shown in the
                figure also).  Supporting chunked dataset storage is also
                on the "to do" list.
            </li>
        </ul>
    </li>

    <li><b>Build "chunk map"</b> - This step still has some scalability issues
        as it creates a data structure that is proportional to the number of
        chunks which will be written to, which could potentially be very large.
        Building the "chunk map" information incrementally is on the "to do"
        list also.
    </li>

    <li><b>Perform Chunked I/O</b> - As the figure shows, there is no support
        for collective parallel I/O on chunked datasets currently.  As noted
        earlier, this is on the "to do" list.
    </li>

    <li><b>Perform "Direct" Serial I/O</b> - "Direct" serial I/O writes data
        from the application's buffer, without any intervening buffer or memory
        copies.  For maximum efficiency and performance, the elements in the
        selections should be adjoining.
    </li>

    <li><b>Perform Collective Parallel I/O</b> - This step also writes data
        directly from an application buffer, but additionally uses collective
        MPI I/O operations to combine the data from each process in the parallel
        application in an efficient manner.
    </li>
</ol>

<hr>
Navigate back: \ref index "Main" / \ref TN

*/