Skip to main content

Files

Struct Files 

Source
pub struct Files<M: FilesMode = Writer> { /* private fields */ }
Expand description

Owns storage, database file operations and the device’s file area (Appendix F.3), for the store’s writer or a read-only handle (Files<ReadOnly>), which only reads files and keeps its cache. The writer’s starts one commit-driven worker, for uploads and pins; no sync loop or timer is created. Call close before closing the database.

Implementations§

Source§

impl Files

Source

pub async fn prepare_pin( &self, files: &[FileRef], ) -> Result<PreparedPin, FileReadError>

Prepare a pin of stored files (§17.8): download what each lacks, up to the download limit at once, into a whole cache copy written, synced and checked against its content hash, or note a checked whole copy already kept. Nothing is pinned until a write commits the result with its pin step. Each file’s download failure is its stored bytes’ pending record, as for any pin; a download that succeeds clears it. A file only on one device, this one included while it uploads, is refused: only stored bytes are kept. So is one whose record goes, or leaves its stored bytes, while they download (NoLongerStored). While the network is metered and the app moves files only on unmetered networks, the downloads wait before asking storage for bytes (§17.8).

Source

pub async fn get_cache_budget(&self, namespace: &str) -> Result<u64, DbError>

The namespace’s budget, declared or since set (E8).

Source§

impl Files

Source

pub async fn prepare_device_only( &self, folder: &Path, files: Vec<(FileId, RelativePath)>, cancel: &Receiver<bool>, progress: Sender<Option<Progress<DeviceOnlyStep>>>, ) -> Result<PreparedDeviceOnly, DeviceOnlyError>

Download each cloud file to its path under folder, for one write to switch them all to this device only, each copy becoming the original this device records (§17.3). Each download checks the file’s content hash, and each copy is written under a temporary name in its final folder and renamed once synced. Each name is written as the one rule for every platform makes it, which keeps it inside the folder. A path through a symbolic link below the folder, where something is already, or naming what another path names once written, case and Unicode form aside, is refused. progress hears each file’s download and how many of its bytes, and of the call’s, are down. Until it returns, cancel stops the call; a failure, a panic in a download among them, or a cancel removes every copy and folder the call made. The call waits once for a place of the app’s budget, before it holds anything, and reads each file’s stream in it in turn; its copy’s writer is outside the budget (§17.3).

Source§

impl<M: FilesMode> Files<M>

Source

pub async fn open_file_stream( &self, file: &FileRef, lease: &FileLease, ) -> Result<FileStream<M>, FileReadError>

Open the file as its record now stands: its bytes here while it is on this device only, uploading or not, or else its cached or stored bytes. A file only on another device can’t be read here (§17.7), and only such a file fails with DeviceOnly: a file that leaves this device only as it opens goes on as the record the open found says, which never keeps it here. The stream holds one place of lease until it drops.

Source

pub async fn read_file( &self, file: &FileRef, lease: &FileLease, ) -> Result<Vec<u8>, FileReadError>

Read the whole file, in one place of lease. A stored file is checked against its content hash; a file this device uploads reads as it is on disk (§17.7).

Source§

impl Files

Source

pub async fn file_status( &self, file: &FileRef, ) -> Result<FileStatus, FileReadError>

The file as its record now stands: a file this device uploads is judged from local facts with no storage request, one only on another device from its record, and a stored one by one fresh single-object status call for its fixed path. Network failures and denied access are errors, not absence.

Source§

impl<M: FilesMode> Files<M>

Source

pub fn reads_awaiting_connection(&self) -> Receiver<usize>

Follow how many reads wait for a coming connection now, for a test that goes on once a read waits.

Source§

impl Files

Source

pub fn expect_connection(&self) -> ConnectionComing

Note that a connection attempt is running: until the returned guard drops, reads that need storage wait for it rather than fail. The guard drops when the attempt ends, connected or not, and a store with no storage then reads as released.

Source§

impl Files

Source

pub fn closing(&self)

Note that the store is closing, before its connection is released: a read waiting for that connection, or asked after this, fails as the store closing, not as having no storage.

Source§

impl Files<ReadOnly>

Source

pub fn read_only( database: FileDatabase<ReadOnly>, directory: StoreDir, storage: Option<Arc<dyn Storage>>, send: Arc<SequenceState>, waits: Arc<RetryWaits>, ids: IdSourceRef, transfers: Arc<TransferBudget>, files: FileBudget, clock: ClockRef, network: NetworkView, ) -> Self

Compose a read-only handle’s file owner, which reads files and keeps its cache; it uploads, pins and records nothing, and runs no worker.

Source§

impl<M: FilesMode> Files<M>

Source

pub async fn close(&self)

Stop background work, wait for in-flight database and transfer work, then release the storage client, while clones of this owner live on. An app retry still waiting fails as the store closes, as does a read of a file stream still open.

Source§

impl Files

Source

pub fn uploads_parked_from_now( &self, ) -> impl Future<Output = ()> + Send + 'static

Each time the upload worker has taken every change, wake and due retry that was ready, and waits for the next.

Source

pub fn new( database: FileDatabase, directory: StoreDir, storage: Option<Arc<dyn Storage>>, send: Arc<SequenceState>, waits: Arc<RetryWaits>, ids: IdSourceRef, transfers: Arc<TransferBudget>, files: FileBudget, clock: ClockRef, network: NetworkView, ) -> Self

Compose the writer’s file owner and start its upload worker. Storage may be absent while uploads wait.

Source

pub fn transfer_limits(&self) -> TransferLimits

The limits shared by this handle’s transfer consumers.

Source

pub fn set_transfer_limits(&self, limits: TransferLimits)

Change upload and download admission. The next upload to start sees the new upload limit; uploads in flight keep running. Active response bodies retain their leases until they finish or are dropped.

Source

pub async fn retry_uploads_now(&self) -> Result<DrainOutcome, SyncError>

Optionally retry recoverable uploads early: the upload worker attempts every upload that can retry, whatever its wait, and this returns once each attempt has ended. Provider cooldowns and failures that never clear still hold (§17.9), and while uploads are paused only bound ones are tried; while sync is stopped none is (§17.4).

Source

pub fn set_uploads_paused( &self, sql: &SqlContext<'_, '_>, paused: bool, ) -> Result<(), DbError>

Persist the pause setting, as a step of sql’s write; a running trailing upload stops between confirmed parts, preserving its provider session (E7). Bound uploads run on (§17.4). Once the write commits, and before it returns, the copy parts check takes the new setting, after any upload run that read the old one has acted on it: so no retry asked after the write returns is answered from the setting it replaced.

Source

pub fn set_unmetered_only( &self, sql: &SqlContext<'_, '_>, unmetered_only: bool, ) -> Result<(), DbError>

Persist the setting to move files only on unmetered networks, as a step of sql‘s write (§17.9): while the network is metered, a running trailing upload stops between confirmed parts, as a pause stops it, and pins’ downloads wait before their next request to storage. Bound uploads run on. Once the write commits, and before it returns, the uploads and downloads take the new setting, as they take a pause.

Source

pub async fn set_storage( &self, storage: Option<Arc<dyn Storage>>, ready: impl Future<Output = Result<(), SyncError>>, ) -> Result<(), SyncError>

Finish transfers before verifying and committing a connection change. No upload starts meanwhile. A failed setup leaves the current connection installed.

Trait Implementations§

Source§

impl<M: FilesMode> Clone for Files<M>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more

Auto Trait Implementations§

§

impl<M = Writer> !RefUnwindSafe for Files<M>

§

impl<M = Writer> !UnwindSafe for Files<M>

§

impl<M> Freeze for Files<M>

§

impl<M> Send for Files<M>

§

impl<M> Sync for Files<M>

§

impl<M> Unpin for Files<M>

§

impl<M> UnsafeUnpin for Files<M>

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<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
§

impl<T> ErasedDestructor for T
where T: 'static,

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.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<Unshared, Shared> IntoShared<Shared> for Unshared
where Shared: FromUnshared<Unshared>,

§

fn into_shared(self) -> Shared

Creates a shared type from an unshared type.
§

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

§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] only if self and other return Action::Follow. Read more
§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns [Action::Follow] if either self or other returns Action::Follow. Read more
§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

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

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

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

Source§

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<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

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