Struct CacheAgent 

pub struct CacheAgent { /* private fields */ }

Shared state for an agent hosted by the process that owns a build session.

Transport listeners deliberately live in the embedder so the session lifecycle owns them. This type only contains ecosystem-independent CAS and protocol logic.

Implementations

impl CacheAgent

pub fn new(cache_dir: impl Into<PathBuf>, version: impl Into<Arc<str>>) -> Self

Create an agent backed by the cache rooted at cache_dir.

pub fn new_remote( cache_dir: impl Into<PathBuf>, version: impl Into<Arc<str>>, remote: AgentRemoteCache, ) -> Self

Create an agent with local-first access to a remote action cache.

pub fn new_remote_with_download_limit( cache_dir: impl Into<PathBuf>, version: impl Into<Arc<str>>, remote: AgentRemoteCache, max_remote_download_bytes: u64, ) -> Self

Create a remote agent with a cumulative download budget for the session.

pub fn with_observer(self, observer: Arc<dyn AgentEventObserver>) -> Self

Report each accounted cache decision to observer as it happens.

pub fn with_task_loader( self, loader: Arc<dyn for<'a> Fn(&'a CacheAgent, &'a str) -> BoxFuture<'a, ()> + Send + Sync>, ) -> Self

Load tasks on demand.

The loader is called with the agent and the task’s identity before the first request that names a task this agent has not begun, and is expected to begin it; a second call for the same task must be a no-op. Requests that name no task never wait on it.

pub async fn begin_task(&self, task: &str) -> Result<String>

Load the last committed action manifest for a task into this session.

pub async fn begin_task_on_prediction(&self, task: &str) -> Result<String>

Load a task but defer each adapter’s speculative downloads until its first prediction matches the current build.

pub async fn begin_session_task(&self, task: &str) -> Result<()>

Load a task using its identity as the run key.

A task-scoped process has only one run for an identity, so it can defer this work until its first client connects while putting the identity in the client’s environment ahead of time.

pub fn register_task_fallbacks( &self, task: &str, fallbacks: impl Fn() -> Vec<String> + Send + Sync + 'static, ) -> Result<()>

Name where a task’s predictions may come from when nothing has been recorded under its own identity.

The identities are produced on demand rather than taken up front, because finding them can cost a few version-control commands and most builds never need them. The first manifest found, locally and then on the remote, is adopted under the task’s own identity, so the commands that follow, tests and lints included, start from it too, and a trusted build publishes it there. When none of the named identities has one, the store’s newest manifests are tried.

pub async fn prefetch_task(&self, task: &str) -> Result<String>

Load a task and finish its prefetch, surfacing remote lookup failures.

pub async fn cancel_prefetches(&self)

Cancel speculative downloads before the owning session exits.

pub async fn wait_for_uploads(&self)

Publish everything a build queued, before the session stops.

Store requests return once an object is durable locally, so at this point the remote cache may still be behind the local one. Uploads run on the session’s runtime and are abandoned if it goes away, so a session that wants them published has to wait here.

pub async fn commit_task(&self, run: &str) -> Result<()>

Atomically publish the completed actions collected by a task run.

pub async fn commit_task_actions( &self, run: &str, ) -> Result<Vec<ActionPrediction>>

Publish a task run and return exactly the predictions completed by it.

The persisted task manifest also carries predictions inherited from earlier runs. Callers that need a receipt for this one run must not mistake that cumulative manifest for the work the run completed.

pub fn stats(&self) -> AgentStats

Return a snapshot of this session’s cache activity.

pub async fn handle_requests( &self, requests: impl IntoIterator<Item = AgentRequest>, ) -> Vec<AgentResponse>

Handle requests without a transport connection.

Persistent wrappers use this entry point when Cargo invokes mbx outside an orchestrated session. It intentionally has the same response semantics as Self::handle_connection, while leaving framing and the version handshake to callers that actually cross a process boundary.

pub fn seed_file_digests( &self, entries: Vec<(FileDigestScope, RecordedFileDigest)>, ) -> usize

Start the file-digest ledger from entries an earlier session left behind, so a file nothing has touched since is not read again by the first compilation of this session that names it.

Each entry stands only while its recorded identity still matches the disk, the same rule a lookup applies to what this session recorded, so a stale seed costs a hash and nothing else. Entries this session has already recorded are kept over seeded ones. Returns how many were taken.

pub fn seed_file_digests_with( &self, load: impl FnOnce() -> Vec<(FileDigestScope, RecordedFileDigest)>, ) -> usize

Seed the ledger from entries produced under its lock.

A lookup that arrives while load is still reading waits for it rather than missing, so a caller can start the read in the background and let whatever else the build is doing overlap it.

pub fn file_digests(&self) -> Vec<(FileDigestScope, RecordedFileDigest)>

Everything the file-digest ledger holds, for a later session to start from.

pub async fn handle_connection<S>(&self, stream: S) -> Result<()>

where S: AsyncRead + AsyncWrite + Unpin,

Serve newline-delimited protocol requests on an authenticated session stream.

Trait Implementations

impl Clone for CacheAgent

fn clone(&self) -> CacheAgent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.