Introduce QSocketNotifier::activate(QSocketDescriptor, QSN::Type)

The pre-existing overload passes an int, but this can mean the
descriptor gets truncated in compilations where the descriptor
is 64-bit.

The old overload with int is visible when querying the metaobject system
so string-based connects still work as before, and connecting to it will
produce a deprecation warning in the output.
At the same time the PMF-based connect will, on recompile, pick the
QSocketDescriptor overload. As an added improvement it also comes with
the notification type, removing the need for separate slots where the
code would be mostly shared anyway.

The QSocketDescriptor type can be implicitly converted to and from
qintptr to ensure existing code still compiles. It can also be
constructed from Qt::HANDLE on Windows.

In this same patch I also update the existing string-based connects in
this module, which then includes updating the parameters for some slots
as well.

[ChangeLog][QtCore][QSocketNotifier] Added
QSocketNotifier::activated(QSocketDescriptor, QSocketNotifier::Type).
This replaces the activated(int) signal which in 64-bit environments
could truncate the socket descriptor. If you use "activated" with the
string-based connect() then you need to update the parameter type of the
signal and slot if it had one. If you use it with the pointer to member
function based connect() then all you need to do is update your slot's
parameter type if it has one. If you need to compile your source code
with multiple versions of Qt then connect() to this function using
pointer to member function and update the slot's parameter type if
needed.

Task-number: QTBUG-70441
Change-Id: Ic43d6bc4c5bcb4040867b2ffad8d36fb01eed8af
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

2 files changed, 141 insertions, 5 deletions

diff --git a/src/corelib/kernel/qsocketnotifier.cpp b/src/corelib/kernel/qsocketnotifier.cpp
index 78269ee605..6c032d13ae 100644
--- a/src/corelib/kernel/qsocketnotifier.cpp
+++ b/src/corelib/kernel/qsocketnotifier.cpp
@@ -37,23 +37,32 @@
 **
 ****************************************************************************/
 
+#define BUILDING_QSOCKETNOTIFIER
 #include "qsocketnotifier.h"
+#undef BUILDING_QSOCKETNOTIFIER
 
 #include "qplatformdefs.h"
 
 #include "qabstracteventdispatcher.h"
 #include "qcoreapplication.h"
 
+#include "qmetatype.h"
+
 #include "qobject_p.h"
 #include <private/qthread_p.h>
 
+#include <QtCore/QLoggingCategory>
+
 QT_BEGIN_NAMESPACE
 
+Q_DECLARE_LOGGING_CATEGORY(lcSocketNotifierDeprecation)
+Q_LOGGING_CATEGORY(lcSocketNotifierDeprecation, "qt.core.socketnotifier_deprecation");
+
 class QSocketNotifierPrivate : public QObjectPrivate
 {
     Q_DECLARE_PUBLIC(QSocketNotifier)
 public:
-    qintptr sockfd;
+    QSocketDescriptor sockfd;
     QSocketNotifier::Type sntype;
     bool snenabled;
 };
@@ -143,13 +152,17 @@ QSocketNotifier::QSocketNotifier(qintptr socket, Type type, QObject *parent)
     : QObject(*new QSocketNotifierPrivate, parent)
 {
     Q_D(QSocketNotifier);
+
+    qRegisterMetaType<QSocketDescriptor>();
+    qRegisterMetaType<QSocketNotifier::Type>();
+
     d->sockfd = socket;
     d->sntype = type;
     d->snenabled = true;
 
     auto thisThreadData = d->threadData.loadRelaxed();
 
-    if (socket < 0)
+    if (!d->sockfd.isValid())
         qWarning("QSocketNotifier: Invalid socket specified");
     else if (!thisThreadData->hasEventDispatcher())
         qWarning("QSocketNotifier: Can only be used with threads started with QThread");
@@ -169,6 +182,11 @@ QSocketNotifier::~QSocketNotifier()
 
 /*!
     \fn void QSocketNotifier::activated(int socket)
+    \obsolete To avoid unintended truncation of the descriptor, use
+    the QSocketDescriptor overload of this function. If you need
+    compatibility with versions older than 5.15 you need to change
+    the slot to accept qintptr if it currently accepts an int, and
+    then connect using Functor-Based Connection.
 
     This signal is emitted whenever the socket notifier is enabled and
     a socket event corresponding to its \l {Type}{type} occurs.
@@ -178,6 +196,18 @@ QSocketNotifier::~QSocketNotifier()
     \sa type(), socket()
 */
 
+/*!
+    \fn void QSocketNotifier::activated(QSocketDescriptor socket, QSocketNotifier::Type type)
+    \since 5.15
+
+    This signal is emitted whenever the socket notifier is enabled and
+    a socket event corresponding to its \a type occurs.
+
+    The socket identifier is passed in the \a socket parameter.
+
+    \sa type(), socket()
+*/
+
 
 /*!
     Returns the socket identifier specified to the constructor.
@@ -187,7 +217,7 @@ QSocketNotifier::~QSocketNotifier()
 qintptr QSocketNotifier::socket() const
 {
     Q_D(const QSocketNotifier);
-    return d->sockfd;
+    return qintptr(d->sockfd);
 }
 
 /*!
@@ -230,7 +260,7 @@ bool QSocketNotifier::isEnabled() const
 void QSocketNotifier::setEnabled(bool enable)
 {
     Q_D(QSocketNotifier);
-    if (d->sockfd < 0)
+    if (!d->sockfd.isValid())
         return;
     if (d->snenabled == enable)                        // no change
         return;
@@ -268,12 +298,57 @@ bool QSocketNotifier::event(QEvent *e)
     }
     QObject::event(e);                        // will activate filters
     if ((e->type() == QEvent::SockAct) || (e->type() == QEvent::SockClose)) {
-        emit activated(d->sockfd, QPrivateSignal());
+        QPointer<QSocketNotifier> alive(this);
+        emit activated(d->sockfd, d->sntype, QPrivateSignal());
+        // ### Qt7: Remove emission if the activated(int) signal is removed
+        if (alive)
+            emit activated(int(qintptr(d->sockfd)), QPrivateSignal());
+
         return true;
     }
     return false;
 }
 
+/*!
+    \class QSocketDescriptor
+    \inmodule QtCore
+    \brief A class which holds a native socket descriptor.
+
+    \ingroup network
+    \ingroup io
+
+    \since 5.15
+
+    QSocketDescriptor makes it easier to handle native socket
+    descriptors in cross-platform code.
+
+    On Windows it holds a \c {Qt::HANDLE} and on Unix it holds an \c int.
+    The class will implicitly convert between the class and the
+    native descriptor type.
+*/
+
+/*!
+    \fn QSocketDescriptor::QSocketDescriptor(DescriptorType descriptor)
+
+    Construct a QSocketDescriptor from a native socket \a descriptor.
+*/
+
+/*!
+    \fn QSocketDescriptor::QSocketDescriptor(qintptr descriptor)
+
+    Construct a QSocketDescriptor from a native socket \a descriptor.
+
+    \note This constructor is only available on Windows.
+*/
+
+/*!
+    \fn Qt::HANDLE QSocketDescriptor::winHandle() const noexcept
+
+    Returns the internal handle.
+
+    \note This function is only available on Windows.
+*/
+
 QT_END_NAMESPACE
 
 #include "moc_qsocketnotifier.cpp"
diff --git a/src/corelib/kernel/qsocketnotifier.h b/src/corelib/kernel/qsocketnotifier.h
index 38e5f27247..808931e04b 100644
--- a/src/corelib/kernel/qsocketnotifier.h
+++ b/src/corelib/kernel/qsocketnotifier.h
@@ -44,6 +44,7 @@
 
 QT_BEGIN_NAMESPACE
 
+class QSocketDescriptor;
 class QSocketNotifierPrivate;
 class Q_CORE_EXPORT QSocketNotifier : public QObject
 {
@@ -65,7 +66,23 @@ public Q_SLOTS:
     void setEnabled(bool);
 
 Q_SIGNALS:
+#if defined(Q_MOC_RUN)
+    // Add default arguments during Q_MOC_RUN which makes moc generate "signals" which takes less
+    // parameters, but we won't actually allow emitting without all 3. This lets users use the
+    // string-based connect without specifying QSocketNotifier::Type as one of the parameters.
+    void activated(QSocketDescriptor socket, QSocketNotifier::Type activationEvent = Read,
+                   QPrivateSignal = {});
+#else
+    void activated(QSocketDescriptor socket, QSocketNotifier::Type activationEvent, QPrivateSignal);
+#endif
+
+    // ### Qt7: consider removing it.
+    // The old signal is compiled internally, but hidden outside of this class.
+    // This means the PMF-based connect(..) will automatically, on recompile, pick up the new
+    // version while the old-style connect(..) can query the metaobject system for this version.
+#if defined(Q_MOC_RUN) || defined(BUILDING_QSOCKETNOTIFIER) || defined(Q_QDOC)
     void activated(int socket, QPrivateSignal);
+#endif
 
 protected:
     bool event(QEvent *) override;
@@ -74,6 +91,50 @@ private:
     Q_DISABLE_COPY(QSocketNotifier)
 };
 
+class QSocketDescriptor
+{
+public:
+#if defined(Q_OS_WIN)
+    using DescriptorType = Qt::HANDLE;
+#define Q_DECL_CONSTEXPR_NOT_WIN
+#else
+    using DescriptorType = int;
+#define Q_DECL_CONSTEXPR_NOT_WIN Q_DECL_CONSTEXPR
+#endif
+
+    /* implicit */ Q_DECL_CONSTEXPR_NOT_WIN
+    QSocketDescriptor(DescriptorType descriptor = DescriptorType(-1)) noexcept : sockfd(descriptor)
+    {
+    }
+
+#if defined(Q_OS_WIN) || defined(Q_QDOC)
+    /* implicit */ QSocketDescriptor(qintptr desc) noexcept : sockfd(DescriptorType(desc)) {}
+    operator qintptr() const noexcept { return qintptr(sockfd); }
+    Q_DECL_CONSTEXPR Qt::HANDLE winHandle() const noexcept { return sockfd; }
+#endif
+    Q_DECL_CONSTEXPR operator DescriptorType() const noexcept { return sockfd; }
+
+    Q_DECL_CONSTEXPR_NOT_WIN bool isValid() const noexcept { return *this != QSocketDescriptor(); }
+
+    friend Q_DECL_CONSTEXPR_NOT_WIN bool operator==(QSocketDescriptor lhs,
+                                                    QSocketDescriptor rhs) noexcept
+    {
+        return lhs.sockfd == rhs.sockfd;
+    }
+    friend Q_DECL_CONSTEXPR_NOT_WIN bool operator!=(QSocketDescriptor lhs,
+                                                    QSocketDescriptor rhs) noexcept
+    {
+        return lhs.sockfd != rhs.sockfd;
+    }
+
+#undef Q_DECL_CONSTEXPR_NOT_WIN
+
+private:
+    DescriptorType sockfd;
+};
+
 QT_END_NAMESPACE
+Q_DECLARE_METATYPE(QSocketNotifier::Type)
+Q_DECLARE_METATYPE(QSocketDescriptor)
 
 #endif // QSOCKETNOTIFIER_H