BmnFileReaderZStd.h

Go to the documentation of this file.

#pragma once
#ifndef BmnFileReaderZStd_h
#define BmnFileReaderZStd_h
 
// headers from this target
#include "BmnIArchiveLibRead.h"
#include "BmnIFileReader.h"
#include "BmnReaderCacheManager.h"
 
// keeping it only as a declaration so one would be able to include the header even if <zstd.h> is not in the include
// list
struct ZSTD_DCtx_s;
 
/*
 * A class responsible for reading compressed ZSTD files. The primary goal of this class is to read
 * large compressed files (possibly a few GB) such as those for raw data. If smaller files are used,
 * there might be better ways to compress/uncompress data (e.g., with dictionaries), but such cases
 * were not considered while preparing this class - if needed, add a new one that handles such cases
 * or upgrade this.
 * It's advisable to allocate this class on the heap as internally it uses big std::array
 * @warning Using this class directly can result in throws if the zstd library is not found during compilation.
 *          Therefore, it's always advisable to obtain appropriate read objects through
 * `BmnCompressionCreateNewSuitableReaderForAFile`
 */
class BmnFileReaderZStd
    : public BmnIFileReader
    , public BmnIArchiveLibRead
{
  public:
    /*
     * A standard constructor that sets a path to the input binary (ZSTD) file
     * @note The constructor will not check whether the file actually exists
     * @param fileName A path (most likely relative) to the input binary (ZSTD) file
     * @warning If using relative paths, be very careful about currently-working directory as it might
     *          be something unexpected based on the directory that initalized an application
     */
    explicit BmnFileReaderZStd(const std::string& fileName = "");
 
    /*
     * A standard constructor that sets a path to the input binary (ZSTD) file
     * @note The constructor will not check whether the file actually exists
     * @param fileName A path (most likely relative) to the input binary (ZSTD) file
     * @warning If using relative paths, be very careful about currently-working directory as it might
     *          be something unexpected based on the directory that initalized an application
     */
    explicit BmnFileReaderZStd(std::string&& fileName);
 
    /*
     * A standard constructor that sets a path to the input binary (ZSTD) file
     * @note The constructor will not check whether the file actually exists
     * @param filePath A path to the input binary (ZSTD) file
     * @warning If using relative paths, be very careful about currently-working directory as it might
     *          be something unexpected based on the directory that initalized an application
     */
    explicit BmnFileReaderZStd(const std::filesystem::path& filePath);
 
    /*
     * A standard constructor that sets a path to the input binary (ZSTD) file
     * @note The constructor will not check whether the file actually exists
     * @param filePath A path to the input binary (ZSTD) file
     * @warning If using relative paths, be very careful about currently-working directory as it might
     *          be something unexpected based on the directory that initalized an application
     */
    explicit BmnFileReaderZStd(std::filesystem::path&& filePath);
 
    // Closes the stream while destroying the instance
    virtual ~BmnFileReaderZStd() override;
    BmnFileReaderZStd(const BmnFileReaderZStd&) = delete;
    BmnFileReaderZStd& operator=(const BmnFileReaderZStd&) = delete;
    BmnFileReaderZStd(BmnFileReaderZStd&&) noexcept = delete;
    BmnFileReaderZStd& operator=(BmnFileReaderZStd&&) noexcept = delete;
 
    // ========== BmnIFileReaderInterface ==========
 
    /*
     * Opens a file for reading. The path of the file should be provided before calling this method
     * @param processingFlags A flag that tells us how to open the file for reading. This class only supports
     * `ReadBinary` flag
     */
    virtual void Open(
        const BmnBinaryFileProcessingOptions processingFlags = BmnBinaryFileProcessingOptions::ReadBinary) override;
 
    /*
     * Closes the stream and resets all internal data. After calling `Close`, it's safe to reopen using the same
     * instance of this class
     */
    virtual void Close() noexcept override;
 
    /*
     * Reads and decompresses the data while still managing caching for efficiency.
     * @param dataToFill A buffer that will be filled with uncompressed data
     * @param sizeToFill A number of bytes that will be filled in `dataToFill`
     * @return A number of bytes that were filled in `dataToFill`. This value should almost always be the same as
     * `sizeToFill` except when the end of the stream is reached (only if the user asked for more data than possible)
     */
    virtual int64_t Read(void* dataToFill, const int64_t sizeToFill) override;
 
    /*
     * A method that tells us what's next to read
     * @return A position of the next byte that should be read
     */
    [[nodiscard]] virtual int64_t Tell() const noexcept override;
 
    /*
     * A method that allows us to go to another place in the file (uncompressed data) and read from that place.
     * This method is NOT EFFICIENT as it still needs to uncompress data to reach the needed place!
     * @param value A position in uncompressed data to which one wants to move before the next read
     */
    virtual void Seek(int64_t value) override;
 
    /*
     * Checks whether the reading stream is good
     * @return 'true' if no decompression error has occurred and the input-file stream is good, or 'false' otherwise
     */
    [[nodiscard]] virtual bool IsGood() const noexcept override;
 
    /*
     * Check if we have reached the file. This will tell us if we have reached EOF in the uncompressed data, not
     * in the file itself. That is, the file might be at EOF, while this method returns will return true as cache
     * still has some data
     * @return 'true' if both file and internal cache are completely read, 'false' otherwise
     */
    [[nodiscard]] virtual bool IsEOF() const noexcept override;
 
    /*
     * A method that clears bad flags after an error has occurred. Just calling this error will most likely
     * not solve the problem, and you will get an error again in the next read. That is, before calling `Read`,
     * remove the previous error source
     */
    virtual void ClearStateFlags() override;
 
    /*
     * @return 'true' if the input stream is open, or 'false' if not
     */
    [[nodiscard]] virtual bool IsOpen() const noexcept override;
 
    // ========== BmnIArchiveLib Interface ==========
 
    /*
     * A method that is called to uncompress ZSTD data
     * @param source A pointer to a buffer with the subsequent compressed data that should be uncompressed
     * @param sourceTotalSize A number of bytes available in the source buffer
     * @param numberOfReadBytes A number of bytes that were consumed by ZSTD while compressing. This value will be set.
     * @param output A pointer to a buffer that will be filled with uncompressed data
     * @param outputTotalSize A number of bytes that may be filled in the output buffer
     * @param numberOfSetOutputBytes A number of bytes that were set while decompressing. This value will be set.
     * @return There are a few options:
     *      1. `BmnFileStreamResults::FileNotOpen` if the stream is not open
     *      2. `BmnFileStreamResults::TryingToReadBadStream` if the stream previously hit an error while it wasn't
     * cleared later
     *      3. `BmnFileStreamResults::UnexpectedFail` ZSTD failed while decompressing
     *      4. `BmnFileStreamResults::ReachedEOF` ZSTD reached the end of frame (in our case file)
     *      5. `BmnFileStreamResults::Success` ZSTD successfully uncompressed the package
     */
    virtual BmnFileStreamResults Uncompress(const void* source,
                                            const size_t sourceTotalSize,
                                            size_t& numberOfReadBytes,
                                            void* output,
                                            const size_t outputTotalSize,
                                            size_t& numberOfSetOutputBytes) override;
 
    /*
     * If an error occurred while decompressing, this method can be called to obtain a description of the error
     * @return A description of an error that occurred while decompressing, or an empty string if no such error happened
     */
    [[nodiscard]] virtual std::string GetLastUncompressErrorDescription() const noexcept override;
 
    /*
     * @return 'false' - this class doesn't allow jumping
     */
    [[nodiscard]] virtual bool JumpsAllowed() const noexcept override;
 
    /*
     * This method will do nothing but print an error. ZSTD doesn't allow us to efficiently jump over the compressed
     * file
     */
    virtual void JumpTo(size_t) override;
 
    /*
     * A method that tells us how many uncompressed bytes were read from an input file
     * @return A number of uncompressed bytes that passed through the ZSTD
     */
    [[nodiscard]] virtual size_t GetNumberOfDecompressedBytes() const noexcept override;
 
    /*
     * A method that checks whether there's something left in ZSTD cache, i.e., if we should
     * continue reading even though we have reached the end of the stream. If stream is in a
     * bad state, it will also return as EOF
     * @return 'true' if the underlying stream has a bad state or empty internal cache, or 'false' otherwise
     */
    [[nodiscard]] virtual bool HasReachedTheEndOfStream() const noexcept override;
 
    /*
     * A method that tells us whether an underlying ZSTD stream reported an error or not
     * @return 'true' if previous read calls didn't report an error, otherwise 'false'
     */
    [[nodiscard]] virtual bool IsStreamInGoodState() const noexcept override;
 
    // ========== BmnFileReaderZStd inlines ==========
 
    [[nodiscard]] inline ZSTD_DCtx_s* GetUnderlyingLibraryHandler() const noexcept;
    [[nodiscard]] inline size_t GetLastReadReturnValue() const noexcept;
    // Get number of read bytes via `GetNumberOfDecompressedBytes`
    // No need to expose `fArchiveReadManager`
 
  private:
    ZSTD_DCtx_s* fZstdStream;
    BmnReaderCacheManager<32ull * 1024ull, 64ull * 1024ull> fArchiveReadManager;
    size_t fNumberOfReadBytes;
    size_t fLastReadReturnValue;   // possibly carries information about an error that occurred
};
 
// o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o
// ================== BmnFileReaderZStd inline methods ==================
// o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o o
 
ZSTD_DCtx_s* BmnFileReaderZStd::GetUnderlyingLibraryHandler() const noexcept
{
    return fZstdStream;
}
 
size_t BmnFileReaderZStd::GetLastReadReturnValue() const noexcept
{
    return fLastReadReturnValue;
}
 
#endif   // BmnFileReaderZStd_h