From 649bf42b7918e84c8636449024d22a0b702ad4f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Oberhuber?= <oberhuber.tomas@gmail.com>
Date: Sun, 10 Mar 2019 21:00:54 +0100
Subject: [PATCH] Updating the File documentation.
---
src/TNL/File.h | 51 +++++++++++++++++++++++++++++---------------------
1 file changed, 30 insertions(+), 21 deletions(-)
diff --git a/src/TNL/File.h b/src/TNL/File.h
index f79b244013..882d1c725f 100644
--- a/src/TNL/File.h
+++ b/src/TNL/File.h
@@ -21,7 +21,7 @@
namespace TNL {
/**
- * \brief This class serves for binary IO. It allows to do IO even for data allocated on GPU
+ * \brief This class serves for binary IO. It allows to do IO even for data allocated on GPU together with on-the-fly data type conversion.
*
* \par Example
* \include FileExample.cpp
@@ -57,7 +57,7 @@ class File
* Throws \ref std::ios_base::failure on failure.
*
* \param fileName String which indicates file name.
- * \param mode Indicates in what mode the will be opened - see. \ref File::Mode.
+ * \param mode Indicates in what mode the file will be opened - see. \ref File::Mode.
*/
void open( const String& fileName,
Mode mode = static_cast< Mode >( static_cast< int >( Mode::In ) | static_cast< int >( Mode::Out ) ) );
@@ -78,34 +78,43 @@ class File
}
/**
- * \brief Method for reading data with given \e Type from the file.
+ * \brief Method for loading data from the file.
*
* The data will be stored in \e buffer allocated on device given by the
- * \e Device parameter.
+ * \e Device parameter. The data type of the buffer is given by the
+ * template parameter \e Type. The second template parameter
+ * \e SourceType defines the type of data in the source file. If both
+ * types are different, on-the-fly conversion takes place during the
+ * data loading.
*
* Throws \ref std::ios_base::failure on failure.
*
- * \tparam Type Type of data.
- * \tparam Device Device where the data are stored after reading. For example \ref Devices::Host or \ref Devices::Cuda.
- * \tparam SourceType Type of index by which the elements are indexed.
+ * \tparam Type type of data to be loaded to the \e buffer.
+ * \tparam SourceType type of data stored on the file,
+ * \tparam Device device where the data are stored after reading. For example \ref Devices::Host or \ref Devices::Cuda.
* \param buffer Pointer in memory where the elements are loaded and stored after reading.
- * \param elements Number of elements the user wants to get (read) from given file.
+ * \param elements number of elements to be loaded from the file.
*/
template< typename Type, typename SourceType = Type, typename Device = Devices::Host >
void load( Type* buffer, std::streamsize elements = 1 );
/**
- * \brief Method that can write particular data type from CPU into given file. (Function that writes particular elements into given file.)
+ * \brief Method for saving data to the file.
*
- * Returns \e true when the elements are successfully written into given file. Otherwise returns \e false.
+ * The data from the \e buffer (with type \e Type) allocated on the device
+ * \e Device will be saved into the file. \e TargetType defines as what
+ * data type the buffer shall be saved. If the type is different from the
+ * data type, on-the-fly data type conversion takes place during the data
+ * saving.
*
* Throws \ref std::ios_base::failure on failure.
*
- * \tparam Type Type of data.
- * \tparam Device Place from where the data are loaded before writing into file. For example \ref Devices::Host or \ref Devices::Cuda.
- * \tparam Index Type of index by which the elements are indexed.
- * \param buffer Pointer in memory where the elements are loaded from before writing into file.
- * \param elements Number of elements the user wants to write into the given file.
+ * \tparam Type type of data in the \e buffer.
+ * \tparam TargetType tells as what type data the buffer shall be saved.
+ * \tparam Device device from where the data are loaded before writing into file. For example \ref Devices::Host or \ref Devices::Cuda.
+ * \tparam Index type of index by which the elements are indexed.
+ * \param buffer buffer that is going to be saved to the file.
+ * \param elements number of elements saved to the file.
*/
template< typename Type, typename TargetType = Type, typename Device = Devices::Host >
void save( const Type* buffer, std::streamsize elements = 1 );
@@ -156,12 +165,12 @@ class File
std::fstream file;
String fileName;
- /**
- * When we transfer data between the GPU and the CPU we use 5 MB buffer. This
- * size should ensure good performance -- see.
- * http://wiki.accelereyes.com/wiki/index.php/GPU_Memory_Transfer .
- * We use the same buffer size even for retyping data during IO operations.
- */
+ ////
+ // When we transfer data between the GPU and the CPU we use 5 MB buffer. This
+ // size should ensure good performance -- see.
+ // http://wiki.accelereyes.com/wiki/index.php/GPU_Memory_Transfer .
+ // We use the same buffer size even for retyping data during IO operations.
+ //
static constexpr std::streamsize TransferBufferSize = 5 * 2<<20;
};
--
GitLab