Make topics persistent between writer's close() and open() API calls.

rosbag2_compression/include/rosbag2_compression/sequential_compression_writer.hpp

@@ -72,33 +72,33 @@ class ROSBAG2_COMPRESSION_PUBLIC SequentialCompressionWriter
   ~SequentialCompressionWriter() override;
 
   /**
-   * Create a new topic in the underlying storage. Needs to be called for every topic used within
-   * a message which is passed to write(...).
-   *
+   * \brief Create a new topic in the underlying storage.
+   * \details Needs to be called for every topic used within a message which is passed
+   * to \ref write "write(...)".
+   * \note If writer is not open, this will just store the topic information locally and
+   * topics will be created on storage open.
    * \param topic_with_type name and type identifier of topic to be created
-   * \throws runtime_error if the Writer is not open.
    */
   void create_topic(const rosbag2_storage::TopicMetadata & topic_with_type) override;
 
   /**
-   * Create a new topic in the underlying storage. Needs to be called for every topic used within
-   * a message which is passed to write(...).
-   *
+   * \brief Create a new topic in the underlying storage.
+   * \details Needs to be called for every topic used within a message which is passed
+   * to \ref write "write(...)".
+   * \note If writer is not open, this will just store the topic information locally and
+   * topics will be created on storage open.
    * \param topic_with_type name and type identifier of topic to be created
-   * \param message_definition definition of topic_with_type.type
-   * \throws runtime_error if the Writer is not open.
+   * \param message_definition message definition content for this topic's type
    */
   void create_topic(
     const rosbag2_storage::TopicMetadata & topic_with_type,
     const rosbag2_storage::MessageDefinition & message_definition) override;
 
   /**
-   * Remove a new topic in the underlying storage.
-   * If creation of subscription fails remove the topic
-   * from the db (more of cleanup)
-   *
+   * \brief Removes a new topic in the underlying storage.
+   * \details Expected to be used if creation of subscription fails and cleanup is needed.
+   * \note If writer is not open, this will just remove the topic information locally.
    * \param topic_with_type name and type identifier of topic to be created
-   * \throws runtime_error if the Writer is not open.
    */
   void remove_topic(const rosbag2_storage::TopicMetadata & topic_with_type) override;
 
@@ -115,9 +115,9 @@ class ROSBAG2_COMPRESSION_PUBLIC SequentialCompressionWriter
   void write(std::shared_ptr<const rosbag2_storage::SerializedBagMessage> message) override;
 
   /**
-   * Opens a new bagfile and prepare it for writing messages. The bagfile must not exist.
-   * This must be called before any other function is used.
-   *
+   * \brief Opens a new bagfile and prepare it for writing messages. The bagfile must not exist.
+   * \details This must be called before any other function is used among \ref create_topic
+   * and \ref remove_topic.
    * \param storage_options Options to configure the storage
    * \param converter_options options to define in which format incoming messages are stored
    **/

rosbag2_cpp/include/rosbag2_cpp/writer.hpp

@@ -63,9 +63,9 @@ class ROSBAG2_CPP_PUBLIC Writer
   ~Writer();
 
   /**
-   * Opens a new bagfile and prepare it for writing messages. The bagfile must not exist.
-   * This must be called before any other function is used.
-   *
+   * \brief Opens a new bagfile and prepare it for writing messages. The bagfile must not exist.
+   * \details This must be called before any other function is used among \ref create_topic
+   * and \ref remove_topic.
    * \note This will open URI with the default storage options
    * * using default storage backend
    * * using no converter options, storing messages with the incoming serialization format
@@ -78,9 +78,9 @@ class ROSBAG2_CPP_PUBLIC Writer
   void open(const std::string & uri);
 
   /**
-   * Opens a new bagfile and prepare it for writing messages. The bagfile must not exist.
-   * This must be called before any other function is used.
-   *
+   * \brief Opens a new bagfile and prepare it for writing messages. The bagfile must not exist.
+   * \details This must be called before any other function is used among \ref create_topic
+   * and \ref remove_topic.
    * \param storage_options Options to configure the storage
    * \param converter_options options to define in which format incoming messages are stored
    **/
@@ -94,21 +94,23 @@ class ROSBAG2_CPP_PUBLIC Writer
   void close();
 
   /**
-   * Create a new topic in the underlying storage. Needs to be called for every topic used within
-   * a message which is passed to write(...).
-   *
+   * \brief Create a new topic in the underlying storage.
+   * \details Needs to be called for every topic used within a message which is passed
+   * to \ref write "write(...)".
+   * \note If writer is not open, this will just store the topic information locally and
+   * topics will be created on storage open.
    * \param topic_with_type name and type identifier of topic to be created
-   * \throws runtime_error if the Writer is not open.
    */
   void create_topic(const rosbag2_storage::TopicMetadata & topic_with_type);
 
   /**
-   * Create a new topic in the underlying storage. Needs to be called for every topic used within
-   * a message which is passed to write(...).
-   *
+   * \brief Create a new topic in the underlying storage.
+   * \details Needs to be called for every topic used within a message which is passed
+   * to \ref write "write(...)".
+   * \note If writer is not open, this will just store the topic information locally and
+   * topics will be created on storage open.
    * \param topic_with_type name and type identifier of topic to be created
    * \param message_definition message definition content for this topic's type
-   * \throws runtime_error if the Writer is not open.
    */
   void create_topic(
     const rosbag2_storage::TopicMetadata & topic_with_type,
@@ -126,12 +128,10 @@ class ROSBAG2_CPP_PUBLIC Writer
   void split_bagfile();
 
   /**
-   * Remove a new topic in the underlying storage.
-   * If creation of subscription fails remove the topic
-   * from the db (more of cleanup)
-   *
+   * \brief Removes a new topic in the underlying storage.
+   * \details Expected to be used if creation of subscription fails and cleanup is needed.
+   * \note If writer is not open, this will just remove the topic information locally.
    * \param topic_with_type name and type identifier of topic to be created
-   * \throws runtime_error if the Writer is not open.
    */
   void remove_topic(const rosbag2_storage::TopicMetadata & topic_with_type);
 

rosbag2_cpp/include/rosbag2_cpp/writers/sequential_writer.hpp

@@ -72,9 +72,9 @@ class ROSBAG2_CPP_PUBLIC SequentialWriter
   ~SequentialWriter() override;
 
   /**
-   * Opens a new bagfile and prepare it for writing messages. The bagfile must not exist.
-   * This must be called before any other function is used.
-   *
+   * \brief Opens a new bagfile and prepare it for writing messages. The bagfile must not exist.
+   * \details This must be called before any other function is used among \ref create_topic
+   * and \ref remove_topic.
    * \param storage_options Options to configure the storage
    * \param converter_options options to define in which format incoming messages are stored
    **/
@@ -85,33 +85,33 @@ class ROSBAG2_CPP_PUBLIC SequentialWriter
   void close() override;
 
   /**
-   * Create a new topic in the underlying storage. Needs to be called for every topic used within
-   * a message which is passed to write(...).
-   *
+   * \brief Create a new topic in the underlying storage.
+   * \details Needs to be called for every topic used within a message which is passed
+   * to \ref write "write(...)".
+   * \note If writer is not open, this will just store the topic information locally and
+   * topics will be created on storage open.
    * \param topic_with_type name and type identifier of topic to be created
-   * \throws runtime_error if the Writer is not open.
    */
   void create_topic(const rosbag2_storage::TopicMetadata & topic_with_type) override;
 
   /**
-   * Create a new topic in the underlying storage. Needs to be called for every topic used within
-   * a message which is passed to write(...).
-   *
+   * \brief Create a new topic in the underlying storage.
+   * \details Needs to be called for every topic used within a message which is passed
+   * to \ref write "write(...)".
+   * \note If writer is not open, this will just store the topic information locally and
+   * topics will be created on storage open.
    * \param topic_with_type name and type identifier of topic to be created
    * \param message_definition message definition content for this topic's type
-   * \throws runtime_error if the Writer is not open.
    */
   void create_topic(
     const rosbag2_storage::TopicMetadata & topic_with_type,
     const rosbag2_storage::MessageDefinition & message_definition) override;
 
   /**
-   * Remove a new topic in the underlying storage.
-   * If creation of subscription fails remove the topic
-   * from the db (more of cleanup)
-   *
+   * \brief Removes a new topic in the underlying storage.
+   * \details Expected to be used if creation of subscription fails and cleanup is needed.
+   * \note If writer is not open, this will just remove the topic information locally.
    * \param topic_with_type name and type identifier of topic to be created
-   * \throws runtime_error if the Writer is not open.
    */
   void remove_topic(const rosbag2_storage::TopicMetadata & topic_with_type) override;
 
@@ -171,11 +171,17 @@ class ROSBAG2_CPP_PUBLIC SequentialWriter
 
   rosbag2_storage::StorageOptions storage_options_;
 
-  // Used to track topic -> message count. If cache is present, it is updated by CacheConsumer
+  /// \brief Topic name to the TopicInformation map.
+  /// Used to keep topic list and track message counts. If cache is present, the message
+  /// counts updated by CacheConsumer.
+  /// \note The map is persisted across bagfile splits and writer close()->open() operations.
+  /// However, the message counts inside TopicInformation are reset to zero on close() and open().
+  /// \note topics_names_to_info_ needs to be protected with \sa topics_info_mutex_ only when we
+  /// are explicitly adding or deleting items (create_topic(..)/remove_topic(..)) and when we access
+  /// it from CacheConsumer callback i.e., write_messages(..). In all other cases like in write(..)
+  /// it is safe to access without topics_info_mutex_ losck as all external API calls are protected
+  /// with \sa writer_mutex_ on \sa rosbag2_cpp::Writer level.
   std::unordered_map<std::string, rosbag2_storage::TopicInformation> topics_names_to_info_;
-  // Note: topics_names_to_info_ needs to be protected with mutex only when we are explicitly
-  // adding or deleting items (create_topic(..)/remove_topic(..)) and when we access it from
-  // CacheConsumer callback i.e., write_messages(..)
   std::mutex topics_info_mutex_;
 
   LocalMessageDefinitionSource message_definitions_;