github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/module/mempool/README.md (about)

     1  # The `mempool` module
     2  
     3  The `mempool` module provides mempool implementations for the Flow blockchain, which
     4  are in-memory data structures that are tasked with storing the `flow.Entity` objects.
     5  `flow.Entity` objects are the fundamental data model of the Flow blockchain, and
     6  every Flow primitives such as transactions, blocks, and collections are represented
     7  as `flow.Entity` objects.
     8  
     9  Each mempool implementation is tasked for storing a specific type of `flow.Entity`.
    10  As a convention, all mempools are built on top of the `stdmap.Backend` struct, which
    11  provides a thread-safe cache implementation for storing and retrieving `flow.Entity` objects.
    12  The primary responsibility of the `stdmap.Backend` struct is to provide thread-safety for its underlying
    13  data model (i.e., `mempool.Backdata`) that is tasked with maintaining the actual `flow.Entity` objects.
    14  
    15  At the moment, the `mempool` module provides two implementations for the `mempool.Backdata`:
    16  - `backdata.Backdata`: a map implementation for storing `flow.Entity` objects using native Go `map`s.
    17  - `herocache.Cache`: a cache implementation for storing `flow.Entity` objects, which is a heap-optimized
    18      cache implementation that is aims on minimizing the memory footprint of the mempool on the heap and 
    19      reducing the GC pressure.
    20  
    21  Note-1: by design the `mempool.Backdata` interface is **not thread-safe**. Therefore, it is the responsibility
    22  of the `stdmap.Backend` struct to provide thread-safety for its underlying `mempool.Backdata` implementation.
    23  
    24  Note-2: The `herocache.Cache` implementation is several orders of magnitude faster than the `backdata.Backdata` on
    25  high-throughput workloads. For the read or write-heavy workloads, the `herocache.Cache` implementation is recommended as
    26  the underlying `mempool.Backdata` implementation.