path: root/util/memory/blob.h

#pragma once

#include <util/generic/fwd.h>
#include <util/generic/strbuf.h>
#include <util/generic/utility.h>
#include <util/system/defaults.h>

class TMemoryMap;
class IInputStream;
class TFile;
class TBuffer;

enum class EMappingMode {
    /// Just mmap a file allowing lazy page loading at access
    Standard,
    /// Same as previous but warmup the buffer with sequential access to it's data
    Precharged,
    /// Try to lock file in memory so that it doesn't wash away. See mlock(2)
    Locked
};

/// @addtogroup BLOBs
/// @{
class TBlob {
public:
    class TBase {
    public:
        inline TBase() noexcept = default;
        virtual ~TBase() = default;

        virtual void Ref() noexcept = 0;
        virtual void UnRef() noexcept = 0;
    };

private:
    struct TStorage {
        const void* Data;
        size_t Length;
        TBase* Base;

        inline TStorage(const void* data, size_t length, TBase* base) noexcept
            : Data(data)
            , Length(length)
            , Base(base)
        {
        }

        inline ~TStorage() = default;

        inline void Swap(TStorage& r) noexcept {
            DoSwap(Data, r.Data);
            DoSwap(Length, r.Length);
            DoSwap(Base, r.Base);
        }
    };

public:
    using value_type = ui8;
    using const_reference = const value_type&;
    using const_pointer = const value_type*;
    using const_iterator = const_pointer;

    /**
     * Constructs a null blob (data array points to nullptr).
     */
    TBlob() noexcept
        : S_(nullptr, 0, nullptr)
    {
    }

    inline TBlob(const TBlob& r) noexcept
        : S_(r.S_)
    {
        Ref();
    }

    TBlob(TBlob&& r) noexcept
        : TBlob()
    {
        this->Swap(r);
    }

    inline TBlob(const void* data, size_t length, TBase* base) noexcept
        : S_(data, length, base)
    {
        Ref();
    }

    inline ~TBlob() {
        UnRef();
    }

    inline TBlob& operator=(const TBlob& r) noexcept {
        TBlob(r).Swap(*this);

        return *this;
    }

    inline TBlob& operator=(TBlob&& r) noexcept {
        TBlob(std::move(r)).Swap(*this);

        return *this;
    }

    /// Swaps content of two data arrays.
    inline void Swap(TBlob& r) noexcept {
        S_.Swap(r.S_);
    }

    /// Returns a const reference to the data array.
    inline const void* Data() const noexcept {
        return S_.Data;
    }

    /// Returns the size of the data array in bytes.
    inline size_t Length() const noexcept {
        return S_.Length;
    }

    /// Checks if the object has an empty data array.
    Y_PURE_FUNCTION inline bool Empty() const noexcept {
        return !Length();
    }

    /// Checks if the blob owns data
    Y_PURE_FUNCTION inline bool OwnsData() const noexcept {
        return S_.Base != nullptr;
    }

    /// Checks if the object has a data array.
    inline bool IsNull() const noexcept {
        return !Data();
    }

    /// Returns a const pointer of char type to the data array.
    inline const char* AsCharPtr() const noexcept {
        return (const char*)Data();
    }

    /// Returns a const pointer of unsigned char type to the data array.
    inline const unsigned char* AsUnsignedCharPtr() const noexcept {
        return (const unsigned char*)Data();
    }

    inline TStringBuf AsStringBuf() const noexcept {
        return TStringBuf(AsCharPtr(), size());
    }

    /// Drops the data array.
    inline void Drop() noexcept {
        TBlob().Swap(*this);
    }

    /*
     * Some stl-like methods
     */

    /// Returns a const reference to the data array.
    /// result type is const ui8* which is not consistent with Data method above
    /// but it's consistent with operator[], Begin and End methods below
    /// Also it allows us to construct TArrayRef from TBlob
    inline const_pointer data() const noexcept {
        return static_cast<const_pointer>(Data());
    }

    /// Returns the size of the data array in bytes.
    inline size_t size() const noexcept {
        return Length();
    }

    /// Returns the size of the data array in bytes.
    inline size_t Size() const noexcept {
        return Length();
    }

    /// Standard iterator.
    inline const_iterator Begin() const noexcept {
        return AsUnsignedCharPtr();
    }

    /// Standard iterator.
    inline const_iterator End() const noexcept {
        return Begin() + Size();
    }

    inline value_type operator[](size_t n) const noexcept {
        return *(Begin() + n);
    }

    /// Shortcut to SubBlob(0, len)
    TBlob SubBlob(size_t len) const;

    /// Creates a new object from the provided range [begin, end) of internal data. No memory allocation and no copy.
    /// @details Increments the refcounter of the current object
    TBlob SubBlob(size_t begin, size_t end) const;

    /// Calls Copy() for the internal data.
    TBlob DeepCopy() const;

    /// Creates a new blob with a single-threaded (non atomic) refcounter. Dynamically allocates memory and copies the data content.
    static TBlob CopySingleThreaded(const void* data, size_t length);

    /// Creates a new blob with a multi-threaded (atomic) refcounter. Dynamically allocates memory and copies the data content.
    static TBlob Copy(const void* data, size_t length);

    /// Creates a blob which doesn't own data. No refcounter, no memory allocation, no data copy.
    static TBlob NoCopy(const void* data Y_LIFETIME_BOUND, size_t length);

    /// Creates a blob with a single-threaded (non atomic) refcounter. It maps the file on the path as data.
    static TBlob FromFileSingleThreaded(const TString& path, EMappingMode);

    /// Creates a blob with a multi-threaded (atomic) refcounter. It maps the file on the path as data.
    static TBlob FromFile(const TString& path, EMappingMode);

    /// Creates a blob with a single-threaded (non atomic) refcounter. It maps the file on the path as data.
    static TBlob FromFileSingleThreaded(const TFile& file, EMappingMode);

    /// Creates a blob with a multi-threaded (atomic) refcounter. It maps the file on the path as data.
    static TBlob FromFile(const TFile& file, EMappingMode);

    /// Creates a blob with a single-threaded (non atomic) refcounter. It maps the file on the path as data.
    static TBlob FromFileSingleThreaded(const TString& path);

    /// Creates a blob with a multi-threaded (atomic) refcounter. It maps the file on the path as data.
    static TBlob FromFile(const TString& path);

    /// Creates a blob with a single-threaded (non atomic) refcounter. It maps the file on the path as data.
    static TBlob FromFileSingleThreaded(const TFile& file);

    /// Creates a blob with a multi-threaded (atomic) refcounter. It maps the file on the path as data.
    static TBlob FromFile(const TFile& file);

    // TODO: drop Precharged* functions.

    /// Creates a precharged blob with a single-threaded (non atomic) refcounter. It maps the file on the path as data.
    static TBlob PrechargedFromFileSingleThreaded(const TString& path);

    /// Creates a precharged blob with a multi-threaded (atomic) refcounter. It maps the file on the path as data.
    static TBlob PrechargedFromFile(const TString& path);

    /// Creates a precharged blob with a single-threaded (non atomic) refcounter. It maps the file content as data.
    static TBlob PrechargedFromFileSingleThreaded(const TFile& file);

    /// Creates a precharged blob with a multi-threaded (atomic) refcounter. It maps the file content as data.
    static TBlob PrechargedFromFile(const TFile& file);

    /// Creates a locked blob with a single-threaded (non atomic) refcounter. It maps the file on the path as data.
    static TBlob LockedFromFileSingleThreaded(const TString& path);

    /// Creates a locked blob with a multi-threaded (atomic) refcounter. It maps the file on the path as data.
    static TBlob LockedFromFile(const TString& path);

    /// Creates a locked blob with a single-threaded (non atomic) refcounter. It maps the file content as data.
    static TBlob LockedFromFileSingleThreaded(const TFile& file);

    /// Creates a locked blob with a multi-threaded (atomic) refcounter. It maps the file content as data.
    static TBlob LockedFromFile(const TFile& file);

    /// Creates a locked blob with a single-threaded (non atomic) refcounter from the mapped memory.
    static TBlob LockedFromMemoryMapSingleThreaded(const TMemoryMap& map, ui64 offset, size_t length);

    /// Creates a locked blob with a multi-threaded (atomic) refcounter from the mapped memory.
    static TBlob LockedFromMemoryMap(const TMemoryMap& map, ui64 offset, size_t length);

    /// Creates a blob with a single-threaded (non atomic) refcounter from the mapped memory.
    static TBlob FromMemoryMapSingleThreaded(const TMemoryMap& map, ui64 offset, size_t length);

    /// Creates a blob with a multi-threaded (atomic) refcounter from the mapped memory.
    static TBlob FromMemoryMap(const TMemoryMap& map, ui64 offset, size_t length);

    /// Creates a blob with a single-threaded (non atomic) refcounter. Dynamically allocates memory and copies data from the file on the path using pread().
    static TBlob FromFileContentSingleThreaded(const TString& path);

    /// Creates a blob with a multi-threaded (atomic) refcounter. Dynamically allocates memory and copies data from the file on the path using pread().
    static TBlob FromFileContent(const TString& path);

    /// Creates a blob with a single-threaded (non atomic) refcounter. Dynamically allocates memory and copies data from the file using pread().
    static TBlob FromFileContentSingleThreaded(const TFile& file);

    /// Creates a blob with a multi-threaded (atomic) refcounter. Dynamically allocates memory and copies data from the file using pread().
    static TBlob FromFileContent(const TFile& file);

    /// Creates a blob with a single-threaded (non atomic) refcounter. Dynamically allocates memory and copies data from the provided range of the file content using pread().
    static TBlob FromFileContentSingleThreaded(const TFile& file, ui64 offset, size_t length);

    /// Creates a blob with a multi-threaded (atomic) refcounter. Dynamically allocates memory and copies data from the provided range of the file content using pread().
    static TBlob FromFileContent(const TFile& file, ui64 offset, size_t length);

    /// Creates a blob from the stream content with a single-threaded (non atomic) refcounter.
    static TBlob FromStreamSingleThreaded(IInputStream& in);

    /// Creates a blob from the stream content with a multi-threaded (atomic) refcounter.
    static TBlob FromStream(IInputStream& in);

    /// Creates a blob with a single-threaded (non atomic) refcounter. No memory allocation, no content copy.
    /// @details The input object becomes empty.
    static TBlob FromBufferSingleThreaded(TBuffer& in);

    /// Creates a blob with a multi-threaded (atomic) refcounter. No memory allocation, no content copy.
    /// @details The input object becomes empty.
    static TBlob FromBuffer(TBuffer& in);

    /// Creates a blob from TString with a single-threaded (non atomic) refcounter.
    static TBlob FromStringSingleThreaded(const TString& s);

    /// Creates a blob from TString with a single-threaded (non atomic) refcounter. Doesn't copy its content.
    static TBlob FromStringSingleThreaded(TString&& s);

    /// Creates a blob from TString with a multi-threaded (atomic) refcounter.
    static TBlob FromString(const TString& s);

    /// Creates a blob from TString with a multi-threaded (atomic) refcounter. Doesn't copy its content.
    static TBlob FromString(TString&& s);

private:
    inline void Ref() noexcept {
        if (S_.Base) {
            S_.Base->Ref();
        }
    }

    inline void UnRef() noexcept {
        if (S_.Base) {
            S_.Base->UnRef();
        }
    }

private:
    TStorage S_;
};

/// @}