H5hut/src_old
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

src/include/H5.h,H5Block_attribs.h:

Browse Source 
- add/review documentation
This commit is contained in:
gsell
2016-02-12 17:39:46 +01:00
parent 43bc72b7d0
commit 4b1d719d6c
2 changed files with 187 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/include/H5.h
+176 -51
View File
@@ -1,5 +1,5 @@
/*
Copyright (c) 2006-2015, The Regents of the University of California,
Copyright (c) 2006-2016, The Regents of the University of California,
through Lawrence Berkeley National Laboratory (subject to receipt of any
required approvals from the U.S. Dept. of Energy) and the Paul Scherrer
Institut (Switzerland). All rights reserved.
@@ -19,6 +19,23 @@
extern "C" {
#endif
/**
\ingroup h5hut_file
Create a new, empty file property list. This list can be used in \ref H5OpenFile()
to set various properties like the file I/O layer.
\see H5SetPropFileMPIO()
\see H5SetPropFileMPIOCollective()
\see H5SetPropFileMPIOIndependent()
\see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only)
\see H5SetPropFileCoreVFD()
\see H5SetPropFileAlign()
\see H5SetPropFileThrottle()
\return empty file property list
\return \c H5_FAILURE on error
*/
static inline h5_prop_t
H5CreateFileProp (
void
@@ -27,61 +44,158 @@ H5CreateFileProp (
H5_API_RETURN (h5_create_prop (H5_PROP_FILE));
}
/**
\ingroup h5hut_file
Stores MPI IO communicator information to given file property list. If used in
\ref H5OpenFile(), MPI collective IO will be used.
\note H5SetPropFileMPIO() is deprecated. Use H5SetPropFileMPIOCollective() instead.
\see H5SetPropFileMPIOIndependent()
\see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only)
\see H5SetPropFileCoreVFD()
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5SetPropFileMPIO (
h5_prop_t prop,
MPI_Comm* comm
h5_prop_t prop, ///< [in,out] identifier for file property list
MPI_Comm* comm ///< [in] MPI communicator
) {
H5_API_ENTER (h5_err_t, "prop=%p, comm=%p", (void*)prop, comm);
H5_API_RETURN (h5_set_prop_file_mpio_collective (prop, comm));
}
/**
\ingroup h5hut_file
Stores MPI IO communicator information to given file property list. If used in
\ref H5OpenFile(), MPI collective IO will be used.
\note H5SetPropFileMPIOCollective() deprecates H5SetPropFileMPIO().
\see H5SetPropFileMPIOIndependent()
\see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only)
\see H5SetPropFileCoreVFD()
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5SetPropFileMPIOCollective (
h5_prop_t prop,
MPI_Comm* comm
h5_prop_t prop, ///> [in,out] identifier for file property list
MPI_Comm* comm ///< [in] MPI communicator
) {
H5_API_ENTER (h5_err_t, "prop=%p, comm=%p", (void*)prop, comm);
H5_API_RETURN (h5_set_prop_file_mpio_collective (prop, comm));
}
/**
\ingroup h5hut_file
Stores MPI IO communicator information to given file property list. If used in
\ref H5OpenFile(), MPI independent IO will be used.
\see H5SetPropFileMPIOCollective()
\see H5SetPropFileMPIOPosix() (HDF5 <= 1.8.12 only)
\see H5SetPropFileCoreVFD()
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5SetPropFileMPIOIndependent (
h5_prop_t prop,
MPI_Comm* comm
h5_prop_t prop, ///> [in,out] identifier for file property list
MPI_Comm* comm ///> [in] MPI communicator
) {
H5_API_ENTER (h5_err_t, "prop=%p, comm=%p", (void*)prop, comm);
H5_API_RETURN (h5_set_prop_file_mpio_independent (prop, comm));
}
#if H5_VERSION_LE(1,8,12)
/**
\ingroup h5hut_file
Stores MPI IO communicator information to given file property list. If used in
\ref H5OpenFile(), MPI POSIX IO will be used.
\note This function is available only, if H5hut has been compiled with
HDF5 1.8.12 or older.
\see H5SetPropFileMPIOCollective()
\see H5SetPropFileMPIOIndependent()
\see H5SetPropFileCoreVFD()
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5SetPropFileMPIOPosix (
h5_prop_t prop,
MPI_Comm* comm
h5_prop_t prop, ///> [in,out] identifier for file property list
MPI_Comm* comm ///> [in] MPI communicator
) {
H5_API_ENTER (h5_err_t, "prop=%p, comm=%p", (void*)prop, comm);
H5_API_RETURN (h5_set_prop_file_mpio_posix (prop, comm));
}
#endif
/**
\ingroup h5hut_file
Modifies the file property list to use the \c H5FD_CORE driver. The
\c H5FD_CORE driver enables an application to work with a file in memory.
File contents are stored only in memory until the file is closed.
The increment by which allocated memory is to be increased each time more
memory is required, can be specified with \ref H5SetPropFileAlign().
\see H5SetPropFileAlign()
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5SetPropFileCoreVFD (
h5_prop_t prop
h5_prop_t prop ///> [in,out] identifier for file property list
) {
H5_API_ENTER (h5_err_t, "prop=%p", (void*)prop);
H5_API_RETURN (h5_set_prop_file_core_vfd (prop));
}
/**
\ingroup h5hut_file
Sets alignment properties of a file property list so that any file
object greater than or equal in size to threshold bytes will be
aligned on an address which is a multiple of alignment. The
addresses are relative to the end of the user block; the alignment
is calculated by subtracting the user block size from the absolute
file address and then adjusting the address to be a multiple of
alignment.
Default values for alignment is one, implying no
alignment. Generally the default value result in the best
performance for single-process access to the file. For MPI IO and
other parallel systems, choose an alignment which is a multiple of
the disk block size.
\see H5SetPropFileCoreVFD()
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5SetPropFileAlign (
h5_prop_t prop,
h5_int64_t align
h5_prop_t prop, ///> [in,out] identifier for file property list
h5_int64_t align ///> [in] alignment
) {
H5_API_ENTER (h5_err_t, "prop=%p, align=%lld", (void*)prop, (long long int)align);
H5_API_RETURN (h5_set_prop_file_align (prop, align));
}
/*!
/**
\ingroup h5hut_file
Set the `throttle` factor, which causes HDF5 write and read
@@ -95,32 +209,35 @@ H5SetPropFileAlign (
H5_VFD_MPIO_INDEPENDENT drivers and is only available in
the parallel library.
\return \c H5_SUCCESS or \c H5_FAILURE
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5SetPropFileThrottle (
h5_prop_t prop,
h5_int64_t throttle
h5_prop_t prop, ///> [in,out] identifier for file property list
h5_int64_t throttle ///> [in] throttle factor
) {
H5_API_ENTER (h5_err_t, "prop=%p, throttle=%lld", (void*)prop, (long long int)throttle);
H5_API_RETURN (h5_set_prop_file_throttle (prop, throttle));
}
/**
\ingroup h5hut_file
Close file property list.
*/
static inline h5_err_t
H5CloseProp (
h5_prop_t prop
h5_prop_t prop ///> [in] identifier for file property list
) {
H5_API_ENTER (h5_err_t, "prop=%p", (void*)prop);
H5_API_RETURN (h5_close_prop (prop));
}
/*!
/**
\ingroup h5hut_file
<A NAME="H5OpenFile"></A>
Open file with name \c filename. This function is available in the parallel
and serial version. In the serial case \c comm may have any value.
Open file with name \c filename.
File mode flags are:
- \c H5_O_RDONLY: Only reading allowed
@@ -131,20 +248,23 @@ H5CloseProp (
- \c H5_VFD_MPIO_POSIX - use the HDF5 MPI-POSIX virtual file driver
- \c H5_VFD_MPIO_INDEPENDENT - use MPI-IO in indepedent mode
The typical file extension is \c .h5.
\c h5_file_p should be treated as an essentially opaque
datastructure. It acts as the file handle, but internally
it maintains several key state variables associated with
the file.
The file is opened with the properties set in the file property list
\c prop. This argument can also be set to \c H5_PROP_DEFAULT to use
reasonable default values. In this case \c MPI_COMM_WORLD will be
used as MPI communicator in a parallel execution environment.
\return File handle or \c (void*)H5_FAILURE
The typical file extension is \c .h5.
\see H5CreateFileProp()
\return File handle
\return \c H5_FAILURE on error
*/
static inline h5_file_t
H5OpenFile (
const char* filename,
h5_int64_t mode,
h5_prop_t props
const char* filename, ///> [in] name of file
h5_int64_t mode, ///> [in] file mode
h5_prop_t props ///> [in] identifier for file property list
) {
H5_API_ENTER (h5_file_t,
"filename='%s', mode=%lld, props=%p",
@@ -152,12 +272,13 @@ H5OpenFile (
H5_API_RETURN (h5_open_file2 (filename, mode, props));
}
/*!
/**
\ingroup h5hut_file
Close file and free all memory associated with the file handle.
\return \c H5_SUCCESS or \c H5_FAILURE
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5CloseFile (
@@ -169,12 +290,13 @@ H5CloseFile (
H5_API_RETURN (h5_close_file (f));
}
/*!
/**
\ingroup h5hut_file
Verify that the file handle points to a valid H5hut file structure.
Verify that the passed file handle is a valid H5hut file handle.
\return \c H5_SUCCESS or \c H5_FAILURE
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5CheckFile (
@@ -186,12 +308,13 @@ H5CheckFile (
H5_API_RETURN (h5_check_filehandle (f));
}
/*!
/**
\ingroup h5hut_file
Flush step data to disk.
\return \c H5_SUCCESS or \c H5_FAILURE
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5FlushStep (
@@ -203,12 +326,13 @@ H5FlushStep (
H5_API_RETURN (h5_flush_step (f));
}
/*!
/**
\ingroup h5hut_file
Flush file data to disk.
Flush all file data to disk.
\return \c H5_SUCCESS or \c H5_FAILURE
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5FlushFile (
@@ -220,12 +344,13 @@ H5FlushFile (
H5_API_RETURN (h5_flush_file (f));
}
/*!
/**
\ingroup h5hut_file
Close H5hut library. This function should be called before program exit.
\return \c H5_SUCCESS or \c H5_FAILURE
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5Finalize (
@@ -235,7 +360,7 @@ H5Finalize (
H5_API_RETURN (h5_close_hdf5 ());
}
/*!
/**
\ingroup h5hut_error
Set verbosity level to \c level.
@@ -249,7 +374,7 @@ H5SetVerbosityLevel (
return h5_set_debuglevel (level);
}
/*!
/**
\ingroup h5hut_error
Set error handler to \c handler.
@@ -264,7 +389,7 @@ H5SetErrorHandler (
H5_API_RETURN (h5_set_errorhandler (handler));
}
/*!
/**
\ingroup h5hut_error
Set the abort error handler.
@@ -279,7 +404,7 @@ H5AbortOnError (
H5_API_RETURN (h5_set_errorhandler (h5_abort_errorhandler));
}
/*!
/**
\ingroup h5hut_error
Get current error handler.
@@ -295,7 +420,7 @@ H5GetErrorHandler (
}
/*!
/**
\ingroup h5hut_error
The report error handler writes a message to stderr, sets the error number
@@ -311,7 +436,7 @@ H5ReportErrorhandler (
return h5_report_errorhandler (fmt, ap);
}
/*!
/**
\ingroup h5hut_error
The abort error handler writes a message to stderr and exits the programm.
@@ -326,7 +451,7 @@ H5AbortErrorhandler (
return h5_abort_errorhandler (fmt, ap);
}
/*!
/**
\ingroup h5hut_error
Get last error code.
src/include/H5Block_attribs.h
+11 -8
View File
@@ -20,14 +20,14 @@
extern "C" {
#endif
/*!
/**
\ingroup h5block_attrib
\anchor H5BlockGetNumFieldAttribs
Query the number of attributes of field \c field_name.
\return number of attributes
\return H5_FAILURE on error
\return \c H5_FAILURE on error
*/
static inline h5_ssize_t
H5BlockGetNumFieldAttribs (
@@ -40,7 +40,7 @@ H5BlockGetNumFieldAttribs (
H5_API_RETURN (h5b_get_num_field_attribs (f, field_name));
}
/*!
/**
\ingroup h5block_attrib
\anchor H5BlockGetFieldAttribInfo
@@ -52,7 +52,8 @@ H5BlockGetNumFieldAttribs (
minus one. The number of attributes bound to the
field can be queried by calling \ref H5BlockGetNumFieldAttribs.
\return \c H5_SUCCESS or \c H5_FAILURE
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5BlockGetFieldAttribInfo (
@@ -89,14 +90,15 @@ H5BlockGetFieldAttribInfo (
/********************** reading and writing attribute ************************/
/*!
/**
\ingroup h5block_attrib
\anchor H5BlockWriteFieldAttribString
Write the string in \c buffer as attribute \c attrib_name of field
\c field_name.
\return \c H5_SUCCESS or \c H5_FAILURE
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5BlockWriteFieldAttribString (
@@ -124,14 +126,15 @@ H5BlockWriteFieldAttribString (
strlen(buffer) + 1));
}
/*!
/**
\ingroup h5block_attrib
\anchor H5BlockReadFieldAttribString (
Read the string value from attribute \c attrib_name of field
\c field_name into \c buffer.
\return \c H5_SUCCESS or \c H5_FAILURE
\return \c H5_SUCCESS on success
\return \c H5_FAILURE on error
*/
static inline h5_err_t
H5BlockReadFieldAttribString (