Expose wrapping and unwrapping of SocketRefs.

src/socket/mod.rs

@@ -108,12 +108,10 @@ macro_rules! from_socket {
         impl<'a, 'b> AnySocket<'a, 'b> for $socket {
             fn downcast<'c>(ref_: SocketRef<'c, Socket<'a, 'b>>) ->
                            Option<SocketRef<'c, Self>> {
-                SocketRef::map(ref_, |socket| {
-                    match *socket {
-                        Socket::$variant(ref mut socket) => Some(socket),
-                        _ => None,
-                    }
-                })
+                match SocketRef::unwrap(ref_) {
+                    &mut Socket::$variant(ref mut socket) => Some(SocketRef::wrap(socket)),
+                    _ => None,
+                }
             }
         }
     }

src/socket/ref_.rs

@@ -32,21 +32,29 @@ pub struct Ref<'a, T: Session + 'a> {
     consumed: bool,
 }
 
-impl<'a, T: Session> Ref<'a, T> {
-    pub(crate) fn new(socket: &'a mut T) -> Self {
+impl<'a, T: Session + 'a> Ref<'a, T> {
+    /// Wrap a pointer to a socket to make a smart pointer.
+    ///
+    /// Calling this function is only necessary if your code is using [unwrap].
+    ///
+    /// [unwrap]: #method.unwrap
+    pub fn wrap(socket: &'a mut T) -> Self {
         Ref { socket, consumed: false }
     }
-}
 
-impl<'a, T: Session + 'a> Ref<'a, T> {
-    pub(crate) fn map<U, F>(mut ref_: Self, f: F) -> Option<Ref<'a, U>>
-            where U: Session + 'a, F: FnOnce(&'a mut T) -> Option<&'a mut U> {
-        if let Some(socket) = f(ref_.socket) {
-            ref_.consumed = true;
-            Some(Ref::new(socket))
-        } else {
-            None
-        }
+    /// Unwrap a smart pointer to a socket.
+    ///
+    /// The finalization code is not run. Prompt operation of the network stack depends
+    /// on wrapping the returned pointer back and dropping it.
+    ///
+    /// Calling this function is only necessary to achieve composability if you *must*
+    /// map a `&mut SocketRef<'a, XSocket>` to a `&'a mut XSocket` (note the lifetimes);
+    /// be sure to call [wrap] afterwards.
+    ///
+    /// [wrap]: #method.wrap
+    pub fn unwrap(mut ref_: Self) -> &'a mut T {
+        ref_.consumed = true;
+        ref_.socket
     }
 }
 

src/socket/set.rs

@@ -87,7 +87,7 @@ impl<'a, 'b: 'a, 'c: 'a + 'b> Set<'a, 'b, 'c> {
     pub fn get<T: AnySocket<'b, 'c>>(&mut self, handle: Handle) -> SocketRef<T> {
         match self.sockets[handle.0].as_mut() {
             Some(item) => {
-                T::downcast(SocketRef::new(&mut item.socket))
+                T::downcast(SocketRef::wrap(&mut item.socket))
                   .expect("handle refers to a socket of a wrong type")
             }
             None => panic!("handle does not refer to a valid socket")
@@ -209,7 +209,7 @@ impl<'a, 'b: 'a, 'c: 'a + 'b> Iterator for IterMut<'a, 'b, 'c> {
     fn next(&mut self) -> Option<Self::Item> {
         while let Some(item_opt) = self.lower.next() {
             if let Some(item) = item_opt.as_mut() {
-                return Some(SocketRef::new(&mut item.socket))
+                return Some(SocketRef::wrap(&mut item.socket))
             }
         }
         None