pub struct DownloadResult<E, PullError, PushError>where
E: Executor + Send + Sync,
PullError: Send + Unpin + 'static,
PushError: Send + Unpin + 'static,{ /* private fields */ }Expand description
Handle to an active download session.
Cheaply cloneable shared handle. The underlying download keeps running as
long as any clone is alive, and is cancelled only once the last clone is
dropped. An explicit abort cancels immediately.
DownloadResult wraps Arc<DownloadResultInner> and exposes the session
methods (abort, set_threads, set_min_chunk_size, is_aborted) and
event_chain directly; each delegates to the inner
value. There is intentionally no Deref impl — DownloadResultInner
is private, so callers reach session state only through these methods.
The inner value is held in a ForceSend, a deliberately isolated
workaround so the handle is Send even when it is built inside an async
block (see that type’s module docs).
Completion is observed by draining the event stream: once the last sender is
dropped (the download finished or was aborted) the receiver disconnects, so
while result.recv().await.is_ok() {} awaits the session end. recv
is the Send-safe form of that call; prefer it over
result.event_chain().recv() in a tokio::spawned driver.
Implementations§
Source§impl<E, PullError, PushError> DownloadResult<E, PullError, PushError>
impl<E, PullError, PushError> DownloadResult<E, PullError, PushError>
Sourcepub fn event_chain(&self) -> &MAsyncRx<List<Event<PullError, PushError>>>
pub fn event_chain(&self) -> &MAsyncRx<List<Event<PullError, PushError>>>
Access the stream of Events emitted during the session.
The receiver closes once the last clone of this handle is dropped or the session is aborted, so draining it is a natural way to observe progress.
Sourcepub fn recv(
&self,
) -> impl Future<Output = Result<Event<PullError, PushError>, RecvError>> + Send + '_
pub fn recv( &self, ) -> impl Future<Output = Result<Event<PullError, PushError>, RecvError>> + Send + '_
Await the next event, or Err once the session has ended.
Equivalent to self.event_chain().recv(), but returns
impl Future + Send, so an enclosing async block that awaits it stays
Send. Prefer this over event_chain().recv() in a tokio::spawned
driver: the underlying RecvFuture is only Send through a hand-written
impl that the async fn auto-trait leak check does not see through, so
awaiting it inline reintroduces a spurious higher-ranked lifetime error.
No allocation.
Sourcepub fn abort(&self)
pub fn abort(&self)
Cancel all workers immediately.
Safe to call multiple times and safe to call while other clones of the
owning DownloadResult are still alive. The implicit drop-based
cancellation (on the last clone) becomes a no-op once this has run.
Sourcepub fn set_threads(&self, threads: usize)
pub fn set_threads(&self, threads: usize)
Adjust the worker thread count of a running multi-threaded session.
The minimum chunk size used while growing is the session’s live value,
set independently with set_min_chunk_size
(or the configured value until then).
Growing spawns workers for ranges still waiting in the queue, or splits a range off the busiest running worker when nothing is waiting. Shrinking aborts the surplus workers and returns their ranges to the queue for the survivors to steal. No-op for single-threaded sessions, which have no task queue.
A session ends when its last worker exits, and it cannot be restarted:
growing afterwards spawns nothing, because the workers’ shared channels
are closed at that point. Shrinking is clamped to a minimum of one worker
by the scheduler, so set_threads(0) keeps a single worker alive rather
than ending the session. The session terminates only when that last
(clamped) worker exits on its own.
This never touches the abort token: abort is terminal and
cannot be undone by resizing, so is_aborted stays
true across any later set_threads call, and any worker spawned by such
a call observes the cancelled token and exits without pulling.
Sourcepub fn set_min_chunk_size(&self, min_chunk_size: u64)
pub fn set_min_chunk_size(&self, min_chunk_size: u64)
Set the minimum chunk size used when a worker next steals work.
Bounds how finely a running worker may split a range to take a share of a
peer’s work: a range is only halved when at least min_chunk_size * 2
bytes remain. The new value takes effect on the next steal — there is no
need to also call set_threads — and it is also the
granularity used to split ranges the next time the pool grows.
A no-op for single-threaded sessions, which have no worker pool.
Sourcepub fn is_aborted(&self) -> bool
pub fn is_aborted(&self) -> bool
Whether the session has been (or is being) cancelled.