summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorQuincey Koziol <koziol@hdfgroup.org>2000-10-24 18:17:24 (GMT)
committerQuincey Koziol <koziol@hdfgroup.org>2000-10-24 18:17:24 (GMT)
commitad0bc2660401e7334e9bb8fe12d6946f655a5135 (patch)
tree10a68bde538a411987ceed025d015b7fde2e0f16
parent3bb2d5fca2199fbc96d251fac762390038f8783b (diff)
downloadhdf5-ad0bc2660401e7334e9bb8fe12d6946f655a5135.zip
hdf5-ad0bc2660401e7334e9bb8fe12d6946f655a5135.tar.gz
hdf5-ad0bc2660401e7334e9bb8fe12d6946f655a5135.tar.bz2
[svn-r2721] Purpose:
Feature symmetry Description: A while ago I needed to get the 'type' of data being accessed during writes to the VFL driver, so I put in code to get the information down there. Albert asked for the same information during reads, so I've added that in. Tested: Netscape
-rw-r--r--doc/html/TechNotes/VFL.html87
1 files changed, 74 insertions, 13 deletions
diff --git a/doc/html/TechNotes/VFL.html b/doc/html/TechNotes/VFL.html
index 5660b61..5674cdb 100644
--- a/doc/html/TechNotes/VFL.html
+++ b/doc/html/TechNotes/VFL.html
@@ -44,10 +44,11 @@
<LI><A NAME="TOC20" HREF="VFL.html#SEC20">Contiguous I/O Functions</A>
<LI><A NAME="TOC21" HREF="VFL.html#SEC21">Flushing Cached Data</A>
</UL>
-<LI><A NAME="TOC22" HREF="VFL.html#SEC22">Registration of a Driver</A>
-<LI><A NAME="TOC23" HREF="VFL.html#SEC23">Querying Driver Information</A>
+<LI><A NAME="TOC22" HREF="VFL.html#SEC22">Optimization Functions</A>
+<LI><A NAME="TOC23" HREF="VFL.html#SEC23">Registration of a Driver</A>
+<LI><A NAME="TOC24" HREF="VFL.html#SEC24">Querying Driver Information</A>
</UL>
-<LI><A NAME="TOC24" HREF="VFL.html#SEC24">Miscellaneous</A>
+<LI><A NAME="TOC25" HREF="VFL.html#SEC25">Miscellaneous</A>
</UL>
<P><HR><P>
@@ -1058,9 +1059,9 @@ file and vice versa.
</P>
<P>
<DL>
-<DT><U>Function:</U> static herr_t <B>read</B> <I>(H5FD_t *<VAR>file</VAR>, hid_t <VAR>dxpl</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>, void *<VAR>buf</VAR>)</I>
+<DT><U>Function:</U> static herr_t <B>read</B> <I>(H5FD_t *<VAR>file</VAR>, H5FD_mem_t <VAR>type</VAR>, hid_t <VAR>dxpl</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>, void *<VAR>buf</VAR>)</I>
<DD><A NAME="IDX10"></A>
-<DT><U>Function:</U> static herr_t <B>write</B> <I>(H5FD_t *<VAR>file</VAR>, hid_t <VAR>dxpl</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>, const void *<VAR>buf</VAR>)</I>
+<DT><U>Function:</U> static herr_t <B>write</B> <I>(H5FD_t *<VAR>file</VAR>, H5FD_mem_t <VAR>type</VAR>, hid_t <VAR>dxpl</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>, const void *<VAR>buf</VAR>)</I>
<DD><A NAME="IDX11"></A>
</P>
@@ -1071,7 +1072,9 @@ supplied by the caller. The <CODE>write</CODE> function transfers data in the
opposite direction. Both functions take a data transfer property list
<VAR>dxpl</VAR> which indicates the fine points of how the data is to be
transferred and which comes directly from the <CODE>H5Dread</CODE> or
-<CODE>H5Dwrite</CODE> function.
+<CODE>H5Dwrite</CODE> function. Both functions receive <VAR>type</VAR> of
+data being written, which may allow a driver to tune it's behavior for
+different kinds of data.
</DL>
</P>
@@ -1092,8 +1095,8 @@ system calls which were interrupted.
<PRE>
static herr_t
-H5FD_sec2_read(H5FD_t *_file, hid_t dxpl_id/*unused*/, haddr_t addr,
- hsize_t size, void *buf/*out*/)
+H5FD_sec2_read(H5FD_t *_file, H5FD_mem_t type/*unused*/, hid_t dxpl_id/*unused*/,
+ haddr_t addr, hsize_t size, void *buf/*out*/)
{
H5FD_sec2_t *file = (H5FD_sec2_t*)_file;
ssize_t nbytes;
@@ -1203,7 +1206,57 @@ H5FD_sec2_flush(H5FD_t *_file)
-<H2><A NAME="SEC22" HREF="VFL.html#TOC22">Registration of a Driver</A></H2>
+<H2><A NAME="SEC22" HREF="VFL.html#TOC22">Optimization Functions</A></H2>
+
+<P>
+The library is capable of performing several generic optimizations on I/O, but
+these types of optimizations may not be appropriate for a given VFL driver.
+</P>
+
+<P>
+Each driver may provide a query function to allow the library to query whether
+to enable these optimizations. If a driver lacks a query function, the library
+will disable all types of optimizations which can be queried.
+</P>
+
+<P>
+<DL>
+<DT><U>Function:</U> static herr_t <B>query</B> <I>(const H5FD_t *<VAR>file</VAR>, unsigned long *<VAR>flags</VAR>)</I>
+<DD><A NAME="IDX17"></A>
+</P>
+<P>
+This function is called by the library to query which optimizations to enable
+for I/O to this driver. These are the flags which are currently defined:
+
+<UL>
+<DL>
+<DT>H5FD_FEAT_AGGREGATE_METADATA (0x00000001)
+<DD>Defining the H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that
+the library will attempt to allocate a larger block for metadata and
+then sub-allocate each metadata request from that larger block.
+<DT>H5FD_FEAT_ACCUMULATE_METADATA (0x00000002)
+<DD>Defining the H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that
+the library will attempt to cache metadata as it is written to the file
+and build up a larger block of metadata to eventually pass to the VFL
+'write' routine.
+<DT>H5FD_FEAT_DATA_SIEVE (0x00000004)
+<DD>Defining the H5FD_FEAT_DATA_SIEVE for a VFL driver means that
+the library will attempt to cache raw data as it is read from/written to
+a file in a "data sieve" buffer. See Rajeev Thakur's papers:
+ <UL>
+ <DL>
+ <DT>http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz
+ <DT>http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz
+ </DL>
+ </UL>
+</DL>
+</UL>
+</P>
+
+</DL>
+</P>
+
+<H2><A NAME="SEC23" HREF="VFL.html#TOC23">Registration of a Driver</A></H2>
<P>
Before a driver can be used the HDF5 library needs to be told of its
@@ -1275,6 +1328,10 @@ The function which ends access to a file.
An optional function to determine whether two open files have the same key. If
this function is not present then the library assumes that two files will
never be the same.
+<DT><CODE>int (*query)(const H5FD_t *f, unsigned long *flags)</CODE>
+<DD>
+An optional function to determine which library optimizations a driver can
+support.
<DT><CODE>haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hsize_t size)</CODE>
<DD>
An optional function to allocate space in the file.
@@ -1290,10 +1347,10 @@ A function to set the end of address space.
<DT><CODE>haddr_t (*get_eof)(H5FD_t *file)</CODE>
<DD>
A function to return the current end-of-file marker value.
-<DT><CODE>herr_t (*read)(H5FD_t *file, hid_t dxpl, haddr_t addr, hsize_t size, void *buffer)</CODE>
+<DT><CODE>herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, hsize_t size, void *buffer)</CODE>
<DD>
A function to read data from a file.
-<DT><CODE>herr_t (*write)(H5FD_t *file, hid_t dxpl, haddr_t addr, hsize_t size, const void *buffer)</CODE>
+<DT><CODE>herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, hsize_t size, const void *buffer)</CODE>
<DD>
A function to write data to a file.
<DT><CODE>herr_t (*flush)(H5FD_t *file)</CODE>
@@ -1326,6 +1383,7 @@ static const H5FD_class_t H5FD_sec2_g = {
H5FD_sec2_open, /*open */
H5FD_sec2_close, /*close */
H5FD_sec2_cmp, /*cmp */
+ H5FD_sec2_query, /*query */
NULL, /*alloc */
NULL, /*free */
H5FD_sec2_get_eoa, /*get_eoa */
@@ -1368,7 +1426,7 @@ already use that driver.
-<H2><A NAME="SEC23" HREF="VFL.html#TOC23">Querying Driver Information</A></H2>
+<H2><A NAME="SEC24" HREF="VFL.html#TOC24">Querying Driver Information</A></H2>
<P>
<DL>
@@ -1390,7 +1448,7 @@ driver-specific data transfer information instead.
</P>
-<H1><A NAME="SEC24" HREF="VFL.html#TOC24">Miscellaneous</A></H1>
+<H1><A NAME="SEC25" HREF="VFL.html#TOC25">Miscellaneous</A></H1>
<P>
The various private <CODE>H5F_low_*</CODE> functions will be replaced by public
@@ -1478,5 +1536,8 @@ in the missing parts of the mapping.
This document was generated on 18 November 1999 using the
<A HREF="http://wwwcn.cern.ch/dci/texi2html/">texi2html</A>
translator version 1.51.</P>
+<P>
+Updated on 10/24/00 by hand, Quincey Koziol
+</P>
</BODY>
</HTML>