pub enum NeededBlobsRequest {
    OpenMetaBlob {
        blob_type: BlobType,
        responder: NeededBlobsOpenMetaBlobResponder,
    },
    GetMissingBlobs {
        iterator: ServerEnd<BlobInfoIteratorMarker>,
        control_handle: NeededBlobsControlHandle,
    },
    OpenBlob {
        blob_id: BlobId,
        blob_type: BlobType,
        responder: NeededBlobsOpenBlobResponder,
    },
    BlobWritten {
        blob_id: BlobId,
        responder: NeededBlobsBlobWrittenResponder,
    },
    Abort {
        responder: NeededBlobsAbortResponder,
    },
}
Expand description

Represents the transaction for caching a particular package.

Server expects client to follow the normal operation sequence defined below. Violating the protocol (e.g. calling wrong methods at the wrong time) will result in the channel being closed by the package cache with a ZX_ERR_BAD_STATE epitaph and aborting the package cache operation. If a fatal error occurs at any step, server will close the channel, and client should not proceed with the sequence. Non-fatal errors could be retried, as long as the channel remains open.

Normal operation sequence:

  1. Clients should start by requesting to OpenMetaBlob(), and fetch and write the metadata blob if needed, calling BlobWritten() when done to indicate the write is complete.
  2. GetMissingBlobs() should be used to determine which blobs need to be fetched and written.
  3. Each of the missing blobs needs to be written using OpenBlob() and BlobWritten() should be called after each blob is written.

Clients must not make multiple Open[Meta]Blob() calls for the same BlobId at the same time, even across different NeededBlobs connections. I.e. there should be at most one outstanding Open[Meta]Blob() call per BlobId per PackageCache server. Violating this may result in errors in later uses of the protocol.

Once all needed blobs are written by the client, the package cache will complete the pending [PackageCache.Get] request and close this channel with a ZX_OK epitaph.

Variants§

§

OpenMetaBlob

Opens the package’s metadata blob for writing. GetMissingBlobs() should not be called until writing the meta blob or this request responds with false.

If the package was already cached, server will close the channel with a ZX_OK epitaph.

  • request blob_type the type of the blob to be written. Will be removed once the transition to offline compression is complete.
  • response writer is used to write the blob. If writer is absent, the blob is already cached and so does not need to be written.
  • error an OpenBlobError indicating failure. Clients may retry this request, though the server end may abort this cache operation on errors it considers to be fatal.
§

GetMissingBlobs

Fields

§iterator: ServerEnd<BlobInfoIteratorMarker>

Returns an iterator of blobs that are not present on the system that must be written using the OpenBlob request before the package will be fully cached.

Client should call OpenMetaBlob, and write it if needed, before calling GetMissingBlobs.

A client should make this request no more than once per NeededBlobs connection. Once all blobs yielded by this iterator are written, the package open request will complete.

New items may be added to the obtained BlobInfoIterator as the client calls OpenBlob, so, to guaranatee termination of the iterator, clients should call OpenBlob concurrently with reading the iterator.

  • request iterator a request for an iterator of BlobInfo of blobs that the client should try to write.
§

OpenBlob

Fields

§blob_id: BlobId
§blob_type: BlobType

Opens a blob for writing.

  • request blob_id the blob id describing this blob.
  • request blob_type the type of the blob to be written. Will be removed once the transition to offline compression is complete.
  • response writer is used to write the blob. If writer is absent, the blob is already cached and so does not need to be written.
  • error an OpenBlobError indicating failure. Clients may retry this request, though the server end may abort this cache operation on errors it considers to be fatal.
§

BlobWritten

Indicates that a blob opened by Open[Meta]Blob has been successfully written.

A client should call this once the blob has been fully written using the writer returned by Open[Meta]Blob.

  • request blob_id the blob id describing this blob.
  • error a BlobWrittenError indicating failure. Clients may retry the Open[Meta]Blob request that prompted this call, though the server end may abort this cache operation on errors it considers to be fatal.
§

Abort

Aborts this caching operation for the package.

Any open blobs and any missing blobs iterator will be closed. Any dir provided to the associated [PackageCache.Get] request will also be closed. Once this request is acknowledged, this channel will be closed.

Note, dropping this NeededBlobs channel without writing all needed blobs will also abort the package cache operation. However, this API provides the ability to wait for the operation to be torn down.

Implementations§

Trait Implementations§

source§

impl Debug for NeededBlobsRequest

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Encode<Ambiguous1> for T

§

unsafe fn encode( self, _encoder: &mut Encoder<'_>, _offset: usize, _depth: Depth ) -> Result<(), Error>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID. Read more
§

impl<T> Encode<Ambiguous2> for T

§

unsafe fn encode( self, _encoder: &mut Encoder<'_>, _offset: usize, _depth: Depth ) -> Result<(), Error>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more