feat(local): add connect_pair() public API

Mirror asio::local::connect_pair as a free function in
boost::corosio. POSIX uses socketpair(); Windows performs a
private bind/listen/accept on the caller thread paired with a
connect on a short-lived worker thread, so the caller's
io_context is never driven.

Returns std::error_code (noexcept). Stream and POSIX-only
datagram overloads. native_local_stream_socket<Backend> slices
to the base parameter; assign() routes through the backend
service.

Replaces the test-only make_local_*_pair helpers from 4b952ec;
tests, benchmarks, and the user guide are migrated.

Author: sgerbino

doc/modules/ROOT/pages/4.guide/4p.unix-sockets.adoc

@@ -22,7 +22,7 @@ Code snippets assume:
 #include <boost/corosio/local_stream_socket.hpp>
 #include <boost/corosio/local_stream_acceptor.hpp>
 #include <boost/corosio/local_datagram_socket.hpp>
-#include <boost/corosio/local_socket_pair.hpp>
+#include <boost/corosio/local_connect_pair.hpp>
 #include <boost/corosio/local_endpoint.hpp>
 #include <boost/capy/buffers.hpp>
 
@@ -123,11 +123,15 @@ capy::task<> client(corosio::io_context& ioc)
 === Socket Pairs
 
 For bidirectional IPC between a parent and child (or two coroutines),
-use `make_local_stream_pair()` which calls the `socketpair()` system call:
+use `connect_pair()`. On POSIX it uses a single `socketpair()` syscall;
+on Windows it performs a private bind/listen/accept/connect rendezvous
+on a worker thread.
 
 [source,cpp]
 ----
-auto [s1, s2] = corosio::make_local_stream_pair(ioc);
+corosio::local_stream_socket s1(ioc), s2(ioc);
+if (auto ec = corosio::connect_pair(s1, s2))
+    throw std::system_error(ec, "connect_pair");
 
 // Data written to s1 can be read from s2, and vice versa.
 co_await s1.write_some(capy::const_buffer("ping", 4));
@@ -138,9 +142,6 @@ auto [ec, n] = co_await s2.read_some(
 // buf contains "ping"
 ----
 
-This is the fastest way to create a connected pair — it uses a single
-`socketpair()` syscall with no filesystem paths involved.
-
 == Datagram Sockets
 
 Datagram sockets preserve message boundaries. Each `send` delivers exactly
@@ -173,7 +174,9 @@ After calling `connect()`, use `send`/`recv` without specifying the peer:
 
 [source,cpp]
 ----
-auto [s1, s2] = corosio::make_local_datagram_pair(ioc);
+corosio::local_datagram_socket s1(ioc), s2(ioc);
+if (auto ec = corosio::connect_pair(s1, s2))
+    throw std::system_error(ec, "connect_pair");
 
 co_await s1.send(capy::const_buffer("msg", 3));
 

include/boost/corosio.hpp

@@ -31,6 +31,7 @@
 #include <boost/corosio/timer.hpp>
 #include <boost/corosio/udp_socket.hpp>
 
+#include <boost/corosio/local_connect_pair.hpp>
 #include <boost/corosio/local_endpoint.hpp>
 #include <boost/corosio/local_stream.hpp>
 #include <boost/corosio/local_stream_socket.hpp>

include/boost/corosio/local_connect_pair.hpp

@@ -0,0 +1,80 @@
+//
+// Copyright (c) 2026 Steve Gerbino
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/corosio
+//
+
+#ifndef BOOST_COROSIO_LOCAL_CONNECT_PAIR_HPP
+#define BOOST_COROSIO_LOCAL_CONNECT_PAIR_HPP
+
+#include <boost/corosio/detail/config.hpp>
+#include <boost/corosio/detail/platform.hpp>
+#include <boost/corosio/local_stream_socket.hpp>
+
+#if BOOST_COROSIO_POSIX
+#include <boost/corosio/local_datagram_socket.hpp>
+#endif
+
+#include <system_error>
+
+namespace boost::corosio {
+
+/** Synchronously connect two AF_UNIX stream sockets as a connected pair.
+
+    On POSIX the implementation uses `socketpair(AF_UNIX, SOCK_STREAM)`
+    and adopts the descriptors via `assign()`. On Windows it performs a
+    private bind/listen/accept on the calling thread paired with a
+    `connect()` on a short-lived worker thread; the caller's
+    `io_context` is never driven, so it may be running on another
+    thread.
+
+    Either socket may be a `native_local_stream_socket<Backend>`; the
+    base reference selects the backend's `assign_socket` through normal
+    virtual dispatch.
+
+    @par Preconditions
+    Both sockets must be in the closed state.
+
+    @par Exception Safety
+    Nothrow. On failure both sockets remain closed and any underlying
+    resources are released.
+
+    @param a Receives the accepted/first endpoint of the pair.
+    @param b Receives the connected/second endpoint of the pair.
+
+    @return Empty on success; otherwise the underlying system error.
+*/
+BOOST_COROSIO_DECL
+std::error_code
+connect_pair(local_stream_socket& a, local_stream_socket& b) noexcept;
+
+#if BOOST_COROSIO_POSIX
+
+/** Synchronously connect two AF_UNIX datagram sockets as a connected pair.
+
+    POSIX only. Uses `socketpair(AF_UNIX, SOCK_DGRAM)` and adopts the
+    descriptors via `assign()`.
+
+    @par Preconditions
+    Both sockets must be in the closed state.
+
+    @par Exception Safety
+    Nothrow.
+
+    @param a First socket of the pair.
+    @param b Second socket of the pair.
+
+    @return Empty on success; otherwise the underlying system error.
+*/
+BOOST_COROSIO_DECL
+std::error_code
+connect_pair(local_datagram_socket& a, local_datagram_socket& b) noexcept;
+
+#endif // BOOST_COROSIO_POSIX
+
+} // namespace boost::corosio
+
+#endif

include/boost/corosio/local_stream_socket.hpp

@@ -470,7 +470,7 @@ class BOOST_COROSIO_DECL local_stream_socket : public io_stream
 
         The socket must not already be open. The fd is adopted
         and registered with the platform reactor. Used by
-        make_local_stream_pair() to wrap socketpair() fds.
+        connect_pair() to wrap socketpair() fds.
 
         @param fd The file descriptor to adopt. Must be a valid,
             open, non-blocking Unix stream socket.