Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_stakes_fd_collector_overrides_h
       2             : #define HEADER_fd_src_flamenco_stakes_fd_collector_overrides_h
       3             : 
       4             : #include "../fd_flamenco_base.h"
       5             : 
       6             : /* fd_collector_overrides_t tracks SIMD-0232 commission collectors
       7             :    that differ from their defaults (inflation: the vote account,
       8             :    block revenue: the node identity).  A query miss means "use the
       9             :    default".
      10             : 
      11             :    Entries are captured once per epoch boundary from the vote account
      12             :    state at the start of the new epoch E, and tagged with E:
      13             :    inflation rewards distribution (at the boundary of E) queries tag
      14             :    E; block revenue collection during E queries tag E-1, the state
      15             :    its leader schedule was derived from.
      16             : 
      17             :    Vote account state can differ across forks crossing the boundary,
      18             :    so entries carry a fork membership bitmask.  Fork ids rotate at
      19             :    every boundary.  Entry content is immutable after creation: forks
      20             :    capturing identical state share an entry via their fork bit;
      21             :    divergent state gets a distinct entry.
      22             : 
      23             :    Concurrent queries are allowed; mutating operations take an
      24             :    exclusive lock internally.  The structure is only modified during
      25             :    boot and at epoch boundaries. */
      26             : 
      27        3078 : #define FD_COLLECTOR_OVERRIDES_ALIGN (128UL)
      28             : 
      29             : /* Maximum number of child forks represented alongside the root. */
      30      659028 : #define FD_COLLECTOR_OVERRIDES_MAX_FORK_WIDTH (4096UL)
      31             : 
      32             : /* Query result flags */
      33          87 : #define FD_COLLECTOR_OVERRIDE_INFLATION (1)
      34         153 : #define FD_COLLECTOR_OVERRIDE_BLOCK     (2)
      35             : 
      36             : struct fd_collector_overrides;
      37             : typedef struct fd_collector_overrides fd_collector_overrides_t;
      38             : 
      39             : FD_PROTOTYPES_BEGIN
      40             : 
      41             : ulong
      42             : fd_collector_overrides_align( void );
      43             : 
      44             : /* fd_collector_overrides_footprint returns the footprint for at most
      45             :    max_overrides entries.  Entries per epoch tag are bounded by the
      46             :    VAT-admitted vote account set (FD_RUNTIME_MAX_VAT_VOTE_ACCOUNTS):
      47             :    the admitted-set capture path enforces the bound directly, and the
      48             :    pre-VAT capture path creates no entries because non-default
      49             :    collectors require the custom_commission_collector feature, which
      50             :    is assumed inactive before the validator admission ticket.  Up to
      51             :    three tags can be live at once across the fork tree: forks that
      52             :    have not crossed the epoch boundary still query tags E-2/E-1 while
      53             :    forks past it hold E-1/E.  Boundary forks that captured divergent
      54             :    state add one entry per distinct content, at most one per
      55             :    boundary-crossing fork (max_fork_width).  Size for the product of
      56             :    the three; exhaustion is a fail-stop (FD_LOG_CRIT in
      57             :    fd_collector_overrides_upsert) rather than a silent fallback to
      58             :    default collectors. */
      59             : 
      60             : ulong
      61             : fd_collector_overrides_footprint( ulong max_overrides );
      62             : 
      63             : void *
      64             : fd_collector_overrides_new( void * shmem,
      65             :                             ulong  max_overrides,
      66             :                             ulong  seed );
      67             : 
      68             : fd_collector_overrides_t *
      69             : fd_collector_overrides_join( void * shmem );
      70             : 
      71             : /* fd_collector_overrides_new_child allocates a fork id for a fork
      72             :    crossing the epoch boundary.  The new fork starts with no visible
      73             :    entries; call fd_collector_overrides_inherit to make the parent's
      74             :    entries visible. */
      75             : 
      76             : ushort
      77             : fd_collector_overrides_new_child( fd_collector_overrides_t * co );
      78             : 
      79             : /* fd_collector_overrides_inherit makes the parent fork's entries with
      80             :    epoch >= min_epoch visible on the child fork.  Entries older than
      81             :    min_epoch can no longer be queried by the child and are dropped
      82             :    from it. */
      83             : 
      84             : void
      85             : fd_collector_overrides_inherit( fd_collector_overrides_t * co,
      86             :                                 ushort                     parent_idx,
      87             :                                 ushort                     child_idx,
      88             :                                 ulong                      min_epoch );
      89             : 
      90             : /* fd_collector_overrides_advance_root moves the root to root_idx.
      91             :    All other forks are released and entries only visible on them are
      92             :    freed.  A no-op if root_idx is already the root. */
      93             : 
      94             : void
      95             : fd_collector_overrides_advance_root( fd_collector_overrides_t * co,
      96             :                                      ushort                     root_idx );
      97             : 
      98             : /* fd_collector_overrides_purge_child releases a non-root fork.  A
      99             :    no-op if fork_idx is the root. */
     100             : 
     101             : void
     102             : fd_collector_overrides_purge_child( fd_collector_overrides_t * co,
     103             :                                     ushort                     fork_idx );
     104             : 
     105             : /* fd_collector_overrides_reset returns the structure to its initial
     106             :    state (used when loading a new snapshot manifest). */
     107             : 
     108             : void
     109             : fd_collector_overrides_reset( fd_collector_overrides_t * co );
     110             : 
     111             : ushort
     112             : fd_collector_overrides_get_root_idx( fd_collector_overrides_t * co );
     113             : 
     114             : /* fd_collector_overrides_upsert records the non-default collectors
     115             :    for (pubkey, epoch) on the given fork.  Pass has_inflation /
     116             :    has_block=0 for a collector that is default (at least one must be
     117             :    set).  A fork joins an existing identical entry, else a new entry
     118             :    is created. */
     119             : 
     120             : void
     121             : fd_collector_overrides_upsert( fd_collector_overrides_t * co,
     122             :                                ushort                     fork_idx,
     123             :                                ulong                      epoch,
     124             :                                fd_pubkey_t const *        pubkey,
     125             :                                int                        has_inflation,
     126             :                                fd_pubkey_t const *        inflation,
     127             :                                int                        has_block,
     128             :                                fd_pubkey_t const *        block );
     129             : 
     130             : /* fd_collector_overrides_query returns which collectors of
     131             :    (pubkey, epoch) are overridden on the given fork, as a bitwise OR
     132             :    of FD_COLLECTOR_OVERRIDE_{INFLATION,BLOCK} (0 if none: use the
     133             :    defaults).  NULL out params are skipped; out params are only
     134             :    written for overridden collectors. */
     135             : 
     136             : int
     137             : fd_collector_overrides_query( fd_collector_overrides_t * co,
     138             :                               ushort                     fork_idx,
     139             :                               ulong                      epoch,
     140             :                               fd_pubkey_t const *        pubkey,
     141             :                               fd_pubkey_t *              inflation_out_opt,
     142             :                               fd_pubkey_t *              block_out_opt );
     143             : 
     144             : /* fd_collector_overrides_ele_cnt returns the number of live entries
     145             :    (across all forks and epochs).  Intended for tests and metrics. */
     146             : 
     147             : ulong
     148             : fd_collector_overrides_ele_cnt( fd_collector_overrides_t * co );
     149             : 
     150             : FD_PROTOTYPES_END
     151             : 
     152             : #endif /* HEADER_fd_src_flamenco_stakes_fd_collector_overrides_h */