1.. _module-pw_blob_store: 2 3============= 4pw_blob_store 5============= 6``pw_blob_store`` is a storage container library for storing a single blob of 7data. ``BlobStore`` is a flash-backed persistent storage system with integrated 8data integrity checking that serves as a lightweight alternative to a file 9system. 10 11----- 12Usage 13----- 14Most operations on a ``BlobStore`` are done using ``BlobReader`` and 15``BlobWriter`` objects that have been constructed using a ``BlobStore``. Though 16a ``BlobStore`` may have multiple open ``BlobReader`` objects, no other 17readers/writers may be active if a ``BlobWriter`` is opened on a blob store. 18 19The data state of a blob can be checked using the ``HasData()`` method. 20The method returns true if the blob is currenty valid and has at least one data 21byte. This allows checking if a blob has stored data without needing to 22instantiate and open a reader or writer. 23 24Write buffer 25============ 26 27BlobStore uses a write buffer to allow writes smaller than and/or unaligned to 28the flash write aligment. BlobStore also supports using the write buffer for 29deferred writes that can be enqueued and written to flash at a later time or by 30a different thread/context. 31 32BlobStore can be used with a zero-size write buffer to reduce memory 33requirements. When using zero-size write buffer, the user is required to write 34maintain write sizes that are a multiple of the flash write size the blob is 35configured for. 36 37If a non-zero sized write buffer is used, the write buffer size must be a 38multiple of the flash write size. 39 40Writing to a BlobStore 41---------------------- 42``BlobWriter`` objects are ``pw::stream::Writer`` compatible, but do not support 43reading any of the blob's contents. Opening a ``BlobWriter`` on a ``BlobStore`` 44that contains data will discard any existing data if ``Discard()``, ``Write 45()``, or ``Erase()`` are called. There is currently no mechanism to allow 46appending to existing data. 47 48.. code-block:: cpp 49 50 BlobStore::BlobWriterWithBuffer writer(my_blob_store); 51 writer.Open(); 52 writer.Write(my_data); 53 54 // ... 55 56 // A close is implied when a BlobWriter is destroyed. Manually closing a 57 // BlobWriter enables error handling on Close() failure. 58 writer.Close(); 59 60Erasing a BlobStore 61=================== 62There are two distinctly different mechanisms to "erase" the contents of a BlobStore: 63 64#. ``Discard()``: Discards any ongoing writes and ensures ``BlobReader`` objects 65 see the ``BlobStore`` as empty. This is the fastest way to logically erase a 66 ``BlobStore``. 67#. ``Erase()``: Performs an explicit flash erase of the ``BlobStore``'s 68 underlying partition. This is useful for manually controlling when a flash 69 erase is performed before a ``BlobWriter`` starts to write data (as flash 70 erase operations may be time-consuming). 71 72Naming a BlobStore's contents 73============================= 74Data in a ``BlobStore`` May be named similarly to a file. This enables 75identification of a BlobStore's contents in cases where different data may be 76stored to a shared blob store. This requires an additional RAM buffer that can 77be used to encode the BlobStore's KVS metadata entry. Calling 78``MaxFileNameLength()`` on a ``BlobWriter`` will provide the max file name 79length based on the ``BlobWriter``'s metadata encode buffer size. 80 81``SetFileName()`` performs a copy of the provided file name, meaning it's safe 82for the ``std::string_view`` to be invalidated after the function returns. 83 84.. code-block:: cpp 85 86 constexpr size_t kMaxFileNameLength = 48; 87 BlobStore::BlobWriterWithBuffer<kMaxFileNameLength> writer(my_blob_store); 88 writer.Open(); 89 writer.SetFileName("stonks.jpg"); 90 writer.Write(my_data); 91 // ... 92 writer.Close(); 93 94Reading from a BlobStore 95------------------------ 96A ``BlobStore`` may have multiple open ``BlobReader`` objects. No other 97readers/writers may be open/active if a ``BlobWriter`` is opened on a blob 98store. 99 100 0) Create BlobReader instance 101 1) BlobReader::Open(). 102 2) Read data using BlobReader::Read() or 103 BlobReader::GetMemoryMappedBlob(). BlobReader is seekable. Use 104 BlobReader::Seek() to read from a desired offset. 105 3) BlobReader::Close(). 106 107-------------------------- 108FileSystem RPC integration 109-------------------------- 110``pw_blob_store`` provides an optional ``FileSystemEntry`` implementation for 111use with ``pw_file``'s ``FlatFileSystemService``. This simplifies the process of 112enumerating ``BlobStore`` objects as files via ``pw_file``'s ``FileSystem`` RPC 113service. 114 115----------- 116Size report 117----------- 118The following size report showcases the memory usage of the blob store. 119 120.. include:: blob_size 121 122 123.. note:: 124 The documentation for this module is currently incomplete. 125
