From 6190b97e517327f71ff74361168335348d742d1e Mon Sep 17 00:00:00 2001 From: Chris Beard Date: Mon, 7 Oct 2024 13:01:59 -0400 Subject: [PATCH] Docs[BMQ] bde -> doxygen conversion fixes (#443) * Doc[BMQT] minor bde -> doxygen docs * Doc[BMQA] minor bde -> doxygen docs * Doc[BMQA] re-wrap data member comments * Doc[BMQT] re-wrap data member comments * Apply suggestions from code review --------- Signed-off-by: Christopher Beard Signed-off-by: Chris Beard Co-authored-by: Evgeny Malygin <678098@protonmail.com> --- src/groups/bmq/bmqa/bmqa_closequeuestatus.h | 11 +- .../bmq/bmqa/bmqa_configurequeuestatus.h | 11 +- src/groups/bmq/bmqa/bmqa_message.h | 24 ++- .../bmq/bmqa/bmqa_messageeventbuilder.h | 15 +- src/groups/bmq/bmqa/bmqa_messageiterator.h | 18 +- src/groups/bmq/bmqa/bmqa_messageproperties.h | 40 ++--- src/groups/bmq/bmqa/bmqa_mocksession.h | 155 +++++++++--------- src/groups/bmq/bmqa/bmqa_openqueuestatus.h | 17 +- src/groups/bmq/bmqa/bmqa_session.h | 14 +- src/groups/bmq/bmqt/bmqt_correlationid.h | 8 +- src/groups/bmq/bmqt/bmqt_messageguid.h | 11 +- src/groups/bmq/bmqt/bmqt_queueoptions.h | 17 +- src/groups/bmq/bmqt/bmqt_sessionoptions.h | 44 ++--- src/groups/bmq/bmqt/bmqt_subscription.h | 46 +++--- src/groups/bmq/bmqt/bmqt_uri.h | 30 ++-- 15 files changed, 219 insertions(+), 242 deletions(-) diff --git a/src/groups/bmq/bmqa/bmqa_closequeuestatus.h b/src/groups/bmq/bmqa/bmqa_closequeuestatus.h index dad7cbe8a..ed4f4f396 100644 --- a/src/groups/bmq/bmqa/bmqa_closequeuestatus.h +++ b/src/groups/bmq/bmqa/bmqa_closequeuestatus.h @@ -62,18 +62,15 @@ namespace bmqa { class CloseQueueStatus { private: // DATA + + /// QueueId associated with the open queue operation QueueId d_queueId; - // queueId associated with the open - // queue operation + /// Result code of the operation (success, failure) bmqt::CloseQueueResult::Enum d_result; - // Result code of the operation - // (success, failure) + /// Optional string with a human readable description of the error, if any bsl::string d_errorDescription; - // Optional string with a human - // readable description of the error, - // if any public: // TRAITS diff --git a/src/groups/bmq/bmqa/bmqa_configurequeuestatus.h b/src/groups/bmq/bmqa/bmqa_configurequeuestatus.h index f236fe884..e00db146d 100644 --- a/src/groups/bmq/bmqa/bmqa_configurequeuestatus.h +++ b/src/groups/bmq/bmqa/bmqa_configurequeuestatus.h @@ -61,18 +61,15 @@ namespace bmqa { class ConfigureQueueStatus { private: // DATA + + /// QueueId associated with the open queue operation QueueId d_queueId; - // queueId associated with the open - // queue operation + /// Status code of the operation (success, failure) bmqt::ConfigureQueueResult::Enum d_result; - // Status code of the operation - // (success, failure) + /// Optional string with a human readable description of the error, if any bsl::string d_errorDescription; - // Optional string with a human - // readable description of the error, - // if any public: // TRAITS diff --git a/src/groups/bmq/bmqa/bmqa_message.h b/src/groups/bmq/bmqa/bmqa_message.h index c48718132..42481b1f5 100644 --- a/src/groups/bmq/bmqa/bmqa_message.h +++ b/src/groups/bmq/bmqa/bmqa_message.h @@ -101,30 +101,25 @@ class MessageProperties; /// `bmqa::MessageIterator.nextMessage()`. struct MessageImpl { // PUBLIC DATA + + /// Pointer to the Event this message is associated with bmqimp::Event* d_event_p; - // Pointer to the Event this message is - // associated with + /// May point to a bmqimp::Event (in case this Message is a clone) bsl::shared_ptr d_clonedEvent_sp; - // May point to a bmqimp::Event (in case - // this Message is a clone) + /// QueueId this message is associated with bmqa::QueueId d_queueId; - // QueueId this message is associated - // with + /// CorrelationId this message is associated with bmqt::CorrelationId d_correlationId; - // CorrelationId this message is - // associated with + /// SubscriptionHandle this message is associated with bmqt::SubscriptionHandle d_subscriptionHandle; - // SubscriptionHandle this message is - // associated with #ifdef BMQ_ENABLE_MSG_GROUPID + /// Optional GroupId this message is associated with bsl::string d_groupId; - // Optional Group Id this message is - // associated with #endif }; @@ -136,11 +131,12 @@ struct MessageImpl { class MessageConfirmationCookie { private: // DATA + + /// QueueID associated to this cookie bmqa::QueueId d_queueId; - // QueueID associated to this cookie + /// GUID associated to this cookie bmqt::MessageGUID d_guid; - // GUID associated to this cookie public: // CREATORS diff --git a/src/groups/bmq/bmqa/bmqa_messageeventbuilder.h b/src/groups/bmq/bmqa/bmqa_messageeventbuilder.h index c9cc54073..57c85aa41 100644 --- a/src/groups/bmq/bmqa/bmqa_messageeventbuilder.h +++ b/src/groups/bmq/bmqa/bmqa_messageeventbuilder.h @@ -284,30 +284,31 @@ namespace bmqa { /// to expose them publicly). struct MessageEventBuilderImpl { // PUBLIC DATA - MessageEvent d_msgEvent; // This is needed so that 'getMessageEvent()' can - // return a const ref. - Message d_msg; // This is needed so that 'startMessage()' can - // return a ref. + /// This is needed so that `getMessageEvent()` can return a const ref. + MessageEvent d_msgEvent; + + /// This is needed so that `startMessage()` can return a ref. + Message d_msg; - bsl::shared_ptr d_guidGenerator_sp; // GUID generator object. + bsl::shared_ptr d_guidGenerator_sp; - int d_messageCountFinal; // The final number of messages in the current 'd_msgEvent' cached on // switching this MessageEvent from WRITE to READ mode. // This cached value exists because we are not able to access the // underlying PutEventBuilder once downgraded to READ. // CONTRACT: the stored value is correct every moment when in READ mode, // and the value is not guaranteed to be correct when in WRITE mode. + int d_messageCountFinal; - int d_messageEventSizeFinal; // The final message event size of the current 'd_msgEvent' cached on // switching this MessageEvent from WRITE to READ mode. // This cached value exists because we are not able to access the // underlying PutEventBuilder once downgraded to READ. // CONTRACT: the stored value is correct every moment when in READ mode, // and the value is not guaranteed to be correct when in WRITE mode. + int d_messageEventSizeFinal; }; // ========================= diff --git a/src/groups/bmq/bmqa/bmqa_messageiterator.h b/src/groups/bmq/bmqa/bmqa_messageiterator.h index 111322601..2c8c7f940 100644 --- a/src/groups/bmq/bmqa/bmqa_messageiterator.h +++ b/src/groups/bmq/bmqa/bmqa_messageiterator.h @@ -64,18 +64,18 @@ namespace bmqa { /// without publicly exposing private members. struct MessageIteratorImpl { // PUBLIC DATA - bmqimp::Event* d_event_p; // Raw pointer to the event - bmqa::Message d_message; // A 'Message', representing a view to the - // current message pointing at by this iterator. - // This is so that 'message' can return a 'const - // Message&' to clearly indicate the lifetime of - // the Message, and so that we only create one - // such object per MessageIterator. + /// Raw pointer to the event + bmqimp::Event* d_event_p; + /// A `Message`, representing a view to the current message pointing at by + /// this iterator. This is so that `message` can return a 'const Message&' + /// to clearly indicate the lifetime of the Message, and so that we only + /// create one such object per MessageIterator. + bmqa::Message d_message; + + /// Position of `d_message` in the underlying message event. int d_messageIndex; - // Position of 'd_message' in the underlying - // message event. }; // ===================== diff --git a/src/groups/bmq/bmqa/bmqa_messageproperties.h b/src/groups/bmq/bmqa/bmqa_messageproperties.h index e61c929dc..71571c17b 100644 --- a/src/groups/bmq/bmqa/bmqa_messageproperties.h +++ b/src/groups/bmq/bmqa/bmqa_messageproperties.h @@ -96,9 +96,9 @@ class MessageProperties { private: // PRIVATE CONSTANTS - // Constant representing the maximum size of a - // `bmqp::MessageProperties` object, so that the below AlignedBuffer - // is big enough. + /// Constant representing the maximum size of a + /// `bmqp::MessageProperties` object, so that the below AlignedBuffer + /// is big enough. static const int k_MAX_SIZEOF_BMQP_MESSAGEPROPERTIES = 184; // PRIVATE TYPES @@ -107,18 +107,15 @@ class MessageProperties { private: // DATA + + /// Pointer to the implementation object in `d_buffer`, providing a + /// shortcut type safe cast to that object. This variable *must* *be* the + /// first member of this class, as other components in bmqa package may + /// reinterpret_cast to that variable. mutable bmqp::MessageProperties* d_impl_p; - // Pointer to the implementation object - // in 'd_buffer', providing a shortcut - // type safe cast to that object. This - // variable *must* *be* the first - // member of this class, as other - // components in bmqa package may - // reinterpret_cast to that variable. + /// Buffer containing the implementation object, maximally aligned. ImplBuffer d_buffer; - // Buffer containing the implementation - // object, maximally aligned. bslma::Allocator* d_allocator_p; @@ -128,21 +125,20 @@ class MessageProperties { /// Maximum number of properties that can appear in a `bmqa::Message`. static const int k_MAX_NUM_PROPERTIES = 255; + /// Maximum length of all the properties (including their names, values + /// and the wire protocol overhead). Note that this value is just under + /// 64 MB. static const int k_MAX_PROPERTIES_AREA_LENGTH = (64 * 1024 * 1024) - 8; - // Maximum length of all the properties (including their names, values - // and the wire protocol overhead). Note that this value is just under - // 64 MB. /// Maximum length of a property name. static const int k_MAX_PROPERTY_NAME_LENGTH = 4095; - static const int k_MAX_PROPERTY_VALUE_LENGTH = - 67104745; // ~64 MB - // Maximum length of a property value. Note that this value - // is just under 64 MB. Also note that this value is - // calculated assuming that there is only one property and - // property's name has maximum allowable length, and also - // takes into consideration the protocol overhead. + /// ~64 MB + /// Maximum length of a property value. Note that this value is just under + /// 64 MB. Also note that this value is calculated assuming that there is + /// only one property and property's name has maximum allowable length, and + /// also takes into consideration the protocol overhead. + static const int k_MAX_PROPERTY_VALUE_LENGTH = 67104745; public: // TRAITS diff --git a/src/groups/bmq/bmqa/bmqa_mocksession.h b/src/groups/bmq/bmqa/bmqa_mocksession.h index ca11b53d4..d3a8dd668 100644 --- a/src/groups/bmq/bmqa/bmqa_mocksession.h +++ b/src/groups/bmq/bmqa/bmqa_mocksession.h @@ -607,13 +607,14 @@ class ConfirmEventBuilder; struct MockSessionUtil { private: // PRIVATE TYPES + + /// Event impl shared pointer to access + /// the pimpl of `bmqa::Event`. typedef bsl::shared_ptr EventImplSp; - // Event impl shared pointer to access - // the pimpl of 'bmqa::Event'. + /// Queue impl shared pointer to access + /// the pimpl of `bmqa::QueueId`. typedef bsl::shared_ptr QueueImplSp; - // Queue impl shared pointer to access - // the pimpl of 'bmqa::QueueId'. public: // PUBLIC TYPES @@ -621,16 +622,18 @@ struct MockSessionUtil { /// Struct representing parameters for an ack message. struct AckParams { // PUBLIC DATA - bmqt::AckResult::Enum d_status; // Status code + /// Status code + bmqt::AckResult::Enum d_status; + + /// CorrelationId bmqt::CorrelationId d_correlationId; - // Correlation id - bmqt::MessageGUID d_guid; // Message GUID of confirmed message + /// Message GUID of confirmed message + bmqt::MessageGUID d_guid; + /// QueueId for message being referred to QueueId d_queueId; - // Queue id for message being referred - // to // CREATORS @@ -647,14 +650,18 @@ struct MockSessionUtil { /// Struct representing parameters for a push message. struct PushMessageParams { // PUBLIC DATA - bdlbb::Blob d_payload; // Payload of message - QueueId d_queueId; // Queue Id for this message + /// Payload of message + bdlbb::Blob d_payload; - bmqt::MessageGUID d_guid; // GUID for message + /// QueueId for this message + QueueId d_queueId; - MessageProperties d_properties; // Optionally specified properties for - // message + /// GUID for message + bmqt::MessageGUID d_guid; + + /// Optionally specified properties for message + MessageProperties d_properties; // CREATORS @@ -784,10 +791,10 @@ class MockSession : public AbstractSession { private: // CONSTANTS - // Constant representing the maximum size of a `mwcc::TwoKeyHashMap` - // object, so that the below AlignedBuffer is big enough. No `mwc` - // headers can be included in `bmq` public headers, to prevent build - // time dependency. + /// Constant representing the maximum size of a `mwcc::TwoKeyHashMap` + /// object, so that the below AlignedBuffer is big enough. No `mwc` + /// headers can be included in `bmq` public headers, to prevent build + /// time dependency. static const int k_MAX_SIZEOF_MWCC_TWOKEYHASHMAP = 256; // PRIVATE TYPES @@ -815,25 +822,26 @@ class MockSession : public AbstractSession { /// operation executed with a user-specified callback struct Job { // PUBLIC DATA + + /// Signature of a `void` callback method CallbackFn d_callback; - // Signature of a 'void' callback method + /// Queue associated with this job QueueImplSp d_queue; - // Queue associated with this job + /// Type of queue event associated with this job (OPEN, CONFIGURE, or + /// CLOSE) bmqt::SessionEventType::Enum d_type; - // Type of queue event associated with - // this job (OPEN,CONFIGURE, or CLOSE) + /// Status of the queue operation int d_status; - // Status of the queue operation }; typedef bdlb::Variant EventOrJob; + /// Enumeration for the methods in the `MockSession` protocol. Each + /// enum value corresponds to a method. enum Method { - // Enumeration for the methods in the 'MockSession' protocol. Each - // enum value corresponds to a method. e_START, e_START_ASYNC, e_STOP, @@ -859,78 +867,71 @@ class MockSession : public AbstractSession { struct Call { // PUBLIC TYPES - typedef bsl::vector EventsAndJobs; // Vector of events + + /// Vector of events + typedef bsl::vector EventsAndJobs; // PUBLIC DATA + + /// Value to be returned on call int d_rc; - // Value to be returned on call + /// The type of method Method d_method; - // The type of method + /// Line number int d_line; - // Line number + /// File bsl::string d_file; - // File + /// Uri associated with this call bmqt::Uri d_uri; - // Uri associated with this call + /// Flags associated with this call bsls::Types::Uint64 d_flags; - // Flags associated with this call + /// QueueOptions associated with this call bmqt::QueueOptions d_queueOptions; - // QueueOptions associated with this - // call + /// Timeout interval associated with this call bsls::TimeInterval d_timeout; - // Timeout interval associated with - // this call + /// Callback to be invoked upon emission of an async openQueue (if + /// callback was provided) OpenQueueCallback d_openQueueCallback; - // Callback to be invoked upon emission - // of an async openQueue (if callback - // was provided) + /// Callback to be invoked upon emission of an async configureQueue (if + /// callback was provided) ConfigureQueueCallback d_configureQueueCallback; - // Callback to be invoked upon emission - // of an async configureQueue (if - // callback was provided) + /// Callback to be invoked upon emission of an async closeQueue (if + /// callback was provided) CloseQueueCallback d_closeQueueCallback; - // Callback to be invoked upon emission - // of an async closeQueue (if callback - // was provided) + /// The result of an open queue operation bmqa::OpenQueueStatus d_openQueueResult; - // The result of an open queue - // operation + /// The result of a configure queue operation bmqa::ConfigureQueueStatus d_configureQueueResult; - // The result of a configure queue - // operation + /// The result of a close queue operation bmqa::CloseQueueStatus d_closeQueueResult; - // The result of a close queue - // operation + /// Events to be emitted on this call EventsAndJobs d_emittedEvents; - // Events to be emitted on this call + /// Event to be returned on this call Event d_returnEvent; - // Event to be returned on this call + /// MessageEvent associated with this call MessageEvent d_messageEvent; - // MessageEvent associated with this - // call + /// MessageConfirmationCookie associated with this call MessageConfirmationCookie d_cookie; - // MessageConfirmationCookie associated - // with this call + /// Allocator bslma::Allocator* d_allocator_p; - // Allocator // TRAITS BSLMF_NESTED_TRAIT_DECLARATION(Call, bslma::UsesBslmaAllocator) @@ -1006,56 +1007,52 @@ class MockSession : public AbstractSession { typedef bsl::deque PostedEvents; // DATA + + /// Buffer factory bdlbb::PooledBlobBufferFactory d_blobBufferFactory; - // Buffer factory + /// Event handler (set only in asynchronous mode) bslma::ManagedPtr d_eventHandler_mp; - // Event handler (set only in - // asynchronous mode) + /// sequence of method calls that are expected mutable CallQueue d_calls; - // sequence of method calls that are - // expected + /// events waiting to be emitted mutable bsl::deque d_eventsAndJobs; - // events waiting to be emitted + /// GUIDS of unconfirmed messages bsl::unordered_set d_unconfirmedGUIDs; - // GUIDS of unconfirmed messages + /// Aligned buffer of two key hash map uri, corrid to queues TwoKeyHashMapBuffer d_twoKeyHashMapBuffer; - // Aligned buffer of two key hash map - // uri, corrid to queues + /// Currently installed failure callback that is invoked if methods are + /// called incorrectly or out of order. FailureCb d_failureCb; - // Currently installed failure callback - // that is invoked if methods are - // called incorrectly or out of order. + /// QueueId int d_lastQueueId; - // QueueId + /// Mock correlationId container CorrelationIdContainerSp d_corrIdContainer_sp; - // Mock correlationId container + /// Queue of posted events PostedEvents d_postedEvents; - // Queue of posted events + /// protects all public methods mutable bslmt::Mutex d_mutex; - // protects all public methods + /// Top level stat context for this mocked Session. mwcst::StatContext d_rootStatContext; - // Top level stat context for this - // mocked Session. + /// Stats for all queues StatImplSp d_queuesStats_sp; - // Stats for all queues + /// Session Options for current session bmqt::SessionOptions d_sessionOptions; - // Session Options for current session + /// Allocator bslma::Allocator* d_allocator_p; - // Allocator private: // PRIVATE CLASS METHODS diff --git a/src/groups/bmq/bmqa/bmqa_openqueuestatus.h b/src/groups/bmq/bmqa/bmqa_openqueuestatus.h index 70c8eeba5..7e658e468 100644 --- a/src/groups/bmq/bmqa/bmqa_openqueuestatus.h +++ b/src/groups/bmq/bmqa/bmqa_openqueuestatus.h @@ -62,18 +62,15 @@ namespace bmqa { class OpenQueueStatus { private: // DATA + + /// QueueId associated with the open queue operation QueueId d_queueId; - // queueId associated with the open - // queue operation + /// Result code of the operation (success, failure) bmqt::OpenQueueResult::Enum d_result; - // Result code of the operation - // (success, failure) + /// Optional string with a human readable description of the error, if any bsl::string d_errorDescription; - // Optional string with a human - // readable description of the error, - // if any public: // TRAITS @@ -81,9 +78,9 @@ class OpenQueueStatus { // TYPES - // Use of an `UnspecifiedBool` to prevent implicit conversions to - // integral values, and comparisons between different classes which - // have boolean operators. + /// Use of an `UnspecifiedBool` to prevent implicit conversions to + /// integral values, and comparisons between different classes which + /// have boolean operators. typedef bsls::UnspecifiedBool::BoolType BoolType; // CREATORS diff --git a/src/groups/bmq/bmqa/bmqa_session.h b/src/groups/bmq/bmqa/bmqa_session.h index 604edeec5..6e1423b1e 100644 --- a/src/groups/bmq/bmqa/bmqa_session.h +++ b/src/groups/bmq/bmqa/bmqa_session.h @@ -636,23 +636,21 @@ class SessionEventHandler { /// Care should be taken though since `Session` is a polymorphic class. struct SessionImpl { // PUBLIC DATA + + /// The allocator to use bslma::Allocator* d_allocator_p; - // The allocator to use + /// Session options as provided by the application. bmqt::SessionOptions d_sessionOptions; - // Session options as provided by - // the application. + /// Event handler, if any, to use for notifying application of events. bslma::ManagedPtr d_eventHandler_mp; - // Event handler, if any, to use - // for notifying application of - // events. + /// GUID generator object. bsl::shared_ptr d_guidGenerator_sp; - // GUID generator object. + /// The application object. bslma::ManagedPtr d_application_mp; - // The application object. private: // NOT IMPLEMENTED diff --git a/src/groups/bmq/bmqt/bmqt_correlationid.h b/src/groups/bmq/bmqt/bmqt_correlationid.h index 0b9f51034..39c3459f2 100644 --- a/src/groups/bmq/bmqt/bmqt_correlationid.h +++ b/src/groups/bmq/bmqt/bmqt_correlationid.h @@ -213,12 +213,12 @@ class CorrelationId { typedef bsls::Types::Uint64 AutoValue; // DATA + + /// The variant used to hold the value of a `CorrelationId`, that may + /// either be unset, hold a 64-bit integer, a raw pointer, a shared + /// pointer, or an `AutoValue`. bdlb::Variant4, AutoValue> d_variant; - // The variant used to hold the value of a - // 'CorrelationId', that may either be unset, - // hold a 64-bit integer, a raw pointer, a - // shared pointer, or an 'AutoValue'. // PRIVATE ACCESSORS diff --git a/src/groups/bmq/bmqt/bmqt_messageguid.h b/src/groups/bmq/bmqt/bmqt_messageguid.h index 2f83aab85..f7098f302 100644 --- a/src/groups/bmq/bmqt/bmqt_messageguid.h +++ b/src/groups/bmq/bmqt/bmqt_messageguid.h @@ -102,13 +102,15 @@ class MessageGUID { public: // TYPES + + /// Enum representing the size of a buffer needed to represent a GUID enum Enum { - // Enum representing the size of a buffer needed to represent a GUID - e_SIZE_BINARY = 16 // Binary format of the GUID + /// Binary format of the GUID + e_SIZE_BINARY = 16 , + /// Hexadecimal string representation of the GUID e_SIZE_HEX = 2 * e_SIZE_BINARY - // Hexadecimal string representation of the GUID }; // TRAITS @@ -118,8 +120,9 @@ class MessageGUID { private: // PRIVATE CONSTANTS + + /// Constant representing an unset GUID static const char k_UNSET_GUID[e_SIZE_BINARY]; - // Constant representing an unset GUID private: // IMPLEMENTATION NOTE: Some structs in bmqp::Protocol.h blindly diff --git a/src/groups/bmq/bmqt/bmqt_queueoptions.h b/src/groups/bmq/bmqt/bmqt_queueoptions.h index 4b7fd6440..7af98bb7b 100644 --- a/src/groups/bmq/bmqt/bmqt_queueoptions.h +++ b/src/groups/bmq/bmqt/bmqt_queueoptions.h @@ -66,13 +66,12 @@ namespace bmqt { class QueueOptions { public: // PUBLIC CONSTANTS + + /// Constant representing the minimum valid consumer priority static const int k_CONSUMER_PRIORITY_MIN; - // Constant representing the minimum - // valid consumer priority + /// Constant representing the maximum valid consumer priority static const int k_CONSUMER_PRIORITY_MAX; - // Constant representing the maximum - // valid consumer priority static const int k_DEFAULT_MAX_UNCONFIRMED_MESSAGES; static const int k_DEFAULT_MAX_UNCONFIRMED_BYTES; @@ -87,19 +86,17 @@ class QueueOptions { // DATA Subscription d_info; + /// Whether the queue suspends operation while the host is unhealthy. bsl::optional d_suspendsOnBadHostHealth; - // Whether the queue suspends operation - // while the host is unhealthy. Subscriptions d_subscriptions; + /// `true` if `d_subscriptions` had a value, `false` otherwise. Emulates + /// `bsl::optional` for `d_subscriptions`. bool d_hadSubscriptions; - // 'true' if 'd_subscriptions' had a value, 'false' - // otherwise. Emulates 'bsl::optional' for - // 'd_subscriptions'. + /// Allocator bslma::Allocator* d_allocator_p; - // Allocator public: // PUBLIC TYPES diff --git a/src/groups/bmq/bmqt/bmqt_sessionoptions.h b/src/groups/bmq/bmqt/bmqt_sessionoptions.h index 74920761d..e311ccd1a 100644 --- a/src/groups/bmq/bmqt/bmqt_sessionoptions.h +++ b/src/groups/bmq/bmqt/bmqt_sessionoptions.h @@ -161,45 +161,40 @@ namespace bmqt { class SessionOptions { public: // CONSTANTS + + /// Default URI of the `bmqbrkr` to connect to. static const char k_BROKER_DEFAULT_URI[]; - // Default URI of the 'bmqbrkr' to connect to. + /// Default port the `bmqbrkr` is listening to for client to connect. static const int k_BROKER_DEFAULT_PORT = 30114; - // Default port the 'bmqbrkr' is listening to for client - // to connect. + /// The default, and minimum recommended, value for queue operations (open, + /// configure, close). static const int k_QUEUE_OPERATION_DEFAULT_TIMEOUT = 5 * bdlt::TimeUnitRatio::k_SECONDS_PER_MINUTE; - // The default, and minimum recommended, value for queue - // operations (open, configure, close). private: // DATA + + /// URI of the broker to connect to (ex: `tcp://localhost:30114`). Default + /// is to connect to the local broker. bsl::string d_brokerUri; - // URI of the broker to connect to (ex: - // 'tcp://localhost:30114'). Default - // is to connect to the local broker. + /// If not empty, use this value for the processName in the identity + /// message (useful for scripted language bindings). bsl::string d_processNameOverride; - // If not empty, use this value for the - // processName in the identity message - // (useful for scripted language - // bindings). + /// Number of processing threads. Default is 1 thread. int d_numProcessingThreads; - // Number of processing threads. - // Default is 1 thread. + /// Size of the blobs buffer. int d_blobBufferSize; - // Size of the blobs buffer. + /// Write cache high watermark to use on the channel bsls::Types::Int64 d_channelHighWatermark; - // Write cache high watermark to use on - // the channel + /// Interval at which to dump stats to log file (0 to disable dump) bsls::TimeInterval d_statsDumpInterval; - // Interval at which to dump stats to - // log file (0 to disable dump) bsls::TimeInterval d_connectTimeout; @@ -209,20 +204,17 @@ class SessionOptions { bsls::TimeInterval d_configureQueueTimeout; + /// Timeout for operations of the corresponding type. bsls::TimeInterval d_closeQueueTimeout; - // Timeout for operations of the - // corresponding type. int d_eventQueueLowWatermark; + /// Parameters to configure the EventQueue. int d_eventQueueHighWatermark; - // Parameters to configure the - // EventQueue. + /// DEPRECATED: This parameter is no longer relevant and will be removed in + /// future release of libbmq. int d_eventQueueSize; - // DEPRECATED: This parameter is no - // longer relevant and will be removed - // in future release of libbmq. bsl::shared_ptr d_hostHealthMonitor_sp; diff --git a/src/groups/bmq/bmqt/bmqt_subscription.h b/src/groups/bmq/bmqt/bmqt_subscription.h index 80fef4db2..ccce47194 100644 --- a/src/groups/bmq/bmqt/bmqt_subscription.h +++ b/src/groups/bmq/bmqt/bmqt_subscription.h @@ -61,17 +61,18 @@ class SubscriptionHandle { friend class bmqa::MessageIterator; public: + /// Initial (invalid) value for `bmqt::SubscriptionHandle::d_id` static const unsigned int k_INVALID_HANDLE_ID = 0; - // Initial (invalid) value for 'bmqt::SubscriptionHandle::d_id' private: // PRIVATE DATA + + /// Internal, unique key unsigned int d_id; - // Internal, unique key + /// User-specified, not required to be unique bmqt::CorrelationId d_correlationId; - // User-specified, not required to be - // unique + private: // PRIVATE CLASS METHODS static unsigned int nextId(); @@ -122,18 +123,22 @@ class SubscriptionHandle { class SubscriptionExpression { public: // TYPES + + /// Enum representing criteria format enum Enum { - // Enum representing criteria format - e_NONE = 0 // EMPTY + /// EMPTY + e_NONE = 0 + , - e_VERSION_1 = 1 // Simple Evaluator + /// Simple Evaluator + e_VERSION_1 = 1 }; private: bsl::string d_expression; // e.g., "firmId == foo" - Enum d_version; // Required to support newer style - // of expressions in future + // Required to support newer style of expressions in future + Enum d_version; public: // CREATORS @@ -164,13 +169,12 @@ class SubscriptionExpression { class Subscription { public: // PUBLIC CONSTANTS + + /// Constant representing the minimum valid consumer priority static const int k_CONSUMER_PRIORITY_MIN; - // Constant representing the minimum - // valid consumer priority + /// Constant representing the maximum valid consumer priority static const int k_CONSUMER_PRIORITY_MAX; - // Constant representing the maximum - // valid consumer priority static const int k_DEFAULT_MAX_UNCONFIRMED_MESSAGES; static const int k_DEFAULT_MAX_UNCONFIRMED_BYTES; @@ -178,25 +182,23 @@ class Subscription { private: // PRIVATE DATA + + /// Maximum number of outstanding messages that can be sent by the broker + /// without being confirmed. bsl::optional d_maxUnconfirmedMessages; - // Maximum number of outstanding - // messages that can be sent by the - // broker without being confirmed. + /// Maximum accumulated bytes of all outstanding messages that can be sent + /// by the broker without being confirmed. bsl::optional d_maxUnconfirmedBytes; - // Maximum accumulated bytes of all - // outstanding messages that can be - // sent by the broker without being - // confirmed. + /// Priority of a consumer with respect to delivery of messages bsl::optional d_consumerPriority; - // Priority of a consumer with respect - // to delivery of messages SubscriptionExpression d_expression; public: // CREATORS + /// Create a new Subscription Subscription(); diff --git a/src/groups/bmq/bmqt/bmqt_uri.h b/src/groups/bmq/bmqt/bmqt_uri.h index 7f51c631e..50a45096e 100644 --- a/src/groups/bmq/bmqt/bmqt_uri.h +++ b/src/groups/bmq/bmqt/bmqt_uri.h @@ -174,27 +174,31 @@ class Uri { private: // DATA - bsl::string d_uri; // The full URI - bslstl::StringRef d_scheme; // URI scheme (must be "bmq"). + /// The full URI + bsl::string d_uri; - bslstl::StringRef d_authority; // URI authority (domain + optional - // tier) + /// URI scheme (must be "bmq"). + bslstl::StringRef d_scheme; - bslstl::StringRef d_domain; // URI domain + /// URI authority (domain + optional tier) + bslstl::StringRef d_authority; - bslstl::StringRef d_tier; // URI tier + /// URI domain + bslstl::StringRef d_domain; - bslstl::StringRef d_path; // URI path (i.e queue name). + /// URI tier + bslstl::StringRef d_tier; - bslstl::StringRef d_query_id; // Optional application id, part of the - // URI query if present. + /// URI path (i.e queue name). + bslstl::StringRef d_path; + /// Optional application id, part of the URI query if present. + bslstl::StringRef d_query_id; + + /// Flag indicating whether the URI parser was initialized (and whether + /// shutdown should be called on it at destruction) bool d_wasParserInitialized; - // Flag indicating whether the URI - // parser was initialized (and whether - // shutdown should be called on it at - // destruction) private: // PRIVATE MANIPULATORS