mr comments, update cpp collection example

Author: stephen-derosa

cpp-example-collection

@@ -152,7 +152,7 @@ class LIVEKIT_API Room {
   /// The returned handle is non-owning. Call @c lock() to obtain a usable
   /// @c weak_ptr; the result is empty (`lock() == nullptr`) before connect,
   /// after room end-of-stream teardown, or once the room is destroyed. This
-  /// lets callers that cache the handle detect teardown instead of holding a
+  /// lets callers that cache the handle detect object lifetime instead of holding a
   /// dangling pointer.
   ///
   /// @return Weak handle to the local participant.
@@ -287,14 +287,17 @@ class LIVEKIT_API Room {
   RoomDelegate* delegate_ = nullptr; // Not owned
   RoomInfoData room_info_;
   std::shared_ptr<FfiHandle> room_handle_;
+  /// The local participant is owned by the room and is not shared with other objects.
+  /// It is a shared_ptr just to utilize the weak_ptr interface for the localParticipant() accessor.
   std::shared_ptr<LocalParticipant> local_participant_;
   std::unordered_map<std::string, std::shared_ptr<RemoteParticipant>> remote_participants_;
   // Data stream
   std::unordered_map<std::string, TextStreamHandler> text_stream_handlers_;
   std::unordered_map<std::string, ByteStreamHandler> byte_stream_handlers_;
   std::unordered_map<std::string, std::shared_ptr<TextStreamReader>> text_stream_readers_;
   std::unordered_map<std::string, std::shared_ptr<ByteStreamReader>> byte_stream_readers_;
-  // E2EE
+  // The E2EE manager is owned by the room and is not shared with other objects.
+  // It is a shared_ptr just to utilize the weak_ptr interface for the e2eeManager() accessor.
   std::shared_ptr<E2EEManager> e2ee_manager_;
   std::shared_ptr<SubscriptionThreadDispatcher> subscription_thread_dispatcher_;
 

include/livekit/room.h

@@ -138,6 +138,49 @@ inline bool waitForParticipant(Room* room, const std::string& identity, std::chr
   return false;
 }
 
+/// Safely promote the local participant weak handle to a shared_ptr.
+///
+/// Room::localParticipant() returns a std::weak_ptr whose lock() yields nullptr
+/// once the room is torn down (or before connect). Dereferencing the result of
+/// lock() blindly is undefined behavior, so tests must go through this helper,
+/// which throws instead of crashing when the handle is expired.
+inline std::shared_ptr<LocalParticipant> lockLocalParticipant(const Room& room) {
+  auto participant = room.localParticipant().lock();
+  if (!participant) {
+    throw std::runtime_error("Local participant handle is expired");
+  }
+  return participant;
+}
+
+/// Pointer overload of lockLocalParticipant(); throws if @p room is null.
+inline std::shared_ptr<LocalParticipant> lockLocalParticipant(const Room* room) {
+  if (room == nullptr) {
+    throw std::runtime_error("Room is null");
+  }
+  return lockLocalParticipant(*room);
+}
+
+/// Safely promote a remote participant weak handle to a shared_ptr.
+///
+/// Mirrors lockLocalParticipant(): Room::remoteParticipant() returns a
+/// std::weak_ptr that lock()s to nullptr once the participant disconnects, so
+/// this helper throws rather than letting callers dereference a null pointer.
+inline std::shared_ptr<RemoteParticipant> lockRemoteParticipant(const Room& room, const std::string& identity) {
+  auto participant = room.remoteParticipant(identity).lock();
+  if (!participant) {
+    throw std::runtime_error("Remote participant '" + identity + "' handle is expired");
+  }
+  return participant;
+}
+
+/// Pointer overload of lockRemoteParticipant(); throws if @p room is null.
+inline std::shared_ptr<RemoteParticipant> lockRemoteParticipant(const Room* room, const std::string& identity) {
+  if (room == nullptr) {
+    throw std::runtime_error("Room is null");
+  }
+  return lockRemoteParticipant(*room, identity);
+}
+
 inline std::array<std::string, 2> getDataTrackTestTokens() {
   const char* token_a = std::getenv("LIVEKIT_TOKEN_A");
   if (token_a == nullptr || std::string(token_a).empty()) {
@@ -164,7 +207,7 @@ inline void waitForParticipantVisibility(const std::vector<std::unique_ptr<Room>
     if (!room || room->localParticipant().expired()) {
       throw std::runtime_error("Test room is missing a local participant after connect");
     }
-    participant_identities.push_back(room->localParticipant().lock()->identity());
+    participant_identities.push_back(lockLocalParticipant(room.get())->identity());
   }
 
   auto start = std::chrono::steady_clock::now();

src/tests/common/test_common.h

@@ -113,8 +113,13 @@ std::string describeDataTrackError(const Error& error) {
   return "code=" + std::to_string(static_cast<std::uint32_t>(error.code)) + " message=" + error.message;
 }
 
-std::shared_ptr<LocalDataTrack> requirePublishedTrack(LocalParticipant* participant, const std::string& name) {
-  auto result = participant->publishDataTrack(name);
+std::shared_ptr<LocalDataTrack> requirePublishedTrack(const std::weak_ptr<LocalParticipant>& participant,
+                                                      const std::string& name) {
+  auto locked = participant.lock();
+  if (!locked) {
+    throw std::runtime_error("Local participant handle is expired");
+  }
+  auto result = locked->publishDataTrack(name);
   if (!result) {
     throw std::runtime_error("Failed to publish data track: " + describeDataTrackError(result.error()));
   }
@@ -216,7 +221,7 @@ void runEncryptedDataTrackRoundTrip(KeyDerivationFunction key_derivation_functio
   EXPECT_EQ(publisher_room->e2eeManager().lock()->keyProvider()->exportSharedKey(), e2eeSharedKey());
   EXPECT_EQ(subscriber_room->e2eeManager().lock()->keyProvider()->exportSharedKey(), e2eeSharedKey());
 
-  auto publish_result = publisher_room->localParticipant().lock()->publishDataTrack(track_name);
+  auto publish_result = lockLocalParticipant(*publisher_room)->publishDataTrack(track_name);
   if (!publish_result) {
     FAIL() << describeDataTrackError(publish_result.error());
   }
@@ -307,9 +312,9 @@ TEST_P(DataTrackTransportTest, PublishesAndReceivesFramesEndToEnd) {
 
   auto rooms = testRooms(room_configs);
   auto& publisher_room = rooms[0];
-  const auto publisher_identity = publisher_room->localParticipant().lock()->identity();
+  const auto publisher_identity = lockLocalParticipant(*publisher_room)->identity();
 
-  auto local_track = requirePublishedTrack(publisher_room->localParticipant().lock().get(), track_name);
+  auto local_track = requirePublishedTrack(publisher_room->localParticipant(), track_name);
   ASSERT_TRUE(local_track->isPublished());
   EXPECT_FALSE(local_track->info().uses_e2ee);
   EXPECT_EQ(local_track->info().name, track_name);
@@ -372,7 +377,7 @@ TEST_F(DataTrackE2ETest, UnpublishUpdatesPublishedStateEndToEnd) {
   auto rooms = testRooms(room_configs);
   auto& publisher_room = rooms[0];
 
-  auto publish_result = publisher_room->localParticipant().lock()->publishDataTrack(track_name);
+  auto publish_result = lockLocalParticipant(*publisher_room)->publishDataTrack(track_name);
   if (!publish_result) {
     FAIL() << describeDataTrackError(publish_result.error());
   }
@@ -401,7 +406,7 @@ TEST_F(DataTrackE2ETest, SubscribeAfterUnpublishReportsTerminalError) {
   auto rooms = testRooms(room_configs);
   auto& publisher_room = rooms[0];
 
-  auto local_track = requirePublishedTrack(publisher_room->localParticipant().lock().get(), track_name);
+  auto local_track = requirePublishedTrack(publisher_room->localParticipant(), track_name);
   ASSERT_TRUE(local_track->isPublished());
 
   auto remote_track = subscriber_delegate.waitForTrack(kTrackWaitTimeout);
@@ -455,7 +460,7 @@ TEST_F(DataTrackE2ETest, PublishManyTracks) {
   const auto start = std::chrono::steady_clock::now();
   for (int index = 0; index < kPublishManyTrackCount; ++index) {
     const auto track_name = "track_" + std::to_string(index);
-    auto publish_result = room->localParticipant().lock()->publishDataTrack(track_name);
+    auto publish_result = lockLocalParticipant(*room)->publishDataTrack(track_name);
     if (!publish_result) {
       FAIL() << "Failed to publish track " << track_name << ": " << describeDataTrackError(publish_result.error());
     }
@@ -496,14 +501,14 @@ TEST_F(DataTrackE2ETest, PublishDuplicateName) {
   auto rooms = testRooms(1);
   auto& room = rooms[0];
 
-  auto first_track_result = room->localParticipant().lock()->publishDataTrack("first");
+  auto first_track_result = lockLocalParticipant(*room)->publishDataTrack("first");
   if (!first_track_result) {
     FAIL() << describeDataTrackError(first_track_result.error());
   }
   auto first_track = first_track_result.value();
   ASSERT_TRUE(first_track->isPublished());
 
-  auto duplicate_result = room->localParticipant().lock()->publishDataTrack("first");
+  auto duplicate_result = lockLocalParticipant(*room)->publishDataTrack("first");
   ASSERT_FALSE(duplicate_result) << "Expected duplicate data-track name to be rejected";
   EXPECT_EQ(duplicate_result.error().code, PublishDataTrackErrorCode::DUPLICATE_NAME);
   EXPECT_FALSE(duplicate_result.error().message.empty());
@@ -525,7 +530,7 @@ TEST_F(DataTrackE2ETest, CanResubscribeToRemoteDataTrack) {
   std::exception_ptr publish_error;
   std::thread publisher([&]() {
     try {
-      auto track = requirePublishedTrack(publisher_room->localParticipant().lock().get(), track_name);
+      auto track = requirePublishedTrack(publisher_room->localParticipant(), track_name);
       if (!track->isPublished()) {
         throw std::runtime_error("Publisher failed to publish data track");
       }
@@ -582,7 +587,7 @@ TEST_F(DataTrackE2ETest, FfiClientSubscribeDataTrackReturnsSyncResult) {
 
   for (std::size_t idx = 0; idx < kTopicCount; ++idx) {
     const auto track_name = "test_" + std::to_string(idx);
-    auto publish_result = publisher_room->localParticipant().lock()->publishDataTrack(track_name);
+    auto publish_result = lockLocalParticipant(*publisher_room)->publishDataTrack(track_name);
     if (!publish_result) {
       FAIL() << "Failed to publish " << track_name << ": " << describeDataTrackError(publish_result.error());
     }
@@ -644,7 +649,7 @@ TEST_F(DataTrackE2ETest, PreservesUserTimestampEndToEnd) {
   auto rooms = testRooms(room_configs);
   auto& publisher_room = rooms[0];
 
-  auto publish_result = publisher_room->localParticipant().lock()->publishDataTrack(track_name);
+  auto publish_result = lockLocalParticipant(*publisher_room)->publishDataTrack(track_name);
   if (!publish_result) {
     FAIL() << describeDataTrackError(publish_result.error());
   }
@@ -735,7 +740,7 @@ TEST_F(DataTrackE2ETest, PreservesUserTimestampOnEncryptedDataTrack) {
   publisher_room->e2eeManager().lock()->setEnabled(true);
   subscriber_room->e2eeManager().lock()->setEnabled(true);
 
-  auto publish_result = publisher_room->localParticipant().lock()->publishDataTrack(track_name);
+  auto publish_result = lockLocalParticipant(*publisher_room)->publishDataTrack(track_name);
   if (!publish_result) {
     FAIL() << describeDataTrackError(publish_result.error());
   }

src/tests/integration/test_data_track.cpp

@@ -366,10 +366,10 @@ TEST_P(LateJoinTrackPublicationIntegrationTest, ConsumerReceivesAlreadyPublished
   ASSERT_TRUE(publisher_room.connect(config_.url, config_.token_a, options)) << "Publisher failed to connect";
   ASSERT_FALSE(publisher_room.localParticipant().expired());
 
-  const std::string publisher_identity = publisher_room.localParticipant().lock()->identity();
+  const std::string publisher_identity = lockLocalParticipant(publisher_room)->identity();
   ASSERT_FALSE(publisher_identity.empty());
 
-  PublishedTrackGuard published_tracks(publisher_room.localParticipant().lock().get());
+  PublishedTrackGuard published_tracks(lockLocalParticipant(publisher_room).get());
   MediaLoopGuard media_loops;
   std::vector<ExpectedPublication> expected_media;
 
@@ -380,7 +380,7 @@ TEST_P(LateJoinTrackPublicationIntegrationTest, ConsumerReceivesAlreadyPublished
     TrackPublishOptions publish_options;
     publish_options.source = TrackSource::SOURCE_MICROPHONE;
 
-    ASSERT_NO_THROW(publisher_room.localParticipant().lock()->publishTrack(track, publish_options));
+    ASSERT_NO_THROW(lockLocalParticipant(publisher_room)->publishTrack(track, publish_options));
     ASSERT_NE(track->publication(), nullptr) << "Audio track was not locally published";
 
     published_tracks.addMediaTrack(track, track->publication()->sid());
@@ -470,10 +470,10 @@ TEST_P(LateJoinTrackPublicationIntegrationTest, ConsumerReceivesAlreadyPublished
   ASSERT_TRUE(publisher_room.connect(config_.url, config_.token_a, options)) << "Publisher failed to connect";
   ASSERT_FALSE(publisher_room.localParticipant().expired());
 
-  const std::string publisher_identity = publisher_room.localParticipant().lock()->identity();
+  const std::string publisher_identity = lockLocalParticipant(publisher_room)->identity();
   ASSERT_FALSE(publisher_identity.empty());
 
-  PublishedTrackGuard published_tracks(publisher_room.localParticipant().lock().get());
+  PublishedTrackGuard published_tracks(lockLocalParticipant(publisher_room).get());
   MediaLoopGuard media_loops;
   std::vector<ExpectedPublication> expected_media;
 
@@ -485,7 +485,7 @@ TEST_P(LateJoinTrackPublicationIntegrationTest, ConsumerReceivesAlreadyPublished
     publish_options.source = TrackSource::SOURCE_CAMERA;
     publish_options.simulcast = false;
 
-    ASSERT_NO_THROW(publisher_room.localParticipant().lock()->publishTrack(track, publish_options));
+    ASSERT_NO_THROW(lockLocalParticipant(publisher_room)->publishTrack(track, publish_options));
     ASSERT_NE(track->publication(), nullptr) << "Video track was not locally published";
 
     published_tracks.addMediaTrack(track, track->publication()->sid());
@@ -575,15 +575,15 @@ TEST_P(LateJoinTrackPublicationIntegrationTest, ConsumerReceivesAlreadyPublished
   ASSERT_TRUE(publisher_room.connect(config_.url, config_.token_a, options)) << "Publisher failed to connect";
   ASSERT_FALSE(publisher_room.localParticipant().expired());
 
-  const std::string publisher_identity = publisher_room.localParticipant().lock()->identity();
+  const std::string publisher_identity = lockLocalParticipant(publisher_room)->identity();
   ASSERT_FALSE(publisher_identity.empty());
 
-  PublishedTrackGuard published_tracks(publisher_room.localParticipant().lock().get());
+  PublishedTrackGuard published_tracks(lockLocalParticipant(publisher_room).get());
   std::set<std::string> expected_data;
 
   for (int i = 0; i < kDataTrackCount; ++i) {
     const std::string track_name = makeTrackName("late-join-data", i);
-    auto publish_result = publisher_room.localParticipant().lock()->publishDataTrack(track_name);
+    auto publish_result = lockLocalParticipant(publisher_room)->publishDataTrack(track_name);
     ASSERT_TRUE(publish_result) << "Failed to publish data track " << track_name << ": "
                                 << publish_result.error().message;
 

src/tests/integration/test_late_join_track_publication.cpp

@@ -101,8 +101,7 @@ void MediaMultiStreamIntegrationTest::runPublishTwoVideoAndTwoAudioTracks(bool s
   auto sender_room = std::make_unique<Room>();
   ASSERT_TRUE(sender_room->connect(config_.url, config_.token_a, options)) << "Sender failed to connect";
 
-  const std::string receiver_identity = receiver_room->localParticipant().lock()->identity();
-  const std::string sender_identity = sender_room->localParticipant().lock()->identity();
+  const std::string sender_identity = lockLocalParticipant(*sender_room)->identity();
 
   constexpr int kVideoTrackCount = 10;
   constexpr int kAudioTrackCount = 10;
@@ -126,7 +125,7 @@ void MediaMultiStreamIntegrationTest::runPublishTwoVideoAndTwoAudioTracks(bool s
     auto track = LocalVideoTrack::createLocalVideoTrack(name, source);
     TrackPublishOptions opts;
     opts.source = (i % 2 == 0) ? TrackSource::SOURCE_CAMERA : TrackSource::SOURCE_SCREENSHARE;
-    sender_room->localParticipant().lock()->publishTrack(track, opts);
+    lockLocalParticipant(*sender_room)->publishTrack(track, opts);
     std::cerr << "[MediaMultiStream] published video " << name << " sid=" << track->sid() << std::endl;
     video_sources.push_back(source);
     video_tracks.push_back(track);
@@ -139,7 +138,7 @@ void MediaMultiStreamIntegrationTest::runPublishTwoVideoAndTwoAudioTracks(bool s
     auto track = LocalAudioTrack::createLocalAudioTrack(name, source);
     TrackPublishOptions opts;
     opts.source = (i % 2 == 0) ? TrackSource::SOURCE_MICROPHONE : TrackSource::SOURCE_SCREENSHARE_AUDIO;
-    sender_room->localParticipant().lock()->publishTrack(track, opts);
+    lockLocalParticipant(*sender_room)->publishTrack(track, opts);
     std::cerr << "[MediaMultiStream] published audio " << name << " sid=" << track->sid() << std::endl;
     audio_sources.push_back(source);
     audio_tracks.push_back(track);
@@ -210,12 +209,12 @@ void MediaMultiStreamIntegrationTest::runPublishTwoVideoAndTwoAudioTracks(bool s
 
   for (const auto& track : video_tracks) {
     if (track->publication()) {
-      sender_room->localParticipant().lock()->unpublishTrack(track->publication()->sid());
+      lockLocalParticipant(*sender_room)->unpublishTrack(track->publication()->sid());
     }
   }
   for (const auto& track : audio_tracks) {
     if (track->publication()) {
-      sender_room->localParticipant().lock()->unpublishTrack(track->publication()->sid());
+      lockLocalParticipant(*sender_room)->unpublishTrack(track->publication()->sid());
     }
   }
 }

src/tests/integration/test_media_multistream.cpp

@@ -99,7 +99,7 @@ TEST_F(RoomLifecycleTest, ParticipantHandlesExpireOnRoomDestruction) {
   ASSERT_TRUE(peer->connect(config_.url, config_.token_b, options)) << "Peer failed to connect";
 
   ASSERT_FALSE(peer->localParticipant().expired());
-  const std::string peer_identity = peer->localParticipant().lock()->identity();
+  const std::string peer_identity = lockLocalParticipant(*peer)->identity();
   ASSERT_TRUE(waitForParticipant(room.get(), peer_identity, 10s)) << "Peer not visible to room";
 
   // 2. Store the local participant handle. Keep the weak_ptr itself - locking

src/tests/integration/test_room.cpp

@@ -91,7 +91,7 @@ void expectFailedConnectDoesNotDuplicateParticipantCallbacks(const TestConfig& c
   Room peer_room;
   ASSERT_TRUE(peer_room.connect(config.url, config.token_b, options)) << "Peer failed to connect";
   ASSERT_FALSE(peer_room.localParticipant().expired());
-  const std::string peer_identity = peer_room.localParticipant().lock()->identity();
+  const std::string peer_identity = lockLocalParticipant(peer_room)->identity();
   ASSERT_FALSE(peer_identity.empty());
 
   expectSingleParticipantConnectedCallback(counter, peer_identity);
@@ -137,7 +137,7 @@ TEST_F(RoomListenerCleanupIntegrationTest, AlreadyConnectedConnectDoesNotReplace
   Room peer_room;
   ASSERT_TRUE(peer_room.connect(config_.url, config_.token_b, options)) << "Peer failed to connect";
   ASSERT_FALSE(peer_room.localParticipant().expired());
-  const std::string peer_identity = peer_room.localParticipant().lock()->identity();
+  const std::string peer_identity = lockLocalParticipant(peer_room)->identity();
   ASSERT_FALSE(peer_identity.empty());
 
   expectSingleParticipantConnectedCallback(counter, peer_identity);