socket::shutdown with tests and documentation

Author: vinniefalco

include/boost/corosio/io_stream.hpp

@@ -43,10 +43,12 @@ class BOOST_COROSIO_DECL io_stream : public io_object
         @return An awaitable that completes with a pair of
             `{error_code, bytes_transferred}`. Returns success with the
             number of bytes read, or an error code on failure including:
-            - capy::error::eof: End of stream reached.
-                Check `ec == cond::eof` for portable comparison.
-            - operation_canceled: Cancelled via stop_token or cancel().
-                Check `ec == cond::canceled` for portable comparison.
+            - cond::eof: The peer closed their send direction by calling
+                shutdown or close, sending a TCP FIN. Use the portable
+                condition test: `if (ec == capy::cond::eof)`
+            - cond::canceled: Cancelled via stop_token or cancel().
+                Use the portable condition test:
+                `if (ec == capy::cond::canceled)`
 
         @par Preconditions
         The socket must be open and connected.

include/boost/corosio/socket.hpp

@@ -74,6 +74,14 @@ namespace corosio {
 class BOOST_COROSIO_DECL socket : public io_stream
 {
 public:
+    /** Different ways a socket may be shutdown. */
+    enum shutdown_type
+    {
+        shutdown_receive,
+        shutdown_send,
+        shutdown_both
+    };
+
     struct socket_impl : io_stream_impl
     {
         virtual void connect(
@@ -82,6 +90,8 @@ class BOOST_COROSIO_DECL socket : public io_stream
             endpoint,
             std::stop_token,
             system::error_code*) = 0;
+
+        virtual system::error_code shutdown(shutdown_type) noexcept = 0;
     };
 
     struct connect_awaitable
@@ -271,6 +281,47 @@ class BOOST_COROSIO_DECL socket : public io_stream
     */
     void cancel();
 
+    /** Disable sends or receives on the socket.
+
+        TCP connections are full-duplex: each direction (send and receive)
+        operates independently. This function allows you to close one or
+        both directions without destroying the socket.
+
+        @li @ref shutdown_send sends a TCP FIN packet to the peer,
+            signaling that you have no more data to send. You can still
+            receive data until the peer also closes their send direction.
+            This is the most common use case, typically called before
+            close() to ensure graceful connection termination.
+
+        @li @ref shutdown_receive disables reading on the socket. This
+            does NOT send anything to the peer - they are not informed
+            and may continue sending data. Subsequent reads will fail
+            or return end-of-file. Incoming data may be discarded or
+            buffered depending on the operating system.
+
+        @li @ref shutdown_both combines both effects: sends a FIN and
+            disables reading.
+
+        When the peer shuts down their send direction (sends a FIN),
+        subsequent read operations will complete with `capy::cond::eof`.
+        Use the portable condition test rather than comparing error
+        codes directly:
+
+        @code
+        auto [ec, n] = co_await sock.read_some(buffer);
+        if (ec == capy::cond::eof)
+        {
+            // Peer closed their send direction
+        }
+        @endcode
+
+        Any error from the underlying system call is silently discarded
+        because it is unlikely to be helpful.
+
+        @param what Determines what operations will no longer be allowed.
+    */
+    void shutdown(shutdown_type what);
+
 private:
     friend class acceptor;
 

src/corosio/src/detail/epoll/sockets.hpp

@@ -137,6 +137,22 @@ class epoll_socket_impl
         system::error_code*,
         std::size_t*) override;
 
+    system::error_code shutdown(socket::shutdown_type what) noexcept override
+    {
+        int how;
+        switch (what)
+        {
+        case socket::shutdown_receive: how = SHUT_RD;   break;
+        case socket::shutdown_send:    how = SHUT_WR;   break;
+        case socket::shutdown_both:    how = SHUT_RDWR; break;
+        default:
+            return make_err(EINVAL);
+        }
+        if (::shutdown(fd_, how) != 0)
+            return make_err(errno);
+        return {};
+    }
+
     int native_handle() const noexcept { return fd_; }
     bool is_open() const noexcept { return fd_ >= 0; }
     void cancel() noexcept;

src/corosio/src/detail/iocp/sockets.hpp

@@ -225,6 +225,22 @@ class win_socket_impl
         internal_->write_some(h, d, buf, token, ec, bytes);
     }
 
+    system::error_code shutdown(socket::shutdown_type what) noexcept override
+    {
+        int how;
+        switch (what)
+        {
+        case socket::shutdown_receive: how = SD_RECEIVE; break;
+        case socket::shutdown_send:    how = SD_SEND;    break;
+        case socket::shutdown_both:    how = SD_BOTH;    break;
+        default:
+            return make_err(WSAEINVAL);
+        }
+        if (::shutdown(internal_->native_handle(), how) != 0)
+            return make_err(WSAGetLastError());
+        return {};
+    }
+
     win_socket_impl_internal* get_internal() const noexcept { return internal_.get(); }
 };
 

src/corosio/src/socket.cpp

@@ -51,7 +51,7 @@ socket::
 open()
 {
     if (impl_)
-        return; // Already open
+        return;
 
     auto& svc = ctx_->use_service<socket_service>();
     auto& wrapper = svc.create_impl();
@@ -75,7 +75,7 @@ socket::
 close()
 {
     if (!impl_)
-        return; // Already closed
+        return;
 
     auto* wrapper = static_cast<socket_impl_type*>(impl_);
     wrapper->release();
@@ -94,5 +94,13 @@ cancel()
 #endif
 }
 
+void
+socket::
+shutdown(shutdown_type what)
+{
+    if (impl_)
+        get().shutdown(what);
+}
+
 } // namespace corosio
 } // namespace boost

test/unit/socket.cpp

@@ -679,6 +679,109 @@ struct socket_test
         s2.close();
     }
 
+    // Shutdown
+
+    void
+    testShutdownSend()
+    {
+        io_context ioc;
+        auto [s1, s2] = test::make_socket_pair(ioc);
+
+        auto task = [](socket& a, socket& b) -> capy::task<>
+        {
+            // Write data then shutdown send
+            co_await a.write_some(capy::const_buffer("hello", 5));
+            a.shutdown(socket::shutdown_send);
+
+            // Read the data
+            char buf[32] = {};
+            auto [ec1, n1] = co_await b.read_some(
+                capy::mutable_buffer(buf, sizeof(buf)));
+            BOOST_TEST(!ec1);
+            BOOST_TEST_EQ(std::string_view(buf, n1), "hello");
+
+            // Next read should get EOF
+            auto [ec2, n2] = co_await b.read_some(
+                capy::mutable_buffer(buf, sizeof(buf)));
+            BOOST_TEST(ec2 == capy::cond::eof);
+        };
+        capy::run_async(ioc.get_executor())(task(s1, s2));
+
+        ioc.run();
+        s1.close();
+        s2.close();
+    }
+
+    void
+    testShutdownReceive()
+    {
+        io_context ioc;
+        auto [s1, s2] = test::make_socket_pair(ioc);
+
+        auto task = [](socket& a, socket& b) -> capy::task<>
+        {
+            // Shutdown receive on b
+            b.shutdown(socket::shutdown_receive);
+
+            // b can still send
+            co_await b.write_some(capy::const_buffer("from_b", 6));
+
+            char buf[32] = {};
+            auto [ec, n] = co_await a.read_some(
+                capy::mutable_buffer(buf, sizeof(buf)));
+            BOOST_TEST(!ec);
+            BOOST_TEST_EQ(std::string_view(buf, n), "from_b");
+        };
+        capy::run_async(ioc.get_executor())(task(s1, s2));
+
+        ioc.run();
+        s1.close();
+        s2.close();
+    }
+
+    void
+    testShutdownOnClosedSocket()
+    {
+        io_context ioc;
+        socket sock(ioc);
+
+        // Shutdown on closed socket should not crash
+        sock.shutdown(socket::shutdown_send);
+        sock.shutdown(socket::shutdown_receive);
+        sock.shutdown(socket::shutdown_both);
+    }
+
+    void
+    testShutdownBothSendDirection()
+    {
+        io_context ioc;
+        auto [s1, s2] = test::make_socket_pair(ioc);
+
+        auto task = [](socket& a, socket& b) -> capy::task<>
+        {
+            // Write data then shutdown both
+            co_await a.write_some(capy::const_buffer("goodbye", 7));
+            a.shutdown(socket::shutdown_both);
+
+            // Peer should receive the data
+            char buf[32] = {};
+            auto [ec1, n1] = co_await b.read_some(
+                capy::mutable_buffer(buf, sizeof(buf)));
+            BOOST_TEST(!ec1);
+            BOOST_TEST_EQ(std::string_view(buf, n1), "goodbye");
+
+            // Next read should get EOF
+            auto [ec2, n2] = co_await b.read_some(
+                capy::mutable_buffer(buf, sizeof(buf)));
+            BOOST_TEST(ec2 == capy::cond::eof);
+        };
+        capy::run_async(ioc.get_executor())(task(s1, s2));
+
+        ioc.run();
+        s1.close();
+        s2.close();
+    }
+
     // Data Integrity
 
     void
@@ -770,6 +873,12 @@ struct socket_test
         testReadAfterPeerClose();
         testWriteAfterPeerClose();
 
+        // Shutdown
+        testShutdownSend();
+        testShutdownReceive();
+        testShutdownOnClosedSocket();
+        testShutdownBothSendDirection();
+
         // Cancellation
         testCancelRead();
         testCloseWhileReading();