libsigcplusplus · kjellahl · Jul 23, 2023 · Jul 22, 2023
diff --git a/sigc++/connection.h b/sigc++/connection.h
@@ -16,8 +16,10 @@
  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  *
  */
+
 #ifndef SIGC_CONNECTION_HPP
 #define SIGC_CONNECTION_HPP
+
 #include <sigc++config.h>
 #include <sigc++/functors/slot_base.h>
 #include <sigc++/weak_raw_ptr.h>
@@ -30,13 +32,20 @@ namespace sigc
  * This may be used to disconnect the referred slot at any time (disconnect()).
  * @ref sigc::signal_with_accumulator::connect() "sigc::signal::connect()"
  * returns a %sigc::connection.
+ *
  * @code
  * sigc::connection conn = sig.connect(sigc::mem_fun(a, &A::foo));
  * @endcode
+ *
  * If the slot has already been destroyed, disconnect() does nothing. empty() or
  * operator bool() can be used to test whether the connection is
  * still active. The connection can be blocked (block(), unblock()).
  *
+ * sigc::connection doesnʼt disconnect the slot automatically upon destruction.
+ * You do not need to keep the sigc::connection object to retain the connection
+ * of the slot to the signal. See also @ref sigc::scoped_connection, which does
+ * diconnect automatically when the connection object is destroyed or replaced.
+ *
  * @ingroup signal
  */
 struct SIGC_API connection

diff --git a/sigc++/filelist.am b/sigc++/filelist.am
@@ -24,6 +24,7 @@ sigc_public_h =				\
 	member_method_trait.h \
 	reference_wrapper.h		\
 	retype_return.h			\
+        scoped_connection.h             \
 	signal.h \
 	signal_base.h			\
 	slot.h			\

diff --git a/sigc++/meson.build b/sigc++/meson.build
@@ -8,6 +8,7 @@
 
 source_cc_files = [
   'connection.cc',
+  'scoped_connection.cc',
   'signal_base.cc',
   'trackable.cc',
   'functors' / 'slot_base.cc',
@@ -21,6 +22,7 @@ sigc_h_files = [
   'member_method_trait.h',
   'reference_wrapper.h',
   'retype_return.h',
+  'scoped_connection.h',
   'signal.h',
   'signal_base.h',
   'slot.h',

diff --git a/sigc++/scoped_connection.cc b/sigc++/scoped_connection.cc
@@ -0,0 +1,117 @@
+/*
+ * Copyright 2023, The libsigc++ Development Team
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ *
+ */
+
+#include <sigc++/scoped_connection.h>
+#include <utility>
+
+namespace sigc
+{
+
+// All we are doing is assigning weak_raw_ptr, which is noexcept, so declare it.
+// connectionʼs copy operators can be noexcept for that reason, if breaking ABI.
+scoped_connection::scoped_connection(connection c) noexcept
+: conn_(std::move(c))
+{
+}
+
+scoped_connection&
+scoped_connection::operator=(connection c)
+{
+  conn_.disconnect();
+  conn_ = std::move(c);
+  return *this;
+}
+
+// We do not implement move-ctor in terms of move-assign, so we can be noexcept,
+// as we do not need to call the maybe-throwing disconnect() for obvious reason.
+scoped_connection::scoped_connection(scoped_connection&& sc) noexcept
+: conn_(std::exchange(sc.conn_, connection()))
+{
+}
+
+scoped_connection&
+scoped_connection::operator=(scoped_connection&& sc)
+{
+  conn_.disconnect();
+  conn_ = std::exchange(sc.conn_, connection());
+  return *this;
+}
+
+scoped_connection::~scoped_connection()
+{
+  conn_.disconnect();
+}
+
+bool
+scoped_connection::empty() const noexcept
+{
+  return conn_.empty();
+}
+
+bool
+scoped_connection::connected() const noexcept
+{
+  return conn_.connected();
+}
+
+bool
+scoped_connection::blocked() const noexcept
+{
+  return conn_.blocked();
+}
+
+bool
+scoped_connection::block(bool should_block) noexcept
+{
+  return conn_.block(should_block);
+}
+
+bool
+scoped_connection::unblock() noexcept
+{
+  return conn_.unblock();
+}
+
+void
+scoped_connection::disconnect()
+{
+  conn_.disconnect();
+}
+
+scoped_connection::operator bool() const noexcept
+{
+  return conn_.operator bool();
+}
+
+// Swapping can be noexcept, as it does not need to disconnect either connection
+// because they will still stay alive, just in opposite instances post-swapping.
+void
+swap(scoped_connection &sca, scoped_connection &scb) noexcept
+{
+  using std::swap;
+  swap(sca.conn_, scb.conn_);
+}
+
+connection
+scoped_connection::release() noexcept
+{
+  return std::exchange(conn_, connection());
+}
+
+} /* namespace sigc */
diff --git a/sigc++/scoped_connection.h b/sigc++/scoped_connection.h
@@ -0,0 +1,175 @@
+/*
+ * Copyright 2023, The libsigc++ Development Team
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ *
+ */
+
+#ifndef SIGC_SCOPED_CONNECTION_HPP
+#define SIGC_SCOPED_CONNECTION_HPP
+
+#include <sigc++/connection.h>
+
+namespace sigc
+{
+
+/** Convenience class for safe disconnection, including automatic disconnection
+ * upon destruction.
+ *
+ * This is a variant of @ref sigc::connection which also disconnect()s the slot
+ * automatically when the scoped_connection is destructed or re-assigned. Refer
+ * to @ref sigc::connection for full information about the common functionality.
+ *
+ * You will use sigc::scoped_connection by constructing it from a ‘normal’,
+ * unscoped @ref sigc::connection, such as those returned by 
+ * @ref sigc::signal_with_accumulator::connect() "sigc::signal::connect()", thus
+ * ‘wrapping’ the connection in a scoped_connection, adding auto-disconnection.
+ * It can also be assigned from an unscoped connection, in which case, if there
+ * was a previous slot referred to by the scoped connection, it is disconnected.
+ *
+ * Once a connection is scoped, it canʼt be copied as that would make it unclear
+ * which of the copies would hold responsibility to auto-disconnect the slot. It
+ * can, however, be moved, so itʼs usable in containers or so ‘ownership’ of the
+ * connection/auto-disconnect can be moved to another instance. Moving from the
+ * scoped_connection clears its reference to the slot so it wonʼt disconnect it.
+ *
+ * If you want a reference-counted scoped_connection, wrap in a std::shared_ptr.
+ *
+ * @code
+ * // Automatic disconnection:
+ * {
+ *   sigc::scoped_connection sconn = sig.connect(&some_function);
+ *   // Do stuff that requires the slot to be connected & called.
+ * }
+ * // The scoped_connection was destroyed, so the slot is no longer connected.
+ *
+ * // ***
+ *
+ * // Moving ownership:
+ * {
+ *   sigc::scoped_connection sconn = sig.connect(&some_function);
+ *   // Do stuff that requires the slot to be connected & called.
+ *   take_ownership(std::move(sconn)); // Pass by rvalue.
+ * }
+ * // Now our `sconn` no longer referred to slot, so it did NOT auto-disconnect.
+ *
+ * // ***
+ *
+ * // Shared ownership:
+ * {
+ *   auto shconn = std::make_shared<sigc::scoped_connection>(sig.connect(&some_function));
+ *   take_copy(shconn); // Pass by copy/value
+ *   // Now we AND take_copy() must destroy our shared_ptr to auto-disconnect().
+ * }
+ * // take_copy() may still hold a shared_ptr reference, keeping the slot alive.
+ * @endcode
+ *
+ * @ingroup signal
+ * @newin{3,6}
+ */
+struct SIGC_API scoped_connection final
+{
+  /** Constructs an empty scoped connection object. */
+  [[nodiscard]] scoped_connection() noexcept = default;
+
+  /** Constructs a scoped connection object from an unscoped connection object.
+   * The source connection still refers to the slot and can manually disconnect.
+   * @param c The connection object to make a copy from, whose slot weʼll
+   *   automatically disconnect when the scoped_connection object is destroyed.
+   */
+  [[nodiscard]] scoped_connection(connection c) noexcept;
+
+  /** Overrides this scoped connection object copying an unscoped connection.
+   * The current slot, if any, will be disconnect()ed before being replaced.
+   * The source connection still refers to the slot and can manually disconnect.
+   * @param c The connection object to make a copy from, whose slot weʼll
+   *   automatically disconnect when the scoped_connection object is destroyed.
+   */
+  scoped_connection& operator=(connection c);
+
+  /// scoped_connection canʼt be copied as it would confuse ownership—see intro.
+  scoped_connection& operator=(const scoped_connection&) = delete;
+  /// scoped_connection canʼt be copied as it would confuse ownership—see intro.
+  scoped_connection(const scoped_connection&) = delete;
+
+  /** Constructs a scoped connection object moving an existing one.
+   * The source scoped connection will no longer refer to / disconnect the slot.
+   * @param sc The scoped connection object to move from.
+   */
+  scoped_connection(scoped_connection&& sc) noexcept;
+
+  /** Overrides this scoped connection object moving another one.
+   * The current slot, if any, will be disconnect()ed before being replaced.
+   * The source scoped connection will no longer refer to / disconnect the slot.
+   * @param sc The scoped connection object to move from.
+   */
+  scoped_connection& operator=(scoped_connection&& sc);
+
+  /// Swap two scoped connections.
+  friend void swap(scoped_connection &sca, scoped_connection &scb) noexcept;
+
+  /// scoped_connection disconnects the referred slot, if any, upon destruction.
+  ~scoped_connection();
+
+  /** Returns whether the connection is still active.
+   * @return @p false if the connection is still active.
+   */
+  [[nodiscard]] bool empty() const noexcept;
+
+  /** Returns whether the connection is still active.
+   * @return @p true if the connection is still active.
+   */
+  [[nodiscard]] bool connected() const noexcept;
+
+  /** Returns whether the connection is blocked.
+   * @return @p true if the connection is blocked.
+   */
+  [[nodiscard]] bool blocked() const noexcept;
+
+  /** Sets or unsets the blocking state of this connection.
+   * See slot_base::block() for details.
+   * @param should_block Indicates whether the blocking state should be set or unset.
+   * @return @p true if the connection has been in blocking state before.
+   */
+  bool block(bool should_block = true) noexcept;
+
+  /** Unsets the blocking state of this connection.
+   * @return @p true if the connection has been in blocking state before.
+   */
+  bool unblock() noexcept;
+
+  /// Disconnects the referred slot. This will also happen upon destruction.
+  void disconnect();
+
+  /** Returns whether the connection is still active.
+   * @return @p true if the connection is still active.
+   */
+  [[nodiscard]] explicit operator bool() const noexcept;
+
+  /** Releases the connection from a scoped connection object.
+   * The scoped connection will no longer refer to / disconnect the slot.
+   * @return An unscoped connection object referring to the same slot.
+   */
+  [[nodiscard]] connection release() noexcept;
+
+private:
+  sigc::connection conn_;
+};
+
+void swap(scoped_connection &sca, scoped_connection &scb) noexcept;
+
+} /* namespace sigc */
+
+#endif /* SIGC_SCOPED_CONNECTION_HPP */
diff --git a/sigc++/sigc++.h b/sigc++/sigc++.h
@@ -117,6 +117,7 @@
 
 #include <sigc++/signal.h>
 #include <sigc++/connection.h>
+#include <sigc++/scoped_connection.h>
 #include <sigc++/trackable.h>
 #include <sigc++/adaptors/adaptors.h>
 #include <sigc++/functors/functors.h>

diff --git a/tests/Makefile.am b/tests/Makefile.am
@@ -47,6 +47,7 @@ check_PROGRAMS = \
   test_retype \
   test_retype_return \
   test_rvalue_ref \
+  test_scoped_connection \
   test_signal \
   test_signal_move \
   test_size \

diff --git a/tests/meson.build b/tests/meson.build
@@ -29,6 +29,7 @@ test_programs = [
   [[], 'test_retype', ['test_retype.cc', 'testutilities.cc']],
   [[], 'test_retype_return', ['test_retype_return.cc', 'testutilities.cc']],
   [[], 'test_rvalue_ref', ['test_rvalue_ref.cc', 'testutilities.cc']],
+  [[], 'test_scoped_connection', ['test_scoped_connection.cc', 'testutilities.cc']],
   [[], 'test_signal', ['test_signal.cc', 'testutilities.cc']],
   [[], 'test_signal_move', ['test_signal_move.cc', 'testutilities.cc']],
   [[], 'test_size', ['test_size.cc', 'testutilities.cc']],