future
import std::net::tls::future; · source
The TLS counterparts of TcpConnect, TcpRead, and TcpWrite, with the same ownership handshake: the stream (and, for a read or write, the buffer) goes in through start and comes back out through take_stream / take_buf on the TlsIo outcome. TlsHandshake completes with the stream itself once the handshake is done, or the error that ended it.
They differ from their TCP counterparts in one respect. OpenSSL may need to write to make progress on a read (a renegotiation, a close_notify) or vice versa, so each remembers which direction it last armed with the reactor and re-registers for whichever SSL_get_error asks for — SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE — rather than assuming a read always waits on readability.
Dropping any of these mid-operation releases its registration.
Types
TlsHandshake
type struct TlsHandshake {
tls: TlsStream;
is_client: boolean;
verify: boolean;
rt: Reactor*;
armed: u32;
static start(tls: TlsStream, is_client: boolean, verify: boolean) -> TlsHandshake;
}Drives SSL_connect or SSL_accept to completion, re-arming for whichever direction OpenSSL asks for, and completes with the stream. Dropping it closes the half-established connection.
Properties
| Property | Type |
|---|---|
tls | TlsStream |
is_client | boolean |
verify | boolean |
rt | Reactor* |
armed | u32 |
Constructors
static start(tls: TlsStream, is_client: boolean, verify: boolean) -> TlsHandshake;
static start(tls: TlsStream, is_client: boolean, verify: boolean) -> TlsHandshake;Begin a handshake on tls, which this future owns until it completes.
TlsRead
type struct TlsRead {
tls: TlsStream;
buf: Array<u8>;
rt: Reactor*;
armed: u32;
static start(tls: TlsStream, buf: Array<u8>) -> TlsRead;
}One SSL_read into buf. A TlsRead that completes with 0 bytes saw close_notify, the TLS equivalent of EOF.
Properties
| Property | Type |
|---|---|
tls | TlsStream |
buf | Array<u8> |
rt | Reactor* |
armed | u32 |
Constructors
static start(tls: TlsStream, buf: Array<u8>) -> TlsRead;
static start(tls: TlsStream, buf: Array<u8>) -> TlsRead;Begin a read on tls, filling buf — both owned by this future until it completes.
TlsWrite
type struct TlsWrite {
tls: TlsStream;
buf: Array<u8>;
rt: Reactor*;
armed: u32;
static start(tls: TlsStream, buf: Array<u8>) -> TlsWrite;
}One SSL_write from buf, completing with the bytes accepted.
Properties
| Property | Type |
|---|---|
tls | TlsStream |
buf | Array<u8> |
rt | Reactor* |
armed | u32 |
Constructors
static start(tls: TlsStream, buf: Array<u8>) -> TlsWrite;
static start(tls: TlsStream, buf: Array<u8>) -> TlsWrite;Begin a write of every byte in buf on tls — both owned by this future until it completes.
TlsIo
type struct TlsIo {
tls: TlsStream;
buf: Array<u8>;
result: Result<u64, IoError>;
take_stream(mut &this) -> TlsStream;
take_buf(mut &this) -> Array<u8>;
outcome(&this) -> Result<u64, IoError>;
}The outcome of a read or write: the stream and buffer back through take_stream / take_buf, and outcome() for the count or the error.
Properties
| Property | Type |
|---|---|
tls | TlsStream |
buf | Array<u8> |
result | Result<u64, IoError> |
Methods
take_stream(mut &this) -> TlsStream;
take_stream(mut &this) -> TlsStream;Take the stream back. Calling it twice yields a closed placeholder the second time — the outcome holds the stream exactly once.
take_buf(mut &this) -> Array<u8>;
take_buf(mut &this) -> Array<u8>;Take the buffer back. After a read it holds exactly the bytes that arrived; after a write it is untouched, so a caller with a short write still has the bytes it has not sent yet.
outcome(&this) -> Result<u64, IoError>;
outcome(&this) -> Result<u64, IoError>;How many bytes moved, or why none did.
Trait implementations
TlsHandshake
implement trait Future for struct TlsHandshake
implement trait Drop for struct TlsHandshake
TlsRead
implement trait Future for struct TlsRead
implement trait Drop for struct TlsRead
TlsWrite
implement trait Future for struct TlsWrite
implement trait Drop for struct TlsWrite
type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.
type struct Name {
field: Type;
method(&this) -> Ret { ... }
}A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.
type struct TlsHandshake {
tls: TlsStream;
is_client: boolean;
verify: boolean;
rt: Reactor*;
armed: u32;
}Drive a TLS handshake to completion without blocking. SSL_connect (client) or SSL_accept (server) is re-issued on every poll — which is exactly what OpenSSL wants after a WANT_* — until it reports success or a real failure.
TlsHandshake.tls: TlsStreamtype struct TlsStream {
ssl: void*;
inner: TcpStream;
}TlsHandshake.is_client: booleanTlsHandshake.verify: booleanTlsHandshake.rt: Reactor*type struct Reactor {
mtx: [u8;
40];
buckets: [Registration*;
64];
poll_h: i64;
kick_h: i64;
aux_h: i64;
shutdown: Atomic<u8>;
thread: u64;
timers: Timer*;
// … 1 more
}The I/O readiness driver for one Executor. Heap-allocated: worker threads and parked futures hold raw pointers to it, and the backend hands the OS interior addresses, so it must not move.
TlsHandshake.armed: u32static name(param: Type) -> Ret { ... }A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.
static TlsHandshake::start(tls: TlsStream, is_client: boolean, verify: boolean) -> TlsHandshakeBegin a handshake on tls, which this future owns until it completes.
(parameter) tls: TlsStream(parameter) is_client: boolean(parameter) verify: booleantype struct TlsHandshake {
tls: TlsStream;
is_client: boolean;
verify: boolean;
rt: Reactor*;
armed: u32;
}Drive a TLS handshake to completion without blocking. SSL_connect (client) or SSL_accept (server) is re-issued on every poll — which is exactly what OpenSSL wants after a WANT_* — until it reports success or a real failure.
type struct TlsRead {
tls: TlsStream;
buf: Array<u8>;
rt: Reactor*;
armed: u32;
}Read decrypted bytes as soon as the connection has some. Completes with the byte count — 0 means the peer sent close_notify, the TLS equivalent of EOF — or the error that ended it.
TlsRead.tls: TlsStreamTlsRead.buf: Array<u8>type struct Array<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
length: i64;
capacity: i64;
alloc: A;
}Array<T, A>: growable, heap-backed, contiguous sequence.
std::collections::arrayTlsRead.rt: Reactor*TlsRead.armed: u32static TlsRead::start(tls: TlsStream, buf: Array<u8>) -> TlsReadBegin a read on tls, filling buf — both owned by this future until it completes.
(parameter) buf: Array<u8>type struct TlsRead {
tls: TlsStream;
buf: Array<u8>;
rt: Reactor*;
armed: u32;
}Read decrypted bytes as soon as the connection has some. Completes with the byte count — 0 means the peer sent close_notify, the TLS equivalent of EOF — or the error that ended it.
type struct TlsWrite {
tls: TlsStream;
buf: Array<u8>;
rt: Reactor*;
armed: u32;
}Write plaintext as soon as the connection has room for the resulting record. Completes with the number of bytes accepted, which may be fewer than asked for — a caller with more to send starts another write for the remainder, which is why the buffer comes back untouched.
TlsWrite.tls: TlsStreamTlsWrite.buf: Array<u8>TlsWrite.rt: Reactor*TlsWrite.armed: u32static TlsWrite::start(tls: TlsStream, buf: Array<u8>) -> TlsWriteBegin a write of every byte in buf on tls — both owned by this future until it completes.
type struct TlsWrite {
tls: TlsStream;
buf: Array<u8>;
rt: Reactor*;
armed: u32;
}Write plaintext as soon as the connection has room for the resulting record. Completes with the number of bytes accepted, which may be fewer than asked for — a caller with more to send starts another write for the remainder, which is why the buffer comes back untouched.
std::net::tls::futuretype struct TlsIo {
tls: TlsStream;
buf: Array<u8>;
result: Result<u64, IoError>;
}The outcome of an async TLS read or write: the stream and the buffer handed back, plus how many bytes moved (or why none did).
TlsIo.tls: TlsStreamTlsIo.buf: Array<u8>TlsIo.result: Result<u64, IoError>type struct IoError {
kind: IoErrorKind;
os_code: i32;
}TlsIo::take_stream(mut &this) -> TlsStreamTake the stream back. Calling it twice yields a closed placeholder the second time — the outcome holds the stream exactly once.
mut &this
mut &TypeAn exclusive, mutating borrow. As a receiver, mut &this lets the method modify the fields - and callers can see that from the signature alone. As a parameter type, mut &T lets the callee mutate through the reference while the caller keeps ownership.
&this
mut &this
thisThe receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.
TlsIo::take_buf(mut &this) -> Array<u8>Take the buffer back. After a read it holds exactly the bytes that arrived; after a write it is untouched, so a caller with a short write still has the bytes it has not sent yet.
TlsIo::outcome(&this) -> Result<u64, IoError>How many bytes moved, or why none did.
import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).
namespace std::net::tls::future;Async TLS: the futures that drive OpenSSL on a NON-BLOCKING socket.
module pagestatic TlsHandshake::start(tls: TlsStream, is_client: boolean, verify: boolean) -> TlsHandshakeBegin a handshake on tls, which this future owns until it completes.
TlsIo::take_stream(mut &this) -> TlsStreamTake the stream back. Calling it twice yields a closed placeholder the second time — the outcome holds the stream exactly once.
std::net::tls::futureTlsIo::take_buf(mut &this) -> Array<u8>Take the buffer back. After a read it holds exactly the bytes that arrived; after a write it is untouched, so a caller with a short write still has the bytes it has not sent yet.
std::net::tls::futuretype struct TlsIo {
tls: TlsStream;
buf: Array<u8>;
result: Result<u64, IoError>;
}The outcome of an async TLS read or write: the stream and the buffer handed back, plus how many bytes moved (or why none did).
std::net::tls::futureTlsIo.tls: TlsStreamTlsHandshake.is_client: booleanTlsHandshake.verify: booleanTlsHandshake.rt: Reactor*TlsHandshake.armed: u32TlsIo.buf: Array<u8>TlsIo::outcome(&this) -> Result<u64, IoError>How many bytes moved, or why none did.
std::net::tls::futureTlsIo.result: Result<u64, IoError>implement struct Name { ... }
implement trait Trait for Type { ... }
implement u64 { ... }Adds methods to a type outside its declaration. implement struct T (or enum, or a bare primitive) opens an inherent block; implement trait Tr for T supplies a trait's methods for one type. Resolution is at compile time - no dynamic dispatch.
implement trait Trait for Type { ... }Introduces a trait implementation: the block supplies, for one concrete type, the method bodies the trait requires.
language referencetype trait Future {
type Output;
poll(mut &this, cx: Context*) -> Poll<This::Output>;
}An asynchronous computation. poll drives it one step: Ready(v) when the value is available, Pending when it is not yet (the future has arranged, via cx's waker, to be polled again later).
implement trait Trait for Type { ... }Names the type a trait implementation is for. The block that follows supplies the bodies the trait requires.
language reference