docs: io callback examples - #6036
Conversation
| @@ -0,0 +1,264 @@ | |||
| //! This example shows how to setup the unsafe send + recv callbacks for s2n-tls. | |||
There was a problem hiding this comment.
I think these new files just need the copyright/licence headers. Otherwise looks good to me
| /// use s2n_tls::connection::Connection; | ||
| /// use io_callbacks::generic_posix_send_cb; | ||
| /// | ||
| /// let (client_stream, server_stream) = UnixStream::pair().unwrap(); |
There was a problem hiding this comment.
You don't need this doc example if you have a test example further on. Just seems weird since the send callback has a doc example but the recv callback does not.
| //! s2n-tls holds a raw pointer to the IO context for the life of the connection, | ||
| //! so the transport must have a stable address and must outlive the connection's | ||
| //! use of it. `TlsStream` enforces both by pinning the transport on the heap and | ||
| //! owning it alongside the connection. |
There was a problem hiding this comment.
I don't understand the purpose of this example. You've already shown how a UnixStream can be used to send/read from a connection in your lib.rs test. What are you showing in this test file that is different?
There was a problem hiding this comment.
A common problem that people run into is "how do I managed transport layer lifetimes". This TlsStream abstraction is how I'd recommend they deal with the disconnected lifetimes.
There was a problem hiding this comment.
Also it implements std::io::Read and std::io::Write, which I expect people will generally be more comfortable using instead of poll_send and poll_recv.
There was a problem hiding this comment.
Oh the tls_stream is what you actually recommend people use, and the lib.rs functions are just the barebones impl.
3 participants
Goal
Why
This is all very tedious stuff. I have found these patterns to be really useful in my own work, so it makes sense to document them.
How
Examples!
Callouts
This code is deliberately verbose. In my opinion DRY is a very poor fit for examples.
Testing
The examples are really more reference code. So there are tests that confirm things are working.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.