include/highfive/H5File.hpp

0001 /*
0002  *  Copyright (c), 2017, Adrien Devresse <adrien.devresse@epfl.ch>
0003  *
0004  *  Distributed under the Boost Software License, Version 1.0.
0005  *    (See accompanying file LICENSE_1_0.txt or copy at
0006  *          http://www.boost.org/LICENSE_1_0.txt)
0007  *
0008  */
0009 #pragma once
0010
0011 #include <string>
0012
0013 #include "H5FileDriver.hpp"
0014 #include "H5Object.hpp"
0015 #include "H5PropertyList.hpp"
0016 #include "bits/H5Annotate_traits.hpp"
0017 #include "bits/H5Node_traits.hpp"
0018
0019 namespace HighFive {
0020
0021 ///
0022 /// \brief File class
0023 ///
0024 class File: public Object, public NodeTraits<File>, public AnnotateTraits<File> {
0025   public:
0026     const static ObjectType type = ObjectType::File;
0027
0028     enum : unsigned {
0029         /// Open flag: Read only access
0030         ReadOnly = 0x00u,
0031         /// Open flag: Read Write access
0032         ReadWrite = 0x01u,
0033         /// Open flag: Truncate a file if already existing
0034         Truncate = 0x02u,
0035         /// Open flag: Open will fail if file already exist
0036         Excl = 0x04u,
0037         /// Open flag: Open in debug mode
0038         Debug = 0x08u,
0039         /// Open flag: Create non existing file
0040         Create = 0x10u,
0041         /// Derived open flag: common write mode (=ReadWrite|Create|Truncate)
0042         Overwrite = Truncate,
0043         /// Derived open flag: Opens RW or exclusively creates
0044         OpenOrCreate = ReadWrite | Create
0045     };
0046
0047     ///
0048     /// \brief File
0049     /// \param filename: filepath of the HDF5 file
0050     /// \param openFlags: Open mode / flags ( ReadOnly, ReadWrite)
0051     /// \param fileAccessProps: the file access properties
0052     ///
0053     /// Open or create a new HDF5 file
0054     explicit File(const std::string& filename,
0055                   unsigned openFlags = ReadOnly,
0056                   const FileAccessProps& fileAccessProps = FileAccessProps::Default());
0057
0058     ///
0059     /// \brief File
0060     /// \param filename: filepath of the HDF5 file
0061     /// \param openFlags: Open mode / flags ( ReadOnly, ReadWrite)
0062     /// \param fileCreateProps: the file create properties
0063     /// \param fileAccessProps: the file access properties
0064     ///
0065     /// Open or create a new HDF5 file
0066     File(const std::string& filename,
0067          unsigned openFlags,
0068          const FileCreateProps& fileCreateProps,
0069          const FileAccessProps& fileAccessProps = FileAccessProps::Default());
0070
0071     ///
0072     /// \brief Return the name of the file
0073     ///
0074     const std::string& getName() const noexcept;
0075
0076
0077     /// \brief Object path of a File is always "/"
0078     std::string getPath() const noexcept {
0079         return "/";
0080     }
0081
0082     /// \brief Returns the block size for metadata in bytes
0083     hsize_t getMetadataBlockSize() const;
0084
0085     /// \brief Returns the HDF5 version compatibility bounds
0086     std::pair<H5F_libver_t, H5F_libver_t> getVersionBounds() const;
0087
0088 #if H5_VERSION_GE(1, 10, 1)
0089     /// \brief Returns the HDF5 file space strategy.
0090     H5F_fspace_strategy_t getFileSpaceStrategy() const;
0091
0092     /// \brief Returns the page size, if paged allocation is used.
0093     hsize_t getFileSpacePageSize() const;
0094 #endif
0095
0096     ///
0097     /// \brief flush
0098     ///
0099     /// Flushes all buffers associated with a file to disk
0100     ///
0101     void flush();
0102
0103     /// \brief Get the list of properties for creation of this file
0104     FileCreateProps getCreatePropertyList() const {
0105         return details::get_plist<FileCreateProps>(*this, H5Fget_create_plist);
0106     }
0107
0108     /// \brief Get the list of properties for accession of this file
0109     FileAccessProps getAccessPropertyList() const {
0110         return details::get_plist<FileAccessProps>(*this, H5Fget_access_plist);
0111     }
0112
0113     /// \brief Get the size of this file in bytes
0114     size_t getFileSize() const;
0115
0116     /// \brief Get the amount of tracked, unused space in bytes.
0117     ///
0118     /// Note, this is a wrapper for `H5Fget_freespace` and returns the number
0119     /// bytes in the free space manager. This might be different from the total
0120     /// amount of unused space in the HDF5 file, since the free space manager
0121     /// might not track everything or not track across open-close cycles.
0122     size_t getFreeSpace() const;
0123
0124   protected:
0125     File() = default;
0126     using Object::Object;
0127
0128   private:
0129     mutable std::string _filename{};
0130
0131     template <typename>
0132     friend class PathTraits;
0133 };
0134
0135 }  // namespace HighFive
0136
0137 // H5File is the main user constructible -> bring in implementation headers
0138 #include "bits/H5Annotate_traits_misc.hpp"
0139 #include "bits/H5File_misc.hpp"
0140 #include "bits/H5Node_traits_misc.hpp"
0141 #include "bits/H5Path_traits_misc.hpp"