LCOV - code coverage report
Current view: top level - choreo/forks - fd_forks.h (source / functions) Hit Total Coverage
Test: cov.lcov Lines: 0 16 0.0 %
Date: 2025-07-01 05:00:49 Functions: 0 10 0.0 %

          Line data    Source code
       1             : #ifndef HEADER_fd_src_choreo_forks_fd_forks_h
       2             : #define HEADER_fd_src_choreo_forks_fd_forks_h
       3             : 
       4             : #include "../../flamenco/runtime/context/fd_exec_slot_ctx.h"
       5             : #include "../../flamenco/runtime/fd_blockstore.h"
       6             : #include "../fd_choreo_base.h"
       7             : #include "../ghost/fd_ghost.h"
       8             : #include "../voter/fd_voter.h"
       9             : 
      10             : /* FD_FORKS_USE_HANDHOLDING:  Define this to non-zero at compile time
      11             :    to turn on additional runtime checks and logging. */
      12             : 
      13             : #ifndef FD_FORKS_USE_HANDHOLDING
      14             : #define FD_FORKS_USE_HANDHOLDING 1
      15             : #endif
      16             : 
      17             : struct fd_fork {
      18             :   ulong slot; /* the fork head and frontier key */
      19             :   ulong next; /* reserved for use by fd_pool and fd_map_chain */
      20             :   ulong prev; /* reserved for use by fd_forks_publish */
      21             :   int   lock; /* IMPORTANT SAFETY TIP! lock is a boolean indicating
      22             :                  whether a fork's most recent block is still being
      23             :                  actively replayed (executed) and should generally not
      24             :                  be read or written to by downstream consumers (eg.
      25             :                  consensus, publishing) and should definitely not be
      26             :                  removed. */
      27             :   uint  end_idx; /* the end_idx of the last batch executed on this fork */
      28             : };
      29             : 
      30             : typedef struct fd_fork fd_fork_t;
      31             : 
      32             : #define POOL_NAME fd_fork_pool
      33           0 : #define POOL_T    fd_fork_t
      34             : #include "../../util/tmpl/fd_pool.c"
      35             : 
      36             : #define MAP_NAME  fd_fork_frontier
      37             : #define MAP_ELE_T fd_fork_t
      38           0 : #define MAP_KEY   slot
      39             : #include "../../util/tmpl/fd_map_chain.c"
      40             : 
      41             : /* fd_forks maintains all the outstanding fork heads known as the
      42             :    frontier.  The memory required for these fork heads is pre-allocated
      43             :    in `pool`.
      44             : 
      45             :    {processed, confirmed, finalized} correspond to the highest slots
      46             :    that have achieved each of these cluster commitment levels. This is
      47             :    based on what Firedancer has locally observed, so these values are
      48             :    not atomically synchronized with other nodes in the cluster (ie.
      49             :    other nodes may report higher or lower slot numbers for each of
      50             :    these) but are "eventually consistent" as long as Firedancer is
      51             :    connected to the cluster and replaying blocks. All three values are
      52             :    strictly monotonically increasing.
      53             : 
      54             :    processed - a slot has been replayed.
      55             :    confirmed - a slot has been "optimistically confirmed" ie. 2/3 of
      56             :                stake has voted for it.
      57             :    finalized - a slot has been "supermajority rooted" ie. 2/3 of stake
      58             :                has rooted it or any of its descendants. */
      59             : 
      60             : struct fd_forks {
      61             :   fd_fork_frontier_t * frontier; /* map of slot->fd_fork_t */
      62             :   fd_fork_t *          pool;     /* memory pool of fd_fork_t */
      63             :   ulong                processed;
      64             :   ulong                confirmed;
      65             :   ulong                finalized;
      66             : };
      67             : typedef struct fd_forks fd_forks_t;
      68             : 
      69             : /* fd_forks_{align,footprint} return the required alignment and
      70             :    footprint of a memory region suitable for use as forks with up to max
      71             :    fork heads in the frontier. */
      72             : 
      73             : FD_FN_CONST static inline ulong
      74           0 : fd_forks_align( void ) {
      75           0 :   return alignof( fd_forks_t );
      76           0 : }
      77             : 
      78             : FD_FN_CONST static inline ulong
      79           0 : fd_forks_footprint( ulong max ) {
      80           0 :   return FD_LAYOUT_FINI(
      81           0 :     FD_LAYOUT_APPEND(
      82           0 :     FD_LAYOUT_APPEND(
      83           0 :     FD_LAYOUT_APPEND(
      84           0 :     FD_LAYOUT_INIT,
      85           0 :       alignof(fd_forks_t),      sizeof(fd_forks_t) ),
      86           0 :       fd_fork_pool_align(),     fd_fork_pool_footprint( max ) ),
      87           0 :       fd_fork_frontier_align(), fd_fork_frontier_footprint( max ) ),
      88           0 :     alignof(fd_forks_t) );
      89           0 : }
      90             : 
      91             : /* fd_forks_new formats an unused memory region for use as a forks.  mem
      92             :    is a non-NULL pointer to this region in the local address space with
      93             :    the required footprint and alignment. */
      94             : 
      95             : void *
      96             : fd_forks_new( void * shmem, ulong max, ulong seed );
      97             : 
      98             : /* fd_forks_join joins the caller to the forks.  forks points to the
      99             :    first byte of the memory region backing the forks in the caller's
     100             :    address space.
     101             : 
     102             :    Returns a pointer in the local address space to forks on success. */
     103             : 
     104             : fd_forks_t *
     105             : fd_forks_join( void * forks );
     106             : 
     107             : /* fd_forks_leave leaves a current local join.  Returns a pointer to the
     108             :    underlying shared memory region on success and NULL on failure (logs
     109             :    details).  Reasons for failure include forks is NULL. */
     110             : 
     111             : void *
     112             : fd_forks_leave( fd_forks_t const * forks );
     113             : 
     114             : /* fd_forks_delete unformats a memory region used as a forks.  Assumes
     115             :    only the local process is joined to the region. Returns a pointer to
     116             :    the underlying shared memory region or NULL if used obviously in
     117             :    error (e.g. forks is obviously not a forks ... logs details).  The
     118             :    ownership of the memory region is transferred to the caller. */
     119             : 
     120             : void *
     121             : fd_forks_delete( void * forks );
     122             : 
     123             : /* fd_forks_init initializes forks.  Assumes forks is a valid local join
     124             :    and no one else is joined, and slot  Inserts the first fork.
     125             :    Returns fork on success, NULL on failure.
     126             : 
     127             :    In general, this should be called by the same process that formatted
     128             :    forks' memory, ie. the caller of fd_forks_new. */
     129             : 
     130             : fd_fork_t *
     131             : fd_forks_init( fd_forks_t * forks, ulong slot );
     132             : 
     133             : /* fd_forks_query queries for the fork corresponding to slot in the
     134             :    frontier.  Returns the fork if found, otherwise NULL. */
     135             : 
     136             : fd_fork_t *
     137             : fd_forks_query( fd_forks_t * forks, ulong slot );
     138             : 
     139             : /* fd_forks_query_const is the const version of the above. */
     140             : 
     141             : fd_fork_t const *
     142             : fd_forks_query_const( fd_forks_t const * forks, ulong slot );
     143             : 
     144             : /* fd_forks_advance advances a parent_slot to slot in the frontier.
     145             :    Assumes parent_slot corresponds to a fork currently in the frontier
     146             :    (ie. has already been prepared), slot is a child of parent_slot, and
     147             :    parent_slot has already been replayed.  Fails if fork is not frozen.
     148             :    Returns the updated fork on success, NULL on failure. */
     149             : 
     150             : fd_fork_t *
     151             : fd_forks_advance( fd_forks_t const * forks, fd_fork_t * fork, ulong slot );
     152             : 
     153             : /* fd_forks_prepare prepares a fork for execution.  The fork will either
     154             :    be an existing fork in the frontier if parent_slot is already a fork
     155             :    head or it will start a new fork at parent_slot and add it to the
     156             :    frontier.
     157             : 
     158             :    Returns fork on success, NULL on failure.  Failure reasons include
     159             :    parent_slot is not present in the blockstore, is not present in funk,
     160             :    or does not have a valid ancestry.
     161             : 
     162             :    It is possible for the fork to return NULL in a non-error condition.
     163             :    For example, a leader tries to rollback and start a new fork from a
     164             :    very old slot that the blockstore has already pruned. In this
     165             :    scenario, we cannot prepare a new fork at parent_slot because we have
     166             :    already rooted past it. */
     167             : 
     168             : fd_fork_t *
     169             : fd_forks_prepare( fd_forks_t const *    forks,
     170             :                   ulong                 parent_slot,
     171             :                   fd_funk_t *           funk,
     172             :                   fd_blockstore_t *     blockstore,
     173             :                   fd_spad_t *           runtime_spad );
     174             : 
     175             : /* fd_forks_publish publishes a new root into forks.  Assumes root is a
     176             :    valid slot that exists in the cluster and has already been replayed.
     177             :    This prunes all the existing forks in the frontier except descendants
     178             :    of root.  Forks that are not frozen will also not be pruned (warns
     179             :    when handholding is enabled).  */
     180             : 
     181             : void
     182             : fd_forks_publish( fd_forks_t * fork, ulong root );
     183             : 
     184             : /* fd_forks_print prints a forks as a list of the frontiers and number
     185             :    of forks (pool eles acquired). */
     186             : 
     187             : void
     188             : fd_forks_print( fd_forks_t const * forks );
     189             : 
     190             : #endif /* HEADER_fd_src_choreo_forks_fd_forks_h */

Generated by: LCOV version 1.14