Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_stakes_fd_epoch_credits_h
       2             : #define HEADER_fd_src_flamenco_stakes_fd_epoch_credits_h
       3             : 
       4             : #include "../fd_flamenco_base.h"
       5             : 
       6             : /* fd_epoch_credits_store_t tracks epoch credits through an epoch.  A
       7             :    new fd_epoch_credits_t is created at each epoch boundary.  The
       8             :    representation of the epoch credits is partially in-memory and
       9             :    partially on disk.  Once they are created, they are read again for
      10             :    the rest of the epoch.  This data structure is refcounted.
      11             :    Generally, the epoch credits are not expected to spill to disk and
      12             :    will only happen in degenerate network conditions.  It's assumed that
      13             :    epoch credits will only have one single-threaded caller.  The caller
      14             :    is expected to manage references to epoch credit forks. */
      15             : 
      16          24 : #define FD_EPOCH_CREDITS_FD          (123456)
      17         108 : #define FD_EPOCH_CREDITS_STORE_ALIGN (128UL)
      18             : 
      19             : struct fd_epoch_credits_store;
      20             : typedef struct fd_epoch_credits_store fd_epoch_credits_store_t;
      21             : 
      22             : struct fd_epoch_credits_view {
      23             :   fd_epoch_credits_t *       credits;
      24             :   fd_epoch_credits_store_t * store;
      25             :   ulong                      len;
      26             :   ulong                      set_idx;
      27             : };
      28             : typedef struct fd_epoch_credits_view fd_epoch_credits_view_t;
      29             : 
      30             : FD_PROTOTYPES_BEGIN
      31             : 
      32             : /* fd_epoch_credits_store_align returns the alignment of a
      33             :    fd_epoch_credits_store_t struct. */
      34             : 
      35             : ulong
      36             : fd_epoch_credits_store_align( void );
      37             : 
      38             : /* fd_epoch_credits_store_footprint sizes the epoch credits store for a
      39             :    given max_live_slots and cache_cnt. */
      40             : 
      41             : ulong
      42             : fd_epoch_credits_store_footprint( ulong max_live_slots,
      43             :                                   ulong cache_cnt );
      44             : 
      45             : /* fd_epoch_credits_store_new creates a epoch credits store object */
      46             : 
      47             : void *
      48             : fd_epoch_credits_store_new( void * shmem,
      49             :                             int    disk_fd,
      50             :                             ulong  max_live_slots,
      51             :                             ulong  cache_cnt );
      52             : 
      53             : /* fd_epoch_credits_store_join joins a shared memory region that
      54             :    corresponds to a valid fd_epoch_credits_store_t struct. */
      55             : 
      56             : fd_epoch_credits_store_t *
      57             : fd_epoch_credits_store_join( void * shmem,
      58             :                              int    disk_fd );
      59             : 
      60             : /* fd_epoch_credits_store_new_fork releases old_fork_id where USHORT_MAX
      61             :    is treated as a NULL sentinel then creates a new, empty fork in the
      62             :    epoch credits store and returns its fork id. */
      63             : 
      64             : ushort
      65             : fd_epoch_credits_store_new_fork( fd_epoch_credits_store_t * store,
      66             :                                  ushort                     old_fork_id );
      67             : 
      68             : /* fd_epoch_credits_store_acquire acquires a reference to a fork in the
      69             :    epoch credits store. */
      70             : 
      71             : void
      72             : fd_epoch_credits_store_acquire( fd_epoch_credits_store_t * store,
      73             :                                 ushort                     fork_id );
      74             : 
      75             : /* fd_epoch_credits_store_release releases a reference to a fork in the
      76             :    epoch credits store.  If the references reaches 0, the fork is
      77             :    "deleted". */
      78             : 
      79             : void
      80             : fd_epoch_credits_store_release( fd_epoch_credits_store_t * store,
      81             :                                 ushort                     fork_id );
      82             : 
      83             : /* fd_epoch_credits_view_{init,fini} pin and unpin the fork's set in
      84             :    memory, reading it from disk if needed.  These two must be paired
      85             :    together and is the only way to safely read or write the epoch
      86             :    credits.  _peek can be called safely while a view is pinned. */
      87             : 
      88             : fd_epoch_credits_view_t *
      89             : fd_epoch_credits_view_init( fd_epoch_credits_view_t *  view,
      90             :                             fd_epoch_credits_store_t * store,
      91             :                             ushort                     fork_id );
      92             : 
      93             : void
      94             : fd_epoch_credits_view_fini( fd_epoch_credits_view_t * view );
      95             : 
      96             : /* fd_epoch_credits_store_peek returns the in-memory epoch credits of
      97             :    fork_id and stores their count in *len.  It does not modify the
      98             :    store, so another thread may call it while a view pins the set.
      99             :    Crashes if the set is not pinned in memory. */
     100             : 
     101             : fd_epoch_credits_t const *
     102             : fd_epoch_credits_store_peek( fd_epoch_credits_store_t const * store,
     103             :                              ushort                           fork_id,
     104             :                              ulong *                          len );
     105             : 
     106             : /* fd_epoch_credits_store_reset resets the epoch credits store.  This
     107             :    is not meant for production use and is for testing only. */
     108             : 
     109             : void
     110             : fd_epoch_credits_store_reset( fd_epoch_credits_store_t * store );
     111             : 
     112             : 
     113             : FD_PROTOTYPES_END
     114             : 
     115             : #endif /* HEADER_fd_src_flamenco_stakes_fd_epoch_credits_h */