diff --git a/examples/connect.rs b/examples/connect.rs index 275864d12..26614b964 100644 --- a/examples/connect.rs +++ b/examples/connect.rs @@ -170,7 +170,7 @@ mod udp { use futures::{Future, Stream}; use futures::future::Executor; use futures_cpupool::CpuPool; - use tokio::net::UdpSocket; + use tokio::net::{UdpSocket, UdpFramed}; use codec::Bytes; pub fn connect(&addr: &SocketAddr, @@ -192,7 +192,7 @@ mod udp { // this UDP socket into a framed sink/stream which operates over // discrete values. In this case we're working with *pairs* of socket // addresses and byte buffers. - let (sink, stream) = udp.framed(Bytes).split(); + let (sink, stream) = UdpFramed::new(udp, Bytes).split(); // All bytes from `stdin` will go to the `addr` specified in our // argument list. Like with TCP this is spawned concurrently diff --git a/examples/udp-codec.rs b/examples/udp-codec.rs index a2429e491..be686d633 100644 --- a/examples/udp-codec.rs +++ b/examples/udp-codec.rs @@ -17,7 +17,7 @@ use std::net::SocketAddr; use futures::{Future, Stream, Sink}; use futures::future::Executor; use futures_cpupool::CpuPool; -use tokio::net::UdpSocket; +use tokio::net::{UdpSocket, UdpFramed}; use tokio_io::codec::BytesCodec; fn main() { @@ -34,8 +34,8 @@ fn main() { // We're parsing each socket with the `LineCodec` defined above, and then we // `split` each codec into the sink/stream halves. - let (a_sink, a_stream) = a.framed(BytesCodec::new()).split(); - let (b_sink, b_stream) = b.framed(BytesCodec::new()).split(); + let (a_sink, a_stream) = UdpFramed::new(a, BytesCodec::new()).split(); + let (b_sink, b_stream) = UdpFramed::new(b, BytesCodec::new()).split(); // Start off by sending a ping from a to b, afterwards we just print out // what they send us and continually send pings diff --git a/src/net/mod.rs b/src/net/mod.rs index d4a55eb22..077e886a8 100644 --- a/src/net/mod.rs +++ b/src/net/mod.rs @@ -28,8 +28,7 @@ //! [`RecvDgram`] and [`SendDgram`] structs respectively. //! //! For convience it's also possible to convert raw datagrams into higher-level -//! frames. This done with [`UdpFramed`], created by calling [`framed`] on a -//! [`UdpSocket`]. +//! frames. //! //! [`UdpSocket`]: struct.UdpSocket.html //! [`RecvDgram`]: struct.RecvDgram.html diff --git a/src/net/udp/frame.rs b/src/net/udp/frame.rs index f84d0842b..77480a24c 100644 --- a/src/net/udp/frame.rs +++ b/src/net/udp/frame.rs @@ -11,8 +11,19 @@ use bytes::{BytesMut, BufMut}; /// A unified `Stream` and `Sink` interface to an underlying `UdpSocket`, using /// the `Encoder` and `Decoder` traits to encode and decode frames. /// -/// You can acquire a `UdpFramed` instance by using the `UdpSocket::framed` -/// adapter. +/// Raw UDP sockets work with datagrams, but higher-level code usually wants to +/// batch these into meaningful chunks, called "frames". This method layers +/// framing on top of this socket by using the `Encoder` and `Decoder` traits to +/// handle encoding and decoding of messages frames. Note that the incoming and +/// outgoing frame types may be distinct. +/// +/// This function returns a *single* object that is both `Stream` and `Sink`; +/// grouping this into a single object is often useful for layering things which +/// require both read and write access to the underlying object. +/// +/// If you want to work more directly with the streams and sink, consider +/// calling `split` on the `UdpFramed` returned by this method, which will break +/// them into separate objects, allowing them to interact more easily. #[must_use = "sinks do nothing unless polled"] #[derive(Debug)] pub struct UdpFramed { @@ -100,18 +111,21 @@ impl Sink for UdpFramed { const INITIAL_RD_CAPACITY: usize = 64 * 1024; const INITIAL_WR_CAPACITY: usize = 8 * 1024; -pub fn new(socket: UdpSocket, codec: C) -> UdpFramed { - UdpFramed { - socket: socket, - codec: codec, - out_addr: SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(0, 0, 0, 0), 0)), - rd: BytesMut::with_capacity(INITIAL_RD_CAPACITY), - wr: BytesMut::with_capacity(INITIAL_WR_CAPACITY), - flushed: true, - } -} - impl UdpFramed { + /// Create a new `UdpFramed` backed by the given socket and codec. + /// + /// See struct level documention for more details. + pub fn new(socket: UdpSocket, codec: C) -> UdpFramed { + UdpFramed { + socket: socket, + codec: codec, + out_addr: SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(0, 0, 0, 0), 0)), + rd: BytesMut::with_capacity(INITIAL_RD_CAPACITY), + wr: BytesMut::with_capacity(INITIAL_WR_CAPACITY), + flushed: true, + } + } + /// Returns a reference to the underlying I/O stream wrapped by `Framed`. /// /// # Note diff --git a/src/net/udp/mod.rs b/src/net/udp/mod.rs index 1d022abfe..4d1deb4b9 100644 --- a/src/net/udp/mod.rs +++ b/src/net/udp/mod.rs @@ -14,7 +14,6 @@ pub struct UdpSocket { mod frame; pub use self::frame::UdpFramed; -use tokio_io::codec::{Decoder, Encoder}; impl UdpSocket { /// This function will create a new UDP socket and attempt to bind it to @@ -44,29 +43,6 @@ impl UdpSocket { UdpSocket::new(udp, handle) } - /// Provides a `Stream` and `Sink` interface for reading and writing to this - /// `UdpSocket` object, using the provided codec that must implement - /// `Encoder` and `Decoder` traits to read and write the raw data. - /// - /// Raw UDP sockets work with datagrams, but higher-level code usually - /// wants to batch these into meaningful chunks, called "frames". This - /// method layers framing on top of this socket by using the `Encoder` - /// and `Decoder` traits to handle encoding and decoding of messages - /// frames. Note that the incoming and outgoing frame types may be distinct. - /// - /// This function returns a *single* object that is both `Stream` and - /// `Sink`; grouping this into a single object is often useful for layering - /// things which require both read and write access to the underlying - /// object. - /// - /// If you want to work more directly with the streams and sink, consider - /// calling `split` on the `UdpFramed` returned by this method, which will - /// break them into separate objects, allowing them to interact more - /// easily. - pub fn framed(self, codec: C) -> UdpFramed { - frame::new(self, codec) - } - /// Returns the local address that this socket is bound to. pub fn local_addr(&self) -> io::Result { self.io.get_ref().local_addr() diff --git a/tests/udp.rs b/tests/udp.rs index 37c986986..162af7009 100644 --- a/tests/udp.rs +++ b/tests/udp.rs @@ -10,7 +10,7 @@ use std::net::SocketAddr; use futures::{Future, Poll, Stream, Sink}; -use tokio::net::UdpSocket; +use tokio::net::{UdpSocket, UdpFramed}; use tokio_io::codec::{Encoder, Decoder}; use bytes::{BytesMut, BufMut}; @@ -225,8 +225,8 @@ fn send_framed() { let b_addr = t!(b_soc.local_addr()); { - let a = a_soc.framed(ByteCodec); - let b = b_soc.framed(ByteCodec); + let a = UdpFramed::new(a_soc, ByteCodec); + let b = UdpFramed::new(b_soc, ByteCodec); let msg = b"4567".to_vec(); @@ -243,8 +243,8 @@ fn send_framed() { } { - let a = a_soc.framed(ByteCodec); - let b = b_soc.framed(ByteCodec); + let a = UdpFramed::new(a_soc, ByteCodec); + let b = UdpFramed::new(b_soc, ByteCodec); let msg = b"".to_vec();