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_spad_t * runtime_spad ); 173 : 174 : /* fd_forks_publish publishes a new root into forks. Assumes root is a 175 : valid slot that exists in the cluster and has already been replayed. 176 : This prunes all the existing forks in the frontier except descendants 177 : of root. Forks that are not frozen will also not be pruned (warns 178 : when handholding is enabled). */ 179 : 180 : void 181 : fd_forks_publish( fd_forks_t * fork, ulong root ); 182 : 183 : /* fd_forks_print prints a forks as a list of the frontiers and number 184 : of forks (pool eles acquired). */ 185 : 186 : void 187 : fd_forks_print( fd_forks_t const * forks ); 188 : 189 : #endif /* HEADER_fd_src_choreo_forks_fd_forks_h */
