1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
//! Full-duplex Reader/Writer pair for a Connection whose transport is
//! [`Splittable`](crate::Splittable).
//!
//! `Reader` owns the read half and drives packet reception. `Writer` is
//! a cheap handle to the shared write half and channel table, and can
//! be cloned for use from other threads and tasks. A thread blocked in
//! [`Reader::read_channel`] does not prevent another thread from
//! calling [`Writer::write_channel`] or [`Writer::close_channel`].
//!
//! Available under the `split` feature (implied by every runtime
//! feature: `tokio`, `smol`, `nusb`, `rusb`). Pulls `std` into the
//! build for its sync primitives; a pure `no_std` variant would need a
//! no_std Mutex implementation and is not yet provided.
//!
//! # Driving the connection
//!
//! There are two ways to use the pair:
//!
//! * **Reader-driven.** One task keeps the `Reader` and calls
//! [`Reader::open_channel`] and [`Reader::read_channel`] itself;
//! writers send from anywhere. Packets for other channels are
//! buffered while it waits, but only that task can collect them. A
//! writer parked for credit moves only once something reads, so with
//! no read under way the task takes packets one at a time with
//! [`Reader::dispatch_one`]; [`Writer::waits_for_credit`] says when.
//! * **Dispatched.** [`Reader::run`] takes the `Reader` and does
//! nothing but receive and dispatch packets, waking whoever waits on
//! the channel each one is for. Every channel operation then goes
//! through the `Writer` — [`Writer::open_channel`],
//! [`Writer::read_channel`], [`Writer::write_channel`],
//! [`Writer::close_channel`] — so any number of tasks can work on
//! their own channels at once and none waits on another's traffic.
//! Channels the device opens (`adb reverse`) are taken through an
//! [`IncomingListener`] from [`Writer::listen_incoming`].
//!
//! # When the connection ends
//!
//! The connection has ended once `run` returned, the `Reader` was
//! dropped, or a receive failed for good on a reader-driven connection.
//! Every `Writer` call that waits on the device then fails with
//! [`Error::Disconnected`] instead of waiting for packets nobody reads:
//! opening a channel, reading one, waiting for send credit, accepting
//! one the device opened. Calls that need no answer, a write the credit
//! already covers or a close, still reach the transport, except that a
//! close on a stream that has ended frees its slot without a CLSE.
//!
//! A read timeout is no such failure: it is the caller's to handle, and
//! leaves the connection and everyone waiting on it as they were.
//!
//! # What arrived stays readable
//!
//! However the connection fails, a read first hands over what its
//! channel has buffered, and only then fails with
//! [`Error::Disconnected`] or [`Error::Desynchronized`]. Every other
//! call on a desynchronized connection fails at once.
//!
//! A read does not depend on its OKAY. One that fails does not fail the
//! read: the next call reports the failure. Once the connection has
//! ended, or a write was abandoned mid-packet, a read sends no OKAY and
//! does not wait for the write half, and a read already waiting to send
//! one stops. The bytes then come without their OKAY, so a stalled
//! writer or transport cannot keep them back.
//!
//! # What the device is owed
//!
//! The OKAY for data that arrived and the CLSE for a channel closed
//! here are recorded before any wait. The next write, open, close or
//! receive sends them before anything else, so a call dropped while it
//! waits for the write half loses neither. Once the connection has
//! ended a receive no longer sends them. While anything is owed nothing
//! is received, on any channel: a close behind a stalled writer holds
//! up reception until the write half comes free.
//!
//! No CLSE is sent to a device that is gone. Once a write found it gone
//! or a receive found the stream over, [`Writer::close_channel`]
//! returns `Ok` without one, and a close already waiting gives up if a
//! read still under way finds the stream over. A dropped `Reader` is
//! different: the device can still hear the CLSE, and a close waits for
//! the write half as usual.
//!
//! # Dropping a call
//!
//! Each call says whether it is safe to drop. Waiting for the write
//! half always is. Two other waits are not:
//!
//! * **Writing a packet.** From the moment a packet's write is first
//! polled, a drop abandons the packet and desynchronizes the
//! connection: see [`Error::Desynchronized`]. Every call on the
//! `Reader` and on any `Writer` then fails with that error, calls
//! already waiting included, and reads once they have handed over
//! what had already arrived. Close the connection and open a new one.
//! * **Reading a packet.** A call on the `Reader` waits for a packet in
//! a transport read. Where reads are not cancel-safe (USB), dropping
//! it can lose packet bytes: see
//! [`ReadCancelSafety`](crate::transport::ReadCancelSafety).
//!
//! # Closing while a read waits
//!
//! Only the `Reader` drives packet reception, so
//! [`Writer::close_channel`] does not by itself wake a concurrent
//! [`Reader::read_channel`] parked on the same channel: the reader
//! unblocks only once it receives the device's echoed `CLSE` packet.
//! If the device is slow or non-conformant and never echoes the close,
//! an in-flight `read_channel` can remain blocked until the transport
//! itself fails. Drop the `Reader` (or fail the transport) to unblock
//! such a reader unconditionally.
pub use ;
pub use Reader;
pub use Shared;
pub use Writer;
use crateError;