SubscriptionThreadDispatcher: proper replacing of audio/video callbacks. Deprecate a setOn*Callback(), replace with trySetOn*Callback()

Author: stephen-derosa

include/livekit/room.h

@@ -303,16 +303,118 @@ class LIVEKIT_API Room {
   // Frame callbacks
   // ---------------------------------------------------------------
 
-  /// @brief Sets the audio frame callback via SubscriptionThreadDispatcher.
+  /// Register an audio frame callback for a remote subscription.
+  ///
+  /// The callback is keyed by @p participant_identity and @p track_name. If the
+  /// matching remote audio track is already subscribed, a reader is started
+  /// immediately; otherwise the reader starts when the track is subscribed.
+  ///
+  /// To replace a callback whose reader is already running, call
+  /// @ref clearOnAudioFrameCallback first, then register again:
+  /// @code
+  /// room.clearOnAudioFrameCallback(identity, track_name);
+  /// if (!room.trySetOnAudioFrameCallback(identity, track_name, new_handler)) {
+  ///   // registration was rejected (a reader is still active)
+  /// }
+  /// @endcode
+  ///
+  /// @param participant_identity Identity of the remote participant.
+  /// @param track_name           Track name to match.
+  /// @param callback             Function invoked for each decoded audio frame.
+  /// @param opts                 Options used when creating the backing
+  ///                             @ref AudioStream.
+  /// @return @c true if the callback was registered; @c false if a reader is
+  ///         already active for the key (call @ref clearOnAudioFrameCallback
+  ///         first) or the room has no dispatcher.
+  [[nodiscard]] bool trySetOnAudioFrameCallback(const std::string& participant_identity, const std::string& track_name,
+                                                AudioFrameCallback callback, const AudioStream::Options& opts = {});
+
+  /// Register a video frame callback for a remote subscription.
+  ///
+  /// The callback is keyed by @p participant_identity and @p track_name. If the
+  /// matching remote video track is already subscribed, a reader is started
+  /// immediately; otherwise the reader starts when the track is subscribed.
+  ///
+  /// To replace a callback whose reader is already running, call
+  /// @ref clearOnVideoFrameCallback first, then register again.
+  ///
+  /// @param participant_identity Identity of the remote participant.
+  /// @param track_name           Track name to match.
+  /// @param callback             Function invoked for each decoded video frame.
+  /// @param opts                 Options used when creating the backing
+  ///                             @ref VideoStream.
+  /// @return @c true if the callback was registered; @c false if a reader is
+  ///         already active for the key (call @ref clearOnVideoFrameCallback
+  ///         first) or the room has no dispatcher.
+  [[nodiscard]] bool trySetOnVideoFrameCallback(const std::string& participant_identity, const std::string& track_name,
+                                                VideoFrameCallback callback, const VideoStream::Options& opts = {});
+
+  /// Register a rich video frame event callback for a remote subscription.
+  ///
+  /// The callback is keyed by @p participant_identity and @p track_name. If the
+  /// matching remote video track is already subscribed, a reader is started
+  /// immediately; otherwise the reader starts when the track is subscribed.
+  ///
+  /// To replace a callback whose reader is already running, call
+  /// @ref clearOnVideoFrameCallback first, then register again.
+  ///
+  /// @param participant_identity Identity of the remote participant.
+  /// @param track_name           Track name to match.
+  /// @param callback             Function invoked for each decoded video frame
+  ///                             event, including optional metadata.
+  /// @param opts                 Options used when creating the backing
+  ///                             @ref VideoStream.
+  /// @return @c true if the callback was registered; @c false if a reader is
+  ///         already active for the key (call @ref clearOnVideoFrameCallback
+  ///         first) or the room has no dispatcher.
+  [[nodiscard]] bool trySetOnVideoFrameEventCallback(const std::string& participant_identity,
+                                                     const std::string& track_name, VideoFrameEventCallback callback,
+                                                     const VideoStream::Options& opts = {});
+
+  /// @deprecated Use trySetOnAudioFrameCallback() instead.
+  ///
+  /// Forwards to @ref trySetOnAudioFrameCallback and discards the result.
+  /// Replacing an active callback is not supported through this overload; call
+  /// @ref clearOnAudioFrameCallback first, then @ref trySetOnAudioFrameCallback.
+  ///
+  /// @param participant_identity Identity of the remote participant.
+  /// @param track_name           Track name to match.
+  /// @param callback             Function invoked for each decoded audio frame.
+  /// @param opts                 Options used when creating the backing
+  ///                             @ref AudioStream.
+  [[deprecated("Room::setOnAudioFrameCallback is deprecated; use trySetOnAudioFrameCallback instead")]]
   void setOnAudioFrameCallback(const std::string& participant_identity, const std::string& track_name,
                                AudioFrameCallback callback, const AudioStream::Options& opts = {});
 
-  /// @brief Sets the video frame callback via SubscriptionThreadDispatcher.
+  /// @deprecated Use trySetOnVideoFrameCallback() instead.
+  ///
+  /// Forwards to @ref trySetOnVideoFrameCallback and discards the result.
+  /// Replacing an active callback is not supported through this overload; call
+  /// @ref clearOnVideoFrameCallback first, then @ref trySetOnVideoFrameCallback.
+  ///
+  /// @param participant_identity Identity of the remote participant.
+  /// @param track_name           Track name to match.
+  /// @param callback             Function invoked for each decoded video frame.
+  /// @param opts                 Options used when creating the backing
+  ///                             @ref VideoStream.
+  [[deprecated("Room::setOnVideoFrameCallback is deprecated; use trySetOnVideoFrameCallback instead")]]
   void setOnVideoFrameCallback(const std::string& participant_identity, const std::string& track_name,
                                VideoFrameCallback callback, const VideoStream::Options& opts = {});
 
-  /// @brief Sets the video frame event callback via
-  /// SubscriptionThreadDispatcher.
+  /// @deprecated Use trySetOnVideoFrameEventCallback() instead.
+  ///
+  /// Forwards to @ref trySetOnVideoFrameEventCallback and discards the result.
+  /// Replacing an active callback is not supported through this overload; call
+  /// @ref clearOnVideoFrameCallback first, then
+  /// @ref trySetOnVideoFrameEventCallback.
+  ///
+  /// @param participant_identity Identity of the remote participant.
+  /// @param track_name           Track name to match.
+  /// @param callback             Function invoked for each decoded video frame
+  ///                             event, including optional metadata.
+  /// @param opts                 Options used when creating the backing
+  ///                             @ref VideoStream.
+  [[deprecated("Room::setOnVideoFrameEventCallback is deprecated; use trySetOnVideoFrameEventCallback instead")]]
   void setOnVideoFrameEventCallback(const std::string& participant_identity, const std::string& track_name,
                                     VideoFrameEventCallback callback, const VideoStream::Options& opts = {});
 
@@ -354,6 +456,12 @@ class LIVEKIT_API Room {
   // FfiClient listener ID (0 means no listener registered)
   int listener_id_{0};
 
+  /// Find a currently subscribed remote track matching the given participant
+  /// identity and track name. Returns nullptr if no such subscribed track
+  /// exists. Acquires @ref lock_.
+  std::shared_ptr<Track> findSubscribedRemoteTrack(const std::string& participant_identity,
+                                                   const std::string& track_name) const;
+
   void onEvent(const proto::FfiEvent& event);
 };
 } // namespace livekit

include/livekit/subscription_thread_dispatcher.h

@@ -93,54 +93,124 @@ class LIVEKIT_API SubscriptionThreadDispatcher {
   /// Stops all active readers and clears all registered callbacks.
   ~SubscriptionThreadDispatcher();
 
-  /// Register or replace an audio frame callback for a remote subscription.
+  /// Register an audio frame callback for a remote subscription.
   ///
   /// The callback is keyed by remote participant identity plus @p track_name.
   /// If the matching remote audio track is already subscribed, @ref Room may
   /// immediately call @ref handleTrackSubscribed to start a reader.
   ///
+  /// Registration only succeeds when no reader is currently active for the
+  /// key. To replace a callback whose reader is already running, call
+  /// @ref clearOnAudioFrameCallback first, then register again.
+  ///
   /// @param participant_identity Identity of the remote participant.
   /// @param track_name           Track name to match.
   /// @param callback             Function invoked for each decoded audio frame.
   /// @param opts                 Options used when creating the backing
   ///                             @ref AudioStream.
-  void setOnAudioFrameCallback(const std::string& participant_identity, const std::string& track_name,
-                               AudioFrameCallback callback, const AudioStream::Options& opts = {});
+  /// @return @c true if the callback was registered; @c false if a reader is
+  ///         already active for the key (the registration is left unchanged).
+  [[nodiscard]] bool trySetOnAudioFrameCallback(const std::string& participant_identity, const std::string& track_name,
+                                                AudioFrameCallback callback, const AudioStream::Options& opts = {});
 
-  /// Register or replace a video frame callback for a remote subscription.
+  /// Register a video frame callback for a remote subscription.
   ///
   /// The callback is keyed by remote participant identity plus @p track_name.
   /// If the matching remote video track is already subscribed, @ref Room may
   /// immediately call @ref handleTrackSubscribed to start a reader.
   ///
+  /// Registration only succeeds when no reader is currently active for the
+  /// key. To replace a callback whose reader is already running, call
+  /// @ref clearOnVideoFrameCallback first, then register again.
+  ///
   /// @param participant_identity Identity of the remote participant.
   /// @param track_name           Track name to match.
   /// @param callback             Function invoked for each decoded video frame.
   /// @param opts                 Options used when creating the backing
   ///                             @ref VideoStream.
-  void setOnVideoFrameCallback(const std::string& participant_identity, const std::string& track_name,
-                               VideoFrameCallback callback, const VideoStream::Options& opts = {});
+  /// @return @c true if the callback was registered; @c false if a reader is
+  ///         already active for the key (the registration is left unchanged).
+  [[nodiscard]] bool trySetOnVideoFrameCallback(const std::string& participant_identity, const std::string& track_name,
+                                                VideoFrameCallback callback, const VideoStream::Options& opts = {});
 
-  /// Register or replace a rich video frame event callback for a remote
-  /// subscription.
+  /// Register a rich video frame event callback for a remote subscription.
   ///
   /// The callback is keyed by remote participant identity plus @p track_name.
   /// If the matching remote video track is already subscribed, @ref Room may
   /// immediately call @ref handleTrackSubscribed to start a reader.
   ///
+  /// Registration only succeeds when no reader is currently active for the
+  /// key. To replace a callback whose reader is already running, call
+  /// @ref clearOnVideoFrameCallback first, then register again.
+  ///
+  /// @param participant_identity Identity of the remote participant.
+  /// @param track_name           Track name to match.
+  /// @param callback             Function invoked for each decoded video frame
+  ///                             event, including optional metadata.
+  /// @param opts                 Options used when creating the backing
+  ///                             @ref VideoStream.
+  /// @return @c true if the callback was registered; @c false if a reader is
+  ///         already active for the key (the registration is left unchanged).
+  [[nodiscard]] bool trySetOnVideoFrameEventCallback(const std::string& participant_identity,
+                                                     const std::string& track_name, VideoFrameEventCallback callback,
+                                                     const VideoStream::Options& opts = {});
+
+  /// @deprecated Use trySetOnAudioFrameCallback() instead.
+  ///
+  /// Forwards to @ref trySetOnAudioFrameCallback and discards the result.
+  /// Replacing an active callback is not supported through this overload; call
+  /// @ref clearOnAudioFrameCallback first, then @ref trySetOnAudioFrameCallback.
+  ///
+  /// @param participant_identity Identity of the remote participant.
+  /// @param track_name           Track name to match.
+  /// @param callback             Function invoked for each decoded audio frame.
+  /// @param opts                 Options used when creating the backing
+  ///                             @ref AudioStream.
+  [[deprecated(
+      "SubscriptionThreadDispatcher::setOnAudioFrameCallback is deprecated; use trySetOnAudioFrameCallback instead")]]
+  void setOnAudioFrameCallback(const std::string& participant_identity, const std::string& track_name,
+                               AudioFrameCallback callback, const AudioStream::Options& opts = {});
+
+  /// @deprecated Use trySetOnVideoFrameCallback() instead.
+  ///
+  /// Forwards to @ref trySetOnVideoFrameCallback and discards the result.
+  /// Replacing an active callback is not supported through this overload; call
+  /// @ref clearOnVideoFrameCallback first, then @ref trySetOnVideoFrameCallback.
+  ///
+  /// @param participant_identity Identity of the remote participant.
+  /// @param track_name           Track name to match.
+  /// @param callback             Function invoked for each decoded video frame.
+  /// @param opts                 Options used when creating the backing
+  ///                             @ref VideoStream.
+  [[deprecated(
+      "SubscriptionThreadDispatcher::setOnVideoFrameCallback is deprecated; use trySetOnVideoFrameCallback instead")]]
+  void setOnVideoFrameCallback(const std::string& participant_identity, const std::string& track_name,
+                               VideoFrameCallback callback, const VideoStream::Options& opts = {});
+
+  /// @deprecated Use trySetOnVideoFrameEventCallback() instead.
+  ///
+  /// Forwards to @ref trySetOnVideoFrameEventCallback and discards the result.
+  /// Replacing an active callback is not supported through this overload; call
+  /// @ref clearOnVideoFrameCallback first, then
+  /// @ref trySetOnVideoFrameEventCallback.
+  ///
   /// @param participant_identity Identity of the remote participant.
   /// @param track_name           Track name to match.
   /// @param callback             Function invoked for each decoded video frame
   ///                             event, including optional metadata.
   /// @param opts                 Options used when creating the backing
   ///                             @ref VideoStream.
+  [[deprecated(
+      "SubscriptionThreadDispatcher::setOnVideoFrameEventCallback is deprecated; use "
+      "trySetOnVideoFrameEventCallback instead")]]
   void setOnVideoFrameEventCallback(const std::string& participant_identity, const std::string& track_name,
                                     VideoFrameEventCallback callback, const VideoStream::Options& opts = {});
 
   /// Remove an audio callback registration and stop any active reader.
   ///
   /// If an audio reader thread is active for the given key, its stream is
-  /// closed and the thread is joined before this call returns.
+  /// closed and the thread is joined before this call returns. Call this
+  /// before @ref trySetOnAudioFrameCallback to replace an active callback.
   ///
   /// @param participant_identity Identity of the remote participant.
   /// @param track_name           Track name to clear.
@@ -149,7 +219,9 @@ class LIVEKIT_API SubscriptionThreadDispatcher {
   /// Remove a video callback registration and stop any active reader.
   ///
   /// If a video reader thread is active for the given key, its stream is
-  /// closed and the thread is joined before this call returns.
+  /// closed and the thread is joined before this call returns. Call this
+  /// before @ref trySetOnVideoFrameCallback (or
+  /// @ref trySetOnVideoFrameEventCallback) to replace an active callback.
   ///
   /// @param participant_identity Identity of the remote participant.
   /// @param track_name           Track name to clear.