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