Struct ProgramCache

pub struct ProgramCache<FG: ForkGraph> {
    pub latest_root_slot: Slot,
    pub latest_root_epoch: Epoch,
    pub environments: ProgramRuntimeEnvironments,
    pub upcoming_environments: Option<ProgramRuntimeEnvironments>,
    pub programs_to_recompile: Vec<(Pubkey, Arc<ProgramCacheEntry>)>,
    pub stats: ProgramCacheStats,
    pub fork_graph: Option<Weak<RwLock<FG>>>,
    pub loading_task_waiter: Arc<LoadingTaskWaiter>,
    /* private fields */
}

This structure is the global cache of loaded, verified and compiled programs.

It …

• is validator global and fork graph aware, so it can optimize the commonalities across banks.
• handles the visibility rules of un/re/deployments.
• stores the usage statistics and verification status of each program.
• is elastic and uses a probabilistic eviction stragety based on the usage statistics.
• also keeps the compiled executables around, but only for the most used programs.
• supports various kinds of tombstones to avoid loading programs which can not be loaded.
• cleans up entries on orphan branches when the block store is rerooted.
• supports the cache preparation phase before feature activations which can change cached programs.
• manages the environments of the programs and upcoming environments for the next epoch.
• allows for cooperative loading of TX batches which hit the same missing programs simultaneously.
• enforces that all programs used in a batch are eagerly loaded ahead of execution.
• is not persisted to disk or a snapshot, so it needs to cold start and warm up first.

Fields

latest_root_slot: Slot

The slot of the last rerooting

latest_root_epoch: Epoch

The epoch of the last rerooting

environments: ProgramRuntimeEnvironments

Environments of the current epoch

upcoming_environments: Option<ProgramRuntimeEnvironments>

Anticipated replacement for environments at the next epoch

This is None during most of an epoch, and only Some around the boundaries (at the end and beginning of an epoch). More precisely, it starts with the cache preparation phase a few hundred slots before the epoch boundary, and it ends with the first rerooting after the epoch boundary.

programs_to_recompile: Vec<(Pubkey, Arc<ProgramCacheEntry>)>

List of loaded programs which should be recompiled before the next epoch (but don’t have to).

stats: ProgramCacheStats

Statistics counters

fork_graph: Option<Weak<RwLock<FG>>>

Reference to the block store

loading_task_waiter: Arc<LoadingTaskWaiter>

Coordinates TX batches waiting for others to complete their task during cooperative loading

Implementations

impl<FG: ForkGraph> ProgramCache<FG>

pub fn new(root_slot: Slot, root_epoch: Epoch) -> Self

pub fn set_fork_graph(&mut self, fork_graph: Weak<RwLock<FG>>)

pub fn get_environments_for_epoch( &self, epoch: Epoch, ) -> ProgramRuntimeEnvironments

Returns the current environments depending on the given epoch

pub fn get_upcoming_environments_for_epoch( &self, epoch: Epoch, ) -> Option<ProgramRuntimeEnvironments>

Returns the upcoming environments depending on the given epoch

pub fn assign_program( &mut self, key: Pubkey, entry: Arc<ProgramCacheEntry>, ) -> bool

Insert a single entry. It’s typically called during transaction loading, when the cache doesn’t contain the entry corresponding to program key.

pub fn prune_by_deployment_slot(&mut self, slot: Slot)

pub fn prune(&mut self, new_root_slot: Slot, new_root_epoch: Epoch)

Before rerooting the blockstore this removes all superfluous entries

pub fn extract( &self, search_for: &mut Vec<(Pubkey, (ProgramCacheMatchCriteria, u64))>, loaded_programs_for_tx_batch: &mut ProgramCacheForTxBatch, is_first_round: bool, ) -> Option<(Pubkey, u64)>

Extracts a subset of the programs relevant to a transaction batch and returns which program accounts the accounts DB needs to load.

pub fn finish_cooperative_loading_task( &mut self, slot: Slot, key: Pubkey, loaded_program: Arc<ProgramCacheEntry>, ) -> bool

Called by Bank::replenish_program_cache() for each program that is done loading.

pub fn merge( &mut self, modified_entries: &HashMap<Pubkey, Arc<ProgramCacheEntry>>, )

pub fn get_flattened_entries( &self, include_program_runtime_v1: bool, _include_program_runtime_v2: bool, ) -> Vec<(Pubkey, Arc<ProgramCacheEntry>)>

Returns the list of entries which are verified and compiled.

pub fn get_flattened_entries_for_tests( &self, ) -> Vec<(Pubkey, Arc<ProgramCacheEntry>)>

Returns the list of all entries in the cache.

pub fn get_slot_versions_for_tests( &self, key: &Pubkey, ) -> &[Arc<ProgramCacheEntry>]

Returns the slot versions for the given program id.

pub fn sort_and_unload(&mut self, shrink_to: PercentageInteger)

Unloads programs which were used infrequently

pub fn evict_using_2s_random_selection( &mut self, shrink_to: PercentageInteger, now: Slot, )

Evicts programs using 2’s random selection, choosing the least used program out of the two entries. The eviction is performed enough number of times to reduce the cache usage to the given percentage.

pub fn remove_programs(&mut self, keys: impl Iterator<Item = Pubkey>)

Removes all the entries at the given keys, if they exist

Trait Implementations

impl<FG: ForkGraph> Debug for ProgramCache<FG>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.