Socket: documentation

src/socket_async_impl.cpp

@@ -183,6 +183,7 @@ bool SocketAsyncImpl::DriverSend(SendQ &q)
 {
   auto const sendQSize = q.size();
   if(!sendQSize) {
+    // TLS socket has requested write for TLS handshake
     buff->sock->DriverPending();
     return true;
   }

src/socket_impl.cpp

@@ -293,7 +293,7 @@ std::shared_ptr<SockAddrStorage> SocketImpl::GetPeerName() const
 
 void SocketImpl::DriverQuery(short &)
 {
-  return;
+  // only actively used by the TLS socket
 }
 
 void SocketImpl::DriverPending()

src/socket_tls_impl.cpp

@@ -22,8 +22,8 @@ constexpr int handshakeStepsMax = 10;
 template<typename Fn>
 auto UnderDeadline(Fn &&fn, Duration &timeout) -> auto
 {
-  if(timeout.count() <= 0) {
-    return fn(); // remains unchanged
+  if(timeout.count() <= 0) { // remains unchanged
+    return fn();
   }
 
   // update timeout (may be exceeded)
@@ -420,13 +420,16 @@ void SocketTlsImpl::DriverQuery(short &events)
 {
   if(!SSL_is_init_finished(ssl.get())) {
     if(lastError == SSL_ERROR_WANT_WRITE) {
+      // while handshake send is pending we actively request send attempts from the Driver
       events |= POLLOUT;
     } else if(lastError == SSL_ERROR_WANT_READ) {
-      driverPending |= (events & POLLOUT);
+      // while handshake receive is pending we suppress send attempts from the Driver
+      driverSendSuppressed |= (events & POLLOUT);
       events &= ~POLLOUT;
     }
-  } else if (driverPending) {
-    driverPending = false;
+  } else if (driverSendSuppressed) {
+    // if Driver send has been suppressed before handshake finished, restore it now
+    driverSendSuppressed = false;
     events |= POLLOUT;
   }
 }

src/socket_tls_impl.h

@@ -14,8 +14,9 @@
 namespace sockpuppet {
 
 // the interface matches SocketImpl but some implicit differences exist:
-//   may be readable but no user data can be read (only handshake data)
-//   handshake data is sent/received on the socket during both send AND read
+//   may be readable but no user data can be received (only handshake data)
+//   may be writable but no user data can be sent (handshake pending)
+//   handshake data is sent/received on the socket during both send AND receive
 //   if a send with limited timeout fails, it must be retried with the same data
 //     (see https://www.openssl.org/docs/man1.1.1/man3/SSL_write.html)
 struct SocketTlsImpl final : public SocketImpl
@@ -33,7 +34,7 @@ struct SocketTlsImpl final : public SocketImpl
   Duration remainingTime;  ///< Use-case dependent timeout
   bool isReadable = false;  ///< Flag whether Driver has deemed us readable
   bool isWritable = false;  ///< Flag whether Driver has deemed us writable
-  bool driverPending = false;  ///< Flag whether Driver send was suppressed
+  bool driverSendSuppressed = false;  ///< Flag whether Driver send polling was suppressed
 
   SocketTlsImpl(int family,
                 int type,