datagram_socket/
shutdown.rs

1// Copyright (C) 2025, Cloudflare, Inc.
2// All rights reserved.
3//
4// Redistribution and use in source and binary forms, with or without
5// modification, are permitted provided that the following conditions are
6// met:
7//
8//     * Redistributions of source code must retain the above copyright notice,
9//       this list of conditions and the following disclaimer.
10//
11//     * Redistributions in binary form must reproduce the above copyright
12//       notice, this list of conditions and the following disclaimer in the
13//       documentation and/or other materials provided with the distribution.
14//
15// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
16// IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
17// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
19// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26
27use std::future::poll_fn;
28use std::future::Future;
29use std::io;
30use std::sync::Arc;
31use std::task::Context;
32use std::task::Poll;
33
34use tokio::net::UdpSocket;
35
36#[cfg(unix)]
37use tokio::net::UnixDatagram;
38
39pub trait ShutdownConnection {
40    /// Initiates or attempts to shut down this writer, returning success when
41    /// the I/O connection has completely shut down.
42    ///
43    /// # Return value
44    ///
45    /// This function returns a `Poll<io::Result<()>>` classified as such:
46    ///
47    /// * `Poll::Ready(Ok(()))` - indicates that the connection was successfully
48    ///   shut down and is now safe to deallocate/drop/close resources
49    ///   associated with it. This method means that the current task will no
50    ///   longer receive any notifications due to this method and the I/O object
51    ///   itself is likely no longer usable.
52    ///
53    /// * `Poll::Pending` - indicates that shutdown is initiated but could not
54    ///   complete just yet. This may mean that more I/O needs to happen to
55    ///   continue this shutdown operation. The current task is scheduled to
56    ///   receive a notification when it's otherwise ready to continue the
57    ///   shutdown operation. When woken up this method should be called again.
58    ///
59    /// * `Poll::Ready(Err(e))` - indicates a fatal error has happened with
60    ///   shutdown, indicating that the shutdown operation did not complete
61    ///   successfully. This typically means that the I/O object is no longer
62    ///   usable.
63    ///
64    /// # Errors
65    ///
66    /// This function can return normal I/O errors through `Err`, described
67    /// above. Additionally this method may also render the underlying
68    /// `Write::write` method no longer usable (e.g. will return errors in the
69    /// future). It's recommended that once `shutdown` is called the
70    /// `write` method is no longer called.
71    fn poll_shutdown(&mut self, cx: &mut Context) -> Poll<io::Result<()>>;
72}
73
74impl ShutdownConnection for UdpSocket {
75    #[inline]
76    fn poll_shutdown(&mut self, _cx: &mut Context) -> Poll<io::Result<()>> {
77        Poll::Ready(Ok(()))
78    }
79}
80
81#[cfg(unix)]
82impl ShutdownConnection for UnixDatagram {
83    #[inline]
84    fn poll_shutdown(&mut self, _cx: &mut Context) -> Poll<io::Result<()>> {
85        Poll::Ready(Ok(()))
86    }
87}
88
89impl<T: ShutdownConnection + Send + Sync> ShutdownConnection for Arc<T> {
90    #[inline]
91    fn poll_shutdown(&mut self, _cx: &mut Context) -> Poll<io::Result<()>> {
92        Poll::Ready(Ok(()))
93    }
94}
95
96/// Shuts down a datagram oriented connection.
97///
98/// Implemented as an extension trait, adding utility methods to all
99/// [`ShutdownConnection`] types. Callers will tend to import this trait instead
100/// of [`ShutdownConnection`].
101///
102/// [`ShutdownConnection`]: ShutdownConnection
103pub trait ShutdownConnectionExt: ShutdownConnection {
104    #[inline]
105    fn shutdown_connection(&mut self) -> impl Future<Output = io::Result<()>> {
106        poll_fn(move |cx| self.poll_shutdown(cx))
107    }
108}
109
110impl<T: ShutdownConnection + ?Sized> ShutdownConnectionExt for T {}
datagram_socket/shutdown.rs

datagram_socket/
shutdown.rs
