diff --git a/src/groups/mqb/mqba/README.dox b/src/groups/mqb/mqba/README.dox new file mode 100644 index 000000000..0a3237e17 --- /dev/null +++ b/src/groups/mqb/mqba/README.dox @@ -0,0 +1,6 @@ +/** +@dir mqba + +@brief The `MBQA` (BlazingMQ Broker) package provides the components + constituting the broker. +*/ diff --git a/src/groups/mqb/mqba/doc/mqba.txt b/src/groups/mqb/mqba/doc/mqba.txt deleted file mode 100644 index a8bea3ec0..000000000 --- a/src/groups/mqb/mqba/doc/mqba.txt +++ /dev/null @@ -1,48 +0,0 @@ - mqba.txt - -@PURPOSE: Provide broker components. - -@MNEMONIC: BlazingMQ Broker (mqba) - -@DESCRIPTION: This package provides the components constituting the broker. - - -/Hierarchical Synopsis -/--------------------- - The 'mqba' package currently has 7 components having 3 levels of physical - dependency. The list below shows the hierarchical ordering of the components. -.. - 3. mqba_application - - 2. mqba_domainmanager - mqba_sessionnegotiator - - 1. mqba_clientsession - mqba_configprovider - mqba_dispatcher - mqba_domainresolver - -.. - -/Component Synopsis -/------------------ -: 'mqba_application' -: Provide an Application class to control object lifetime/creation. -: -: 'mqba_clientsession' -: Provide a session for interaction with BlazingMQ broker clients. -: -: 'mqba_configprovider' -: Provide a mechanism to retrieve configuration information. -: -: 'mqba_dispatcher' -: Provide an event dispatcher at the core of BlazingMQ broker. -: -: 'mqba_domainmanager' -: Provide a manager for all queue domains. -: -: 'mqba_domainresolver' -: Provide a mechanism to resolve domain and their associated cluster. -: -: 'mqba_sessionnegotiator' -: Provide a negotiator for establishing sessions. diff --git a/src/groups/mqb/mqba/mqba_adminsession.h b/src/groups/mqb/mqba/mqba_adminsession.h index a05a127e5..fffd861ea 100644 --- a/src/groups/mqb/mqba/mqba_adminsession.h +++ b/src/groups/mqb/mqba/mqba_adminsession.h @@ -17,20 +17,17 @@ #ifndef INCLUDED_MQBA_ADMINSESSION #define INCLUDED_MQBA_ADMINSESSION -//@PURPOSE: Provide a session for interaction with BlazingMQ broker admin -// clients. -// -//@CLASSES: -// mqba::AdminSession : mechanism representing a session with an admin -// mqba::AdminSessionState: VST representing the state of a session -// -//@DESCRIPTION: This component provides a mechanism, 'mqba::AdminSession', that -// allows BlazingMQ broker to send and receive messages from an admin connected -// to the broker. 'mqba::AdminSessionState' is a value semantic type holding -// the state associated to an 'mqba::Session'. +/// @file mqba_adminsession.h +/// +/// @brief Provide a session for interaction with BlazingMQ broker admin +/// clients. +/// +/// This component provides a mechanism, @bbref{mqba::AdminSession}, that +/// allows BlazingMQ broker to send and receive messages from an admin +/// connected to the broker. @bbref{mqba::AdminSessionState} is a value +/// semantic type holding the state associated to an 'mqba::Session'. // MQB - #include #include #include @@ -85,21 +82,19 @@ struct AdminSessionState { public: // PUBLIC DATA + + /// Allocator to use. bslma::Allocator* d_allocator_p; - // Allocator to use. + /// Dispatcher client data associated to this session. mqbi::DispatcherClientData d_dispatcherClientData; - // Dispatcher client data associated to - // this session. + /// Pool of shared pointers to blobs to use. BlobSpPool* d_blobSpPool_p; - // Pool of shared pointers to blob to - // use. + /// Builder for schema messages. To be used only in client dispatcher + /// thread. bmqp::SchemaEventBuilder d_schemaEventBuilder; - // Builder for schema messages. To be - // used only in client dispatcher - // thread. private: // NOT IMPLEMENTED @@ -136,43 +131,36 @@ class AdminSession : public mqbnet::Session, public mqbi::DispatcherClient { private: // DATA + + /// This object is used to avoid executing a callback if the session has + /// been destroyed: this is *ONLY* to be used with the callbacks that will + /// be called from outside of the dispatcher's thread. bmqu::SharedResource d_self; - // This object is used to avoid - // executing a callback if the session - // has been destroyed: this is *ONLY* to - // be used with the callbacks that will - // be called from outside of the - // dispatcher's thread. + /// Show whether the session is running. bool d_running; - // Show whether the session is running. + /// Negotiation message received from the remote peer. bmqp_ctrlmsg::NegotiationMessage d_negotiationMessage; - // Negotiation message received from the - // remote peer. + /// Raw pointer to the right field in `d_negotiationMessage` (depending on + /// whether it's a `client` or a `broker`). bmqp_ctrlmsg::ClientIdentity* d_clientIdentity_p; - // Raw pointer to the right field in - // 'd_negotiationMessage' (depending - // whether it's a 'client' or a - // 'broker'). + /// Short identifier for this session. bsl::string d_description; - // Short identifier for this session. + /// Channel associated to this session. bsl::shared_ptr d_channel_sp; - // Channel associated to this session. + /// The state associated to this session. AdminSessionState d_state; - // The state associated to this session. + /// Pointer to the event scheduler to use (held, not owned). bdlmt::EventScheduler* d_scheduler_p; - // Pointer to the event scheduler to - // use (held, not owned) + /// The callback to invoke on received admin command. mqbnet::Session::AdminCommandEnqueueCb d_adminCb; - // The callback to invoke on received - // admin command. private: // NOT IMPLEMENTED diff --git a/src/groups/mqb/mqba/mqba_application.h b/src/groups/mqb/mqba/mqba_application.h index 2e490e015..f6d64bd6d 100644 --- a/src/groups/mqb/mqba/mqba_application.h +++ b/src/groups/mqb/mqba/mqba_application.h @@ -17,14 +17,13 @@ #ifndef INCLUDED_MQBA_APPLICATION #define INCLUDED_MQBA_APPLICATION -//@PURPOSE: Provide an Application class to control object lifetime/creation. -// -//@CLASSES: -// mqba::Application: BlazingMQ broker application top level component -// -//@DESCRIPTION: This component defines a mechanism, 'mqba::Application', -// responsible for instantiating and destroying the top-level BlazingMQ objects -// used by the BlazingMQ broker. +/// @file mqba_application.h +/// +/// @brief Provide an `Application` class to control object lifetime/creation. +/// +/// This component defines a mechanism, @bbref{mqba::Application}, responsible +/// for instantiating and destroying the top-level BlazingMQ objects used by +/// the BlazingMQ broker. // MQB #include @@ -32,6 +31,7 @@ #include #include +// BMQ #include // BDE @@ -110,26 +110,23 @@ class Application { BlobSpPool; // Data members + + /// Allocator store to spawn new allocators for sub components. bmqma::CountingAllocatorStore d_allocators; - // Allocator store to spawn new allocators - // for sub-components + /// Event scheduler (held not owned to use, sharde with all interested + /// components. bdlmt::EventScheduler* d_scheduler_p; - // Event scheduler (held not owned) to use, - // shared with all interested components. + /// Thread pool for admin commands execution. bdlmt::ThreadPool d_adminExecutionPool; - // Thread pool for admin commands - // execution. + /// Thread pool for routed admin commands execution. Ensuring rerouted + /// commands always execute on their own dedicated thread prevents a case + /// where two nodes are simultaneously waiting for each other to process a + /// routed command, but cannot make progress because the calling thread is + /// blocked ("deadlock"). Note that rerouted commands never route again. bdlmt::ThreadPool d_adminRerouteExecutionPool; - // Thread pool for routed admin commands execution. - // Ensuring rerouted commands always execute on their - // own dedicated thread prevents a case where two nodes - // are simultaneously waiting for each other to process - // a routed command, but cannot make process because - // the calling thread is blocked ("deadlock"). - // Note that rerouted commands never route again. bdlbb::PooledBlobBufferFactory d_bufferFactory; @@ -137,14 +134,13 @@ class Application { bdlma::ConcurrentPool d_pushElementsPool; + /// Stat context of the counting allocators, if used. bmqst::StatContext* d_allocatorsStatContext_p; - // Stat context of the counting allocators, - // if used PluginManagerMp d_pluginManager_mp; + /// Statistics controller component. StatControllerMp d_statController_mp; - // Statistics controller component ConfigProviderMp d_configProvider_mp; @@ -156,8 +152,8 @@ class Application { DomainManagerMp d_domainManager_mp; + /// Allocator to use. bslma::Allocator* d_allocator_p; - // Allocator to use private: // PRIVATE MANIPULATORS diff --git a/src/groups/mqb/mqba/mqba_clientsession.h b/src/groups/mqb/mqba/mqba_clientsession.h index 7e7d9f762..0f65d9d23 100644 --- a/src/groups/mqb/mqba/mqba_clientsession.h +++ b/src/groups/mqb/mqba/mqba_clientsession.h @@ -17,20 +17,17 @@ #ifndef INCLUDED_MQBA_CLIENTSESSION #define INCLUDED_MQBA_CLIENTSESSION -//@PURPOSE: Provide a session for interaction with BlazingMQ broker clients. -// -//@CLASSES: -// mqba::ClientSession : mechanism representing a session with a client -// mqba::ClientSessionState: VST representing the state of a session -// -//@DESCRIPTION: This component provides a mechanism, 'mqba::ClientSession', -// that allows BlazingMQ broker to send and receive messages from a client -// connected to the broker, whether it is a producer or a consumer or a peer -// BlazingMQ broker. 'mqba::ClientSessionState' is a value semantic type -// holding the state associated to an 'mqba::Session'. +/// @file mqba_clientsession.h +/// +/// @brief Provide a session for interaction with BlazingMQ broker clients. +/// +/// This component provides a mechanism, @bbref{mqba::ClientSession}, that +/// allows BlazingMQ broker to send and receive messages from a client +/// connected to the broker, whether it is a producer or a consumer or a peer +/// BlazingMQ broker. @bbref{mqba::ClientSessionState} is a value semantic +/// type holding the state associated to an @bbref{mqba::Session}. // MQB - #include #include #include @@ -109,11 +106,13 @@ struct ClientSessionState { /// yet acked. struct UnackedMessageInfo { // DATA - int d_correlationId; // Correlation Id of the message. - bsls::Types::Int64 d_timeStamp; // The time when the message was - // received, in absolute - // nanoseconds referenced to an - // arbitrary but fixed origin. + + /// Correlation Id of the message. + int d_correlationId; + + /// The time when the message was received, in absolute nanosections + /// referenced to an arbitrary but fixed origin. + bsls::Types::Int64 d_timeStamp; // CREATORS UnackedMessageInfo(int correlationId, bsls::Types::Int64 timeStamp); @@ -152,72 +151,57 @@ struct ClientSessionState { public: // PUBLIC DATA + + /// Allocator to use. bslma::Allocator* d_allocator_p; - // Allocator to use. + /// Queue of data pending being sent to the client. This should almost + /// always be empty and is meant to provide a buffer for a "throttling" + /// mechanism when sending a huge burst of data (typically at queue open) + /// that would go beyond the channel high watermark. This should only be + /// manipulated from the dispatcher thread. Note that it really should be + /// a queue and not a deque, but queue doesn't have a `clear` method. bsl::deque > d_channelBufferQueue; - // Queue of data pending being sent to - // the client. This should almost - // always be empty, and is meant to - // provide buffer for a 'throttling' - // mechanism when sending huge burst of - // data (typically at queue open) that - // would go beyond the channel high - // watermark. This should only be - // manipulated from the dispatcher - // thread. Note that it really should - // be a queue and not a deque, but - // queue doesn't have a 'clear' method. + /// Map containing the GUID->UnackedMessageInfo entries. UnackedMessageInfoMap d_unackedMessageInfos; - // Map containing the - // GUID->UnackedMessageInfo entries. + /// Dispatcher client data associated to this session. mqbi::DispatcherClientData d_dispatcherClientData; - // Dispatcher client data associated to - // this session. + /// Stat context dedicated to this domain, to use as the parent stat + /// context for any queue in this domain. StatContextMp d_statContext_mp; - // Stat context dedicated to this - // domain, to use as the parent stat - // context for any queue in this - // domain. /// Blob buffer factory to use. - /// TODO: this field should be removed once we retire the code for - /// message properties conversion. + /// + /// @todo This field should be removed once we retire the code for message + /// properties conversion. bdlbb::BlobBufferFactory* d_bufferFactory_p; + /// Pool of shared pointers to blob to use. BlobSpPool* d_blobSpPool_p; - // Pool of shared pointers to blob to - // use. + /// Builder for schema messages. To be used only in client dispatcher + /// thread. bmqp::SchemaEventBuilder d_schemaEventBuilder; - // Builder for schema messages. To be - // used only in client dispatcher - // thread. + /// Builder for push messages. To be used only in client dispatcher + /// thread. bmqp::PushEventBuilder d_pushBuilder; - // Builder for push messages. To be - // used only in client dispatcher - // thread. + /// Builder for ack messages. To be used only in client dispatcher thread. bmqp::AckEventBuilder d_ackBuilder; - // Builder for ack messages. To be - // used only in client dispatcher - // thread. + /// Throttler for failed ACK messages. bdlmt::Throttle d_throttledFailedAckMessages; - // Throttler for failed ACK messages. + /// Throttler for failed PUT messages. bdlmt::Throttle d_throttledFailedPutMessages; - // Throttler for failed PUT messages. + /// Stats associated with an unknown queue, lazily created when the first + /// usage of an unknown queue is encountered bdlb::NullableValue d_invalidQueueStats; - // Stats associated with an unknown - // queue, lazily created when the first - // usage of an unknown queue is - // encountered private: // NOT IMPLEMENTED @@ -272,21 +256,23 @@ class ClientSession : public mqbnet::Session, /// Enum to signify the session's operation state. enum OperationState { - e_RUNNING // Running normally - , + /// Running normally. + e_RUNNING, + /// Shutting down due to `initiateShutdown` request. // TODO(shutdown-v2): TEMPORARY, remove when all switch to StopRequest // V2. - e_SHUTTING_DOWN // Shutting down due to 'initiateShutdown' request - , - e_SHUTTING_DOWN_V2 // Shutting down due to 'initiateShutdown' request - , - e_DISCONNECTING // Disconnecting due to the client disconnect request - , - e_DISCONNECTED // The session is disconnected and no more valid - , - e_DEAD // The session cannot do anything + e_SHUTTING_DOWN, + /// Shutting down due to `initiateShutdown` request. + e_SHUTTING_DOWN_V2, + /// Disconnecting due to the client disconnect request. + e_DISCONNECTING, + /// The session is disconnected and no longer valid. + e_DISCONNECTED, + /// The session cannot do anything. + e_DEAD }; + /// Struct to be used as a context for shutdown operation. struct ShutdownContext { ShutdownCb d_callback; bsls::TimeInterval d_stopTime; @@ -304,105 +290,80 @@ class ClientSession : public mqbnet::Session, ~ShutdownContext(); }; - // Struct to be used as a context for shutdown operation. typedef bsl::shared_ptr ShutdownContextSp; private: // DATA + + /// This object is used to avoid executing a callback if the session has + /// been destroyed: this is *ONLY* to be used with the callbacks that will + /// be called from outside of the dispatcher's thread (such as a remote + /// configuration service IO thread), because we can't guarantee this queue + /// is drained before destroying the session. bmqu::SharedResource d_self; - // This object is used to avoid - // executing a callback if the session - // has been destroyed: this is *ONLY* to - // be used with the callbacks that will - // be called from outside of the - // dispatcher's thread (such as a remote - // configuration service IO thread); - // because we can't guarantee this queue - // is drained before destroying the - // session. + /// Show whether the session is running or shutting down due to either a + /// stop request, or a client's disconnect request, or the channel being + /// down. Once the channel has been destroyed and is no longer valid or we + /// sent the `DisconnectResponse` to the client, *NO* messages of any sort + /// should be delivered to the client. OperationState d_operationState; - // Show whether the session is running - // or shutting down due to either stop - // request, or client's disconnect - // request, or the channel is down. - // Once the channel has been destroyed - // and is no longer valid or we sent the - // 'DisconnectResponse' to the client, - // *NO* messages of any sort should be - // delivered to the client. + /// Set to true when receiving a `DisconnectRequest` from the client. Only + /// used in the `processEvent` (in the IO thread) to validate that the + /// client honors the contract and doesn't send anything after the + /// `Disconnect` notification. bool d_isDisconnecting; - // Set to true when receiving a - // 'DisconnectRequest' from the client; - // only used in the processEvent (in IO - // thread) to validate that the client - // honors the contract and doesn't send - // any thing after the 'Disconnect' - // notification. + /// Negotiation message received from the remote peer. bmqp_ctrlmsg::NegotiationMessage d_negotiationMessage; - // Negotiation message received from the - // remote peer. + /// Raw pointer to the right field in `d_negotiationMessage` (dpending on + /// whether it's a "client" or a "broker"). bmqp_ctrlmsg::ClientIdentity* d_clientIdentity_p; - // Raw pointer to the right field in - // 'd_negotiationMessage' (depending - // whether it's a 'client' or a - // 'broker'). + /// Set to true when the client identity `guidInfo` struct contains + /// non-empty `clientId` field. If this broker the first hop, then the + /// client is an SDK, which generates GUIDs for PUTs using + /// @bbref{bmqp::MessageGUIDGenerator} and doesn't provide correlation ids. const bool d_isClientGeneratingGUIDs; - // Set to true when the client identity - // 'guidInfo' struct contains non-empty - // 'clientId' field. If this broker is - // first hop then the client is SDK - // which generates GUIDs for PUTs using - // 'bmqp::MessageGUIDGenerator' and - // doesn't provide correlation ids. + /// Short identifier for this session. bsl::string d_description; - // Short identifier for this session. + /// Channel associated with this session. bsl::shared_ptr d_channel_sp; - // Channel associated to this session. + /// The state associated with this session. ClientSessionState d_state; - // The state associated to this session. + /// Queue session manager for this session. mqbblp::QueueSessionManager d_queueSessionManager; - // Queue session manager for this - // session. + /// Cluster catalog to query for cluster information. mqbblp::ClusterCatalog* d_clusterCatalog_p; - // Cluster catalog to query for cluster - // information + /// Pointer to the event scheduler to use (held, not owned). bdlmt::EventScheduler* d_scheduler_p; - // Pointer to the event scheduler to - // use (held, not owned) + /// Handler to manage the scheduled event that triggers the checking of + /// unconfirmed messages during the session shutdown. bdlmt::EventSchedulerEventHandle d_periodicUnconfirmedCheckHandler; - // Handler to manage the scheduled - // event that triggers the checking of - // the unconfirmed messages during the - // session shutdown. + /// Mechanism used for the graceful shutdown of the session to serialize + /// execution of the queue handle deconfigure callbacks. bmqu::OperationChain d_shutdownChain; - // Mechanism used for the session - // graceful shutdown to serialize - // execution of the queue handle - // deconfigure callbacks. + /// If present, call when `tearDownAllQueuesDone`. This is the callback + /// given in `initiateShutdown`. ShutdownCb d_shutdownCallback; - // If present, call when 'tearDownAllQueuesDone'. - // This is the callback given in 'initiateShutdown' + /// HiRes timer value of the begin session/queue operation. bsls::Types::Int64 d_beginTimestamp; - // HiRes timer value of the begin session/queue operation + /// Stream for constructing current session/queue operation description. bmqu::MemOutStream d_currentOpDescription; - // Stream for constructing current session/queue operation description. private: // NOT IMPLEMENTED diff --git a/src/groups/mqb/mqba/mqba_commandrouter.h b/src/groups/mqb/mqba/mqba_commandrouter.h index 74c9a9be5..4c33260e2 100644 --- a/src/groups/mqb/mqba/mqba_commandrouter.h +++ b/src/groups/mqb/mqba/mqba_commandrouter.h @@ -13,40 +13,41 @@ // See the License for the specific language governing permissions and // limitations under the License. -// mqbblp_messagegroupidmanager.h -*-C++-*- +// mqba_commandrouter.h -*-C++-*- #ifndef INCLUDED_MQBA_COMMANDROUTER #define INCLUDED_MQBA_COMMANDROUTER -//@PURPOSE: Provide a class responsible for routing admin commands to the -// subset of cluster nodes that should execute that command. -// -// This currently only supports routing cluster related commands (i.e. cluster -// commands and domain commands). There are 2 main routing modes supported: -// routing to primary node(s) or to all nodes in the cluster. The following -// commands are supported: -// * Primary commands -// * DOMAINS DOMAIN PURGE -// * DOMAINS DOMAIN QUEUE PURGE -// * CLUSTERS CLUSTER FORCE_GC_QUEUES -// * CLUSTERS CLUSTER STORAGE PARTITION [ENABLE|DISABLE] -// * Cluster-wide commands -// * DOMAINS RECONFIGURE -// * CLUSTERS CLUSTER STORAGE REPLICATION SET_ALL -// * CLUSTERS CLUSTER STORAGE REPLICATION GET_ALL -// * CLUSTERS CLUSTER STATE ELECTOR SET_ALL -// * CLUSTERS CLUSTER STATE ELECTOR GET_ALL -// -// Routing operates on mqbnet::ClusterNode pointers, which currently limits our -// ability to route non-cluster commands. In order to support routing non -// cluster related commands, this class would need to be generalized or add -// specialized cases for routing using a more fundamental abstraction (i.e. a -// Session or Channel). This is beyond the scope of current needs at the time -// of writing this feature. -// -//@CLASSES: -// mqbcmd::CommandRouter: Manages routing a single admin command. This class -// is designed to be used once per command and should be destructed after -// the command has been processed. +/// @file mqba_commandrouter.h +/// +/// @brief Provide a class responsible for routing admin commands to the subset +/// of cluster nodes that should execute that command. +/// +/// This currently only supports routing cluster related commands (i.e. cluster +/// commands and domain commands). There are 2 main routing modes supported: +/// routing to primary node(s) or routing to all nodes in the cluster. The +/// following commands are supported: +/// +/// * Primary commands +/// * `DOMAINS DOMAIN PURGE` +/// * `DOMAINS DOMAIN QUEUE PURGE ` +/// * `CLUSTERS CLUSTER FORCE_GC_QUEUES` +/// * `CLUSTERS CLUSTER STORAGE PARTITION +/// [ENABLE|DISABLE]` +/// * Cluster-wide commands +/// * `DOMAINS RECONFIGURE ` +/// * `CLUSTERS CLUSTER STORAGE REPLICATION SET_ALL +/// ` +/// * `CLUSTERS CLUSTER STORAGE REPLICATION GET_ALL ` +/// * `CLUSTERS CLUSTER STATE ELECTOR SET_ALL ` +/// * `CLUSTERS CLUSTER STATE ELECTOR GET_ALL ` +/// +/// Routing operates on @bbref{mqbnet::ClusterNode} pointers, which currently +/// limits our ability to route non-cluster commands. In order to support +/// routing non-cluster-related commands, this class would need to be +/// generalized or add specialized cases for routing using a more fundamental +/// abstraction (i.e. a @bbref{mqbnet::Session} or a @bbref{mqbnet::Channel}). +/// This is beyond the scope of current needs at the time of writing this +/// feature. // BDE #include @@ -79,29 +80,33 @@ class MultiRequestManagerRequestContext; namespace mqba { +/// Manages routing a single admin command. This class is designed to be used +/// once per command and should be destructed after the command has been +/// processed. class CommandRouter { private: // PRIVATE TYPES /// Shared pointer to the correct multirequest context for routing control - /// messages to `mqbnet::ClusterNode`s + /// messages to @bbref{mqbnet::ClusterNode}s. typedef bsl::shared_ptr< mqbnet::MultiRequestManagerRequestContext > MultiRequestContextSp; - /// Vector of `mqbnet::ClusterNode` pointers used for routing + /// Vector of @bbref{mqbnet::ClusterNode} pointers used for routing. typedef bsl::vector NodesVector; private: - /// Struct representing which nodes a command should be routed to. Contains + /// VST representing which nodes a command should be routed to. Contains /// both a list of external nodes to route to and a flag indicating whether /// the self node should execute the command. struct RouteTargets { - NodesVector d_nodes; // Proxy nodes and the self node should never be - // route members. - bool d_self; // True if the command should execute on the self node. + /// Proxy nodes and the self node should never be route members. + NodesVector d_nodes; + /// True if the command should execute on the self node. + bool d_self; }; // ================== diff --git a/src/groups/mqb/mqba/mqba_configprovider.h b/src/groups/mqb/mqba/mqba_configprovider.h index d1ddab76b..49884b29f 100644 --- a/src/groups/mqb/mqba/mqba_configprovider.h +++ b/src/groups/mqb/mqba/mqba_configprovider.h @@ -17,20 +17,17 @@ #ifndef INCLUDED_MQBA_CONFIGPROVIDER #define INCLUDED_MQBA_CONFIGPROVIDER -//@PURPOSE: Provide a mechanism to retrieve configuration information. -// -//@CLASSES: -// mqba::ConfigProvider: mechanism to retrieve configuration information -// -//@DESCRIPTION: 'mqba::ConfigProvider' is a mechanism to retrieve configuration -// information for domain, ... - -// TBD: -// o add commandHandler -// o add statistics +/// @file mqba_configprovider.h +/// +/// @brief Provide a mechanism to retrieve configuration information. +/// +/// @bbref{mqba::ConfigProvider} is a mechanism to retrieve configuration +/// information for domain, ... +/// +/// @todo Add commandHandler. +/// @todo Add statistics. // MQB - #include // BDE @@ -85,19 +82,21 @@ class ConfigProvider { struct Mode { // TYPES enum Enum { - e_NORMAL // Use conf service, failover to disk backup - , - e_FORCE_BACKUP // Skip conf service, only use disk backup + /// Use conf service, failover to disk backup. + e_NORMAL, + /// Skip conf service, only use disk backup. + e_FORCE_BACKUP }; }; /// Struct to represent a configuration response entry in the cache. struct CacheEntry { // PUBLIC DATA - mqbconfm::Response d_data; // Data to cache. - bsls::TimeInterval d_expireTime; // Time after which this entry is no - // longer valid. + /// Data to cache. + mqbconfm::Response d_data; + /// Time after which this entry is no longer valid. + bsls::TimeInterval d_expireTime; }; typedef bsl::unordered_map CacheMap; @@ -108,17 +107,15 @@ class ConfigProvider { bslmt::Mutex d_mutex; + /// Cache (with a small TTL for its entries). The key is the `domainName` + /// for the domain config. This cache has a small TTL and is used to + /// prevent flooding the conf service with the same request if, for example + /// during turnaround, lots of tasks come up at the same time and request + /// the same domain. CacheMap d_cache; - // Cache (with a small TTL for its entries). Key - // is 'domainName' for the domain config. This - // cache has a small TTL and is used to prevent - // flooding conf service with the same request, - // if, for example during turnaround lots of task - // comes up at same time and request the same - // domain. + /// Allocator to use. bslma::Allocator* d_allocator_p; - // Allocator to use private: // PRIVATE MANIPULATORS diff --git a/src/groups/mqb/mqba/mqba_dispatcher.h b/src/groups/mqb/mqba/mqba_dispatcher.h index 23861cc85..b15f8a307 100644 --- a/src/groups/mqb/mqba/mqba_dispatcher.h +++ b/src/groups/mqb/mqba/mqba_dispatcher.h @@ -17,39 +17,39 @@ #ifndef INCLUDED_MQBA_DISPATCHER #define INCLUDED_MQBA_DISPATCHER -//@PURPOSE: Provide an event dispatcher at the core of BlazingMQ broker. -// -//@CLASSES: -// mqba::Dispatcher: Event dispatcher. -// -//@SEE_ALSO: -// mqbi::Dispatcher: Protocol implemented by this dispatcher -// -//@DESCRIPTION: 'mqba::Dispatcher' is an implementation of the -// 'mqbi::Dispatcher' protocol, using the bmqc::MultiQueueThreadPool. This -// dispatcher supports three types of isolated independent pools of threads and -// queues: one for the client sessions, one for the queues, and one for -// clusters. -// -/// Thread Safety -///------------- -// 'mqba::Dispatcher' is thread safe. -// -/// Executors support -///----------------- -// As required by the 'mqbi::Dispatcher' protocol, this implementation provides -// two types of executors, each available through the dispatcher's 'executor' -// and 'clientExecutor' member functions respectively. Provided executors -// compares equal only if they refer to the same processor (for executors -// returned by 'executor'), or if they refer to the same client (for executors -// returned by 'clientExecutor'). A call to 'dispatch' on such executors -// performed from within the executor's associated processor thread results in -// the submitted functor to be executed in-place. A call to 'dispatch' from -// outside of the executor's associated processor thread is equivalent to a -// call to 'post'. +/// @file mqba_dispatcher.h +/// +/// @brief Provide an event dispatcher at the core of BlazingMQ broker. +/// +/// @bbref{mqba::Dispatcher} is an implementation of the +/// @bbref{mqbi::Dispatcher} protocol, using +/// @bbref{bmqc::MultiQueueThreadPool}. This dispatcher supports three types +/// of isolated independent pools of threads and queues: one for the client +/// sessions, one for the queues, and one for clusters. +/// +/// @see @bbref{mqba::Dispatcher}: +/// Protocol implemented by this dispatcher. +/// +/// Thread Safety {#mqba_dispatcher_thread} +/// ============= +/// +/// @bbref{mqba::Dispatcher} is thread-safe. +/// +/// Executors support {#mqba_dispatcher_executors} +/// ================= +/// +/// As required by the @bbref{mqbi::Dispatcher} protocol, this implementation +/// provides two types of executors, each available through the dispatcher's +/// `executor` and `clientExecutor` member functions respectively. Provided +/// executors compares equal only if they refer to the same processor (for +/// executors returned by `executor`), or if they refer to the same client (for +/// executors returned by `clientExecutor`). A call to `dispatch` on such +/// executors performed from within the executor's associated processor thread +/// results in the submitted functor to be executed in-place. A call to +/// `dispatch` from outside of the executor's associated processor thread is +/// equivalent to a call to `post`. // MQB - #include #include #include @@ -233,27 +233,20 @@ class Dispatcher BSLS_CPP11_FINAL : public mqbi::Dispatcher { public: // PUBLIC DATA + + /// Thread pool to use. ThreadPoolMp d_threadPool_mp; - // Thread Pool to use + /// Processor pool to use. ProcessorPoolMp d_processorPool_mp; - // Processor Pool to use + /// The object responsible for distributing clients across processors. mqbu::LoadBalancer d_loadBalancer; - // The object responsible - // for distributing clients - // across processors + /// Vector of vector of pointers to `DispatcherClients` with the + /// clients for which a flush needs to be called. The first index of + /// the vector corresponds to the processor. bsl::vector d_flushList; - // Vector of vector of - // pointers to - // DispatcherClients, with - // the clients for which a - // flush needs to be - // called. The first index - // of the vector - // corresponds to the - // processor. // TRAITS BSLMF_NESTED_TRAIT_DECLARATION(DispatcherContext, @@ -276,21 +269,21 @@ class Dispatcher BSLS_CPP11_FINAL : public mqbi::Dispatcher { private: // DATA + + /// Allocator to use. bslma::Allocator* d_allocator_p; - // Allocator to use + /// True if this component is started. bool d_isStarted; - // True if this component is started + /// Configuration for the dispatcher. mqbcfg::DispatcherConfig d_config; - // Configuration for the dispatcher + /// Event scheduler to use. bdlmt::EventScheduler* d_scheduler_p; - // Event scheduler to use + /// The various contexts, one for each `ClientType`. bsl::vector d_contexts; - // The various context, one for each - // ClientType // FRIENDS friend class Dispatcher_ClientExecutor; @@ -299,10 +292,10 @@ class Dispatcher BSLS_CPP11_FINAL : public mqbi::Dispatcher { private: // PRIVATE MANIPULATORS - /// Start the dispatcher context associated to clients of the specified - /// `type`, using the specified `config` and return 0 on success, or - /// return a non-zero value and populate the specified - /// `errorDescription` on error. + /// Start the dispatcher context associated with clients of the specified + /// `type`, using the specified `config` and return 0 on success, or return + /// a non-zero value and populate the specified `errorDescription` on + /// error. int startContext(bsl::ostream& errorDescription, mqbi::DispatcherClientType::Enum type, const mqbcfg::DispatcherProcessorConfig& config); @@ -320,8 +313,8 @@ class Dispatcher BSLS_CPP11_FINAL : public mqbi::Dispatcher { bslma::Allocator* allocator); /// Callback when a new object in the specified `event` and having the - /// associated specified `context` is dispatched for the queue in charge - /// of dispatcher client of the specified `type`, having the specified + /// specified associated `context` is dispatched for the queue in charge of + /// dispatcher client of the specified `type`, having the specified /// `processorId`. void queueEventCb(mqbi::DispatcherClientType::Enum type, int processorId, @@ -333,7 +326,7 @@ class Dispatcher BSLS_CPP11_FINAL : public mqbi::Dispatcher { void flushClients(mqbi::DispatcherClientType::Enum type, int processorId); /// This method is invoked when a new client of the specified `type` is - /// registered to the dispatcher, from the thread associated to that new + /// registered to the dispatcher, from the thread associated with that new /// client that is mapped to the specified `processorId`. void onNewClient(mqbi::DispatcherClientType::Enum type, int processorId); @@ -363,17 +356,16 @@ class Dispatcher BSLS_CPP11_FINAL : public mqbi::Dispatcher { /// Stop the `Dispatcher`. void stop(); - /// Based on the specified `type`, associate the specified `client` to - /// one of the processors of the dispatcher if the optionally specified + /// Based on the specified `type`, associate the specified `client` to one + /// of the processors of the dispatcher if the optionally specified /// `handle` is invalid, or to the provided `handle` if it is valid, and /// fill in the `processorHandle` and `dispatcherClientType` in the - /// client's `dispatcherClientData` member. This operation is a no-op - /// if the `client` is already associated with a processor *and* - /// `handle` is invalid. If `handle` is valid, behavior is undefined - /// unless `client` is not associated with any processor. Note that - /// specifying a valid `handle` is useful when BlazingMQ broker requires - /// a client to be associated to same processor across it's (broker's) - /// instantiations. + /// client's `dispatcherClientData` member. This operation is a no-op if + /// the `client` is already associated with a processor *and* `handle` is + /// invalid. If `handle` is valid, behavior is undefined unless `client` + /// is not associated with any processor. Note that specifying a valid + /// `handle` is useful when BlazingMQ broker requires a client to be + /// associated with same processor across it's (broker's) instantiations. mqbi::Dispatcher::ProcessorHandle registerClient(mqbi::DispatcherClient* client, mqbi::DispatcherClientType::Enum type, @@ -381,36 +373,36 @@ class Dispatcher BSLS_CPP11_FINAL : public mqbi::Dispatcher { mqbi::Dispatcher::k_INVALID_PROCESSOR_HANDLE) BSLS_KEYWORD_OVERRIDE; - /// Remove the association of the specified `client` from its - /// processor. If the `client` is not associated with any processor, - /// this method has no effect. + /// Remove the association of the specified `client` from its processor. + /// If the `client` is not associated with any processor, this method has + /// no effect. void unregisterClient(mqbi::DispatcherClient* client) BSLS_KEYWORD_OVERRIDE; + /// Retrieve an event from the pool to send to a client of the specified + /// `type`. This event *must* be enqueued by calling `dispatchEvent`; + /// otherwise it will be leaked. mqbi::DispatcherEvent* getEvent(mqbi::DispatcherClientType::Enum type) BSLS_KEYWORD_OVERRIDE; - // Retrieve an event from the pool to send to a client of the specified - // 'type'. This event *must* be enqueued by calling 'dispatchEvent', - // otherwise it will be leaked. + /// Retrieve an event from the pool to send to the specified `client`. + /// This event *must* be enqueued by calling `dispatchEvent`; otherwise it + /// will be leaked. mqbi::DispatcherEvent* getEvent(const mqbi::DispatcherClient* client) BSLS_KEYWORD_OVERRIDE; - // Retrieve an event from the pool to send to the specified 'client'. - // This event *must* be enqueued by calling 'dispatchEvent' otherwise - // it will be leaked. + /// Dispatch the specified `event` to the specified `destination`. void dispatchEvent(mqbi::DispatcherEvent* event, mqbi::DispatcherClient* destination) BSLS_KEYWORD_OVERRIDE; - // Dispatch the specified 'event' to the specified 'destination'. + /// Dispatch the specified `event` to the queue associated with the + /// specified `type` and `handle`. The behavior is undefined unless the + /// `event` was obtained by a call to `getEvent`. void dispatchEvent(mqbi::DispatcherEvent* event, mqbi::DispatcherClientType::Enum type, mqbi::Dispatcher::ProcessorHandle handle) BSLS_KEYWORD_OVERRIDE; - // Dispatch the specified 'event' to the queue associated with the - // specified 'type' and 'handle'. The behavior is undefined unless the - // 'event' was obtained by a call to 'getEvent'. /// Execute the specified `functor` in the processors in charge of /// clients of the specified `type`, and invoke the optionally specified @@ -421,50 +413,55 @@ class Dispatcher BSLS_CPP11_FINAL : public mqbi::Dispatcher { const mqbi::Dispatcher::VoidFunctor& doneCallback = mqbi::Dispatcher::VoidFunctor()) BSLS_KEYWORD_OVERRIDE; + /// Execute the specified `functor`, using the specified dispatcher `type`, + /// in the processor associated with the specified `client`. The behavior + /// is undefined unless `type` is `e_DISPATCHER` or `e_CALLBACK`. void execute(const mqbi::Dispatcher::VoidFunctor& functor, mqbi::DispatcherClient* client, mqbi::DispatcherEventType::Enum type) BSLS_KEYWORD_OVERRIDE; - // Execute the specified 'functor', using the specified dispatcher - // 'type', in the processor associated to the specified 'client'. The - // behavior is undefined unless 'type' is 'e_DISPATCHER' or - // 'e_CALLBACK'. + /// Execute the specified `functor` using the `e_DISPATCHER` event type, in + /// the processor associated with the specified `client`. void execute(const mqbi::Dispatcher::VoidFunctor& functor, const mqbi::DispatcherClientData& client) BSLS_KEYWORD_OVERRIDE; - // Execute the specified 'functor', using the 'e_DISPATCHER' event - // type, in the processor associated to the specified 'client'. + /// Enqueue an event to the processor associated with the specified + /// `client` and block until this event gets dequeued. This is typically + /// used by a `dispatcherClient`, in its destructor, to drain the + /// dispatcher's queue and ensure no more events are to be expected for + /// that `client`. The behavior is undefined if `synchronize` is being + /// invoked from the `client`s thread. void synchronize(mqbi::DispatcherClient* client) BSLS_KEYWORD_OVERRIDE; - /// Enqueue an event to the processor associated to the specified - /// `client` or pair of the specified `type` and `handle` and block - /// until this event gets dequeued. This is typically used by a - /// `dispatcherClient`, in its destructor, to drain the dispatcher's - /// queue and ensure no more events are to be expected for that - /// `client`. The behavior is undefined if `synchronize` is being + /// Enqueue an event to the processor associated with the specified pair of + /// `type` and `handle` and block until this event gets dequeued. This is + /// typically used by a `dispatcherClient`, in its destructor, to drain the + /// dispatcher's queue and ensure no more events are to be expected for + /// that `client`. The behavior is undefined if `synchronize` is being /// invoked from the `client`s thread. void synchronize(mqbi::DispatcherClientType::Enum type, mqbi::Dispatcher::ProcessorHandle handle) BSLS_KEYWORD_OVERRIDE; // ACCESSORS + + /// Return number of processors dedicated for dispatching clients of the + /// specified `type`. int numProcessors(mqbi::DispatcherClientType::Enum type) const BSLS_KEYWORD_OVERRIDE; - // Return number of processors dedicated for dispatching clients of the - // specified 'type'. + /// Return whether the current thread is the dispatcher thread associated + /// with the specified `client`. This is useful for precondition assert + /// validation. bool inDispatcherThread(const mqbi::DispatcherClient* client) const BSLS_KEYWORD_OVERRIDE; - // Return whether the current thread is the dispatcher thread - // associated to the specified 'client'. This is usefull for - // preconditions assert validation. + /// Return whether the current thread is the dispatcher thread associated + /// with the specified dispatcher client `data`. This is useful for + /// precondition assert validation. bool inDispatcherThread(const mqbi::DispatcherClientData* data) const BSLS_KEYWORD_OVERRIDE; - // Return whether the current thread is the dispatcher thread - // associated to the specified dispatcher client 'data'. This is - // useful for preconditions assert validation. /// Return an executor object suitable for executing function objects on /// the processor in charge of the specified `client`. The behavior is diff --git a/src/groups/mqb/mqba/mqba_domainmanager.h b/src/groups/mqb/mqba/mqba_domainmanager.h index 18e26ffd1..a7dd7c686 100644 --- a/src/groups/mqb/mqba/mqba_domainmanager.h +++ b/src/groups/mqb/mqba/mqba_domainmanager.h @@ -17,20 +17,20 @@ #ifndef INCLUDED_MQBA_DOMAINMANAGER #define INCLUDED_MQBA_DOMAINMANAGER -//@PURPOSE: Provide a manager for all queue domains. -// -//@CLASSES: -// mqba::DomainManager: Manager for all queue domains. -// -//@DESCRIPTION: The 'mqba::DomainManager' provides a manager for all queue -// domains. The 'DomainManager' exposes a factory-method 'getDomain' to -// retrieve a 'mqbi::Domain' (if already previously opened and still active), -// or will try to create and configure one using one of the registered factory -// methods. -// -/// Thread Safety -///------------- -// This component is thread safe. +/// @file mqba_domainmanager.h +/// +/// @brief Provide a manager for all queue domains. +/// +/// The @bbref{mqba::DomainManager} provides a manager for all queue domains. +/// The `DomainManager` exposes a factory-method `getDomain` to retrieve a +/// @bbref{mqbi::Domain} (if already previously opened and still active), or +/// will try to create and configure one using one of the registered factory +/// methods. +/// +/// Thread Safety {#mqba_domainmanager_thread} +/// ============= +/// +/// This component is thread safe. // MQB #include @@ -144,51 +144,52 @@ class DomainManager BSLS_CPP11_FINAL : public mqbi::DomainFactory { /// if an insert was performed or `false` otherwise. typedef bsl::pair UpsertDomainSuccess; + /// A type with details on errors for `upsertDomain()`. struct Error; - // A type with details on errors for 'upsertDomain()'. /// The return type for `upsertDomain()` might be a value or an error. typedef bmqvt::ValueOrError UpsertDomainValue; + /// The return type for `decodeAndUpsert()`, which might be a value or an + /// error. typedef bmqvt::ValueOrError DecodeAndUpsertValue; - // The return type for 'decodeAndUpsert()' might be a value or an error. private: // DATA + + /// ConfigProvider to use, held not owned. ConfigProvider* d_configProvider_p; - // ConfigProvider to use, held not owned + /// BlobBufferFactory to use, held not owned. bdlbb::BlobBufferFactory* d_blobBufferFactory_p; - // BlobBufferFactory to use, held not owned + /// DomainResolver DomainResolverMp d_domainResolver_mp; - // DomainResolver + /// ClusterCatalog to use, held not owned. mqbblp::ClusterCatalog* d_clusterCatalog_p; // ClusterCatalog to use, held, not owned + /// Top-level stat context for all domains stats. bmqst::StatContext* d_domainsStatContext_p; - // Top-level stat context for all - // domains stats + /// Top-level stat context for all domains/queues stats. bmqst::StatContext* d_queuesStatContext_p; - // Top-level stat context for all - // domains/queues stats + /// Dispatcher to use, held not owned. mqbi::Dispatcher* d_dispatcher_p; - // Dispatcher to use, held not owned + /// Mutex for thread-safety of this component. mutable bslmt::Mutex d_mutex; - // Mutex for thread-safety of this component + /// Map of domains. DomainSpMap d_domains; - // Map of domains + /// Is the domain manager started. bsls::AtomicBool d_isStarted; - // Is the domain manager started + /// Allocator to use. bslma::Allocator* d_allocator_p; - // Allocator to use private: // PRIVATE MANIPULATORS diff --git a/src/groups/mqb/mqba/mqba_domainresolver.h b/src/groups/mqb/mqba/mqba_domainresolver.h index cb2ce0c2e..575fa2fa2 100644 --- a/src/groups/mqb/mqba/mqba_domainresolver.h +++ b/src/groups/mqb/mqba/mqba_domainresolver.h @@ -17,45 +17,44 @@ #ifndef INCLUDED_MQBA_DOMAINRESOLVER #define INCLUDED_MQBA_DOMAINRESOLVER -//@PURPOSE: Provide a mechanism to resolve domain and their associated cluster. -// -//@CLASSES: -// mqba::DomainResolver: Mechanism to resolve domain and their cluster -// -//@DESCRIPTION: 'mqba::DomainResolver' provides a mechanism to resolve a -// domain, and figure out the associated cluster where that domain lives. -// Resolving a domain means that, for a given domain name, on a given machine, -// it may be translated to a more qualified domain. This is done in order to -// provide seamless segregation between tiers for a given domain, to account -// for a dev, alpha, beta, prod, ..., cluster. -// -/// CACHING -///------- -// Each resolved domain response is kept in a map, along with the last -// modification timestamp of the script and associated configuration directory -// at the time the entry was added to the cache. When querying to resolve a -// domain, this component will reuse that cache entry if it's not considered -// stale. An entry is stale if either the last modification timestamp of the -// script or the one of the configuration directory is different than the -// stored value in the cache for that entry. This means that we need to verify -// those timestampseverytime before checking the cache. In order to minimize -// filesystem overhead, we don't look up the timestamps more than once per -// minute (see 'k_SCRIPT_CHECK_TTL' value in the cpp file). -// -/// Thread-safety -///------------- -// This object is *fully thread-safe*, meaning that two threads can safely call -// any methods on the *same* *instance* without external synchronization. -// -/// TBD -///--- -//: o add commandHandler -//: o add statistics -//: o eventually split domain resolution and domain location in two separate -//: entities +/// @file mqba_domainresolver.h +/// +/// @brief Provide a mechanism to resolve domain and their associated cluster. +/// +/// +/// @bbref{mqba::DomainResolver} provides a mechanism to resolve a domain, and +/// figure out the associated cluster where that domain lives. Resolving a +/// domain means that, for a given domain name, on a given machine, it may be +/// translated to a more qualified domain. This is done in order to provide +/// seamless segregation between tiers for a given domain, to account for a +/// dev, alpha, beta, prod, ..., cluster. +/// +/// Caching {#mqba_domainresolver_caching} +/// ======= +/// +/// Each resolved domain response is kept in a map, along with the last +/// modification timestamp of the script and associated configuration directory +/// at the time the entry was added to the cache. When querying to resolve a +/// domain, this component will reuse that cache entry if it's not considered +/// stale. An entry is stale if either the last modification timestamp of the +/// script or the one of the configuration directory is different than the +/// stored value in the cache for that entry. This means that we need to +/// verify those timestampseverytime before checking the cache. In order to +/// minimize filesystem overhead, we don't look up the timestamps more than +/// once per minute (see `k_SCRIPT_CHECK_TTL` value in the cpp file). +/// +/// Thread-safety {#mqba_domainresolver_thread} +/// ============= +/// +/// This object is *fully thread-safe*, meaning that two threads can safely +/// call any methods on the *same* *instance* without external synchronization. +/// +/// @todo Add `commandHandler` +/// @todo Add statistics. +/// @todo Eventually split domain resolution and domain location in two +/// separate entities. // MQB - #include #include @@ -111,36 +110,36 @@ class DomainResolver { /// map. struct CacheEntry { // PUBLIC DATA + + /// Cached response data. mqbconfm::DomainResolver d_data; - // Cached response data. + /// Last modification timestamp of the config directory at the time + /// this data was generated. bdlt::Datetime d_cfgDirTimestamp; - // Last modification timestamp of the config - // directory at the time this data was - // generated. }; + /// Map of domain name to cache entry. typedef bsl::unordered_map CacheMap; - // Map of domain name to cache entry private: // DATA + + /// Protecting the CacheMap. bslmt::Mutex d_mutex; - // Protecting the CacheMap + /// Cache map CacheMap d_cache; - // Cache map + /// Last modification timestamp of the config directory. bdlt::Datetime d_lastCfgDirTimestamp; - // Last modification timestamp of the config - // directory. + /// Time until which the `d_lastCfgDirTimestamp` should be considered + /// valid. bsls::TimeInterval d_timestampsValidUntil; - // Time until which the 'd_lastCfgDirTimestamp' - // should be considered valid. + /// Allocator to use. bslma::Allocator* d_allocator_p; - // Allocator to use private: // PRIVATE MANIPULATORS @@ -162,10 +161,10 @@ class DomainResolver { /// return false and leave `out` untouched. Note that if the entry is /// found but has expired, this will erase it from the cache. /// - /// NOTE: - /// * `d_mutex` *MUST* be locked prior to calling this function, - /// * the caller must call `updateScriptTimestamp()` to update the - /// timestamps prior to calling this method. + /// @attention `d_mutex` *MUST* be locked prior to calling this function. + /// + /// @attention The caller must call `updateScriptTimestamp()` to update the + /// timestamps prior to calling this method. bool cacheLookup(mqbconfm::DomainResolver* out, const bslstl::StringRef& domainName); diff --git a/src/groups/mqb/mqba/mqba_sessionnegotiator.h b/src/groups/mqb/mqba/mqba_sessionnegotiator.h index adc966fc6..db9db9fee 100644 --- a/src/groups/mqb/mqba/mqba_sessionnegotiator.h +++ b/src/groups/mqb/mqba/mqba_sessionnegotiator.h @@ -17,33 +17,31 @@ #ifndef INCLUDED_MQBA_SESSIONNEGOTIATOR #define INCLUDED_MQBA_SESSIONNEGOTIATOR -//@PURPOSE: Provide a negotiator for establishing sessions. -// -//@CLASSES: -// mqba::SessionNegotiator: Negotiator for a BlazingMQ session with client or -// broker -// -//@DESCRIPTION: 'mqba::SessionNegotiator' implements the 'mqbnet::Negotiator' -// interface to negotiate a connection with a BlazingMQ client or another -// bmqbrkr. From a 'bmqio::Channel', it will exchange negotiation identity -// message, and create a session associated to the channel on success. -// -/// Thread Safety -///------------- -// The implementation must be thread safe as 'negotiate()' may be called -// concurrently from many IO threads. +/// @file mqba_sessionnegotiator.h +/// +/// @brief Provide a negotiator for establishing sessions. +/// +/// @bbref{mqba::SessionNegotiator} implements the @bbref{mqbnet::Negotiator} +/// interface to negotiate a connection with a BlazingMQ client or another +/// bmqbrkr. From a @bbref{bmqio::Channel}, it will exchange negotiation +/// identity message, and create a session associated to the channel on +/// success. +/// +/// Thread Safety {#mqba_sessionnegotiator_thread} +/// ============= +/// +/// The implementation must be thread safe as 'negotiate()' may be called +/// concurrently from many IO threads. // MQB - #include #include #include // BMQ -#include - #include #include +#include // BDE #include @@ -95,9 +93,9 @@ class SessionNegotiator : public mqbnet::Negotiator { private: // PRIVATE TYPES struct ConnectionType { + // Enum representing the type of session being negotiated, from that + // side of the connection's point of view. enum Enum { - // enum representing the type of session being negotiated, from - // that side of the connection's point of view e_UNKNOWN, e_CLUSTER_PROXY, e_CLUSTER_MEMBER, @@ -110,78 +108,65 @@ class SessionNegotiator : public mqbnet::Negotiator { /// negotiated struct NegotiationContext { // PUBLIC DATA + + /// The associated negotiatorContext, passed in by the caller. mqbnet::NegotiatorContext* d_negotiatorContext_p; - // The associated - // negotiatorContext, passed in by - // the caller + /// The channel to use for the negotiation. bsl::shared_ptr d_channelSp; - // The channel to use for the - // negotiation + /// The callback to invoke to notify of the status of the negotiation. mqbnet::Negotiator::NegotiationCb d_negotiationCb; - // The callback to invoke to - // notify of the status of the - // negotiation + /// The negotiation message received from the remote peer. bmqp_ctrlmsg::NegotiationMessage d_negotiationMessage; - // The negotiation message - // received from the remote peer + /// The cluster involved in the session being negotiated, or empty if + /// none. bsl::string d_clusterName; - // The cluster involved in the - // session being negotiated, or - // empty is none. + /// True if this is a "reversed" connection (on either side of the + /// connection). bool d_isReversed; - // True if this is a 'reversed' - // connection (on either side of - // the connection). + /// The type of the session being negotiated. ConnectionType::Enum d_connectionType; - // The type of the session being - // negotiated. }; typedef bsl::shared_ptr NegotiationContextSp; private: // DATA + + /// Allocator to use. bslma::Allocator* d_allocator_p; - // Allocator to use /// Buffer factory to use in constructed client sessions - /// TODO: this field should be removed once we retire the code for - /// message properties conversion in `mqba::ClientSession`. + /// + /// @todo This field should be removed once we retire the code for message + /// properties conversion in @bbref{mqba::ClientSession}. bdlbb::BlobBufferFactory* d_bufferFactory_p; + /// Dispatcher to inject into new client session.s mqbi::Dispatcher* d_dispatcher_p; - // Dispatcher to inject into new client - // sessions + /// Domain factory to inject into new client sessions. mqbi::DomainFactory* d_domainFactory_p; - // Domain factory to inject into new client - // sessions + /// Top-level stat context for all clients/queue stats. bmqst::StatContext* d_statContext_p; - // Top-level stat context for all - // clients/queues stats + /// Shared object pool of blobs to inject into new client sessions. BlobSpPool* d_blobSpPool_p; - // Shared object pool of blobs to inject - // into new client sessions + /// Cluster catalog to query for cluster information. mqbblp::ClusterCatalog* d_clusterCatalog_p; - // Cluster catalog to query for cluster - // information + /// Pointer to the event scheduler to use (held, not owned). bdlmt::EventScheduler* d_scheduler_p; - // Pointer to the event scheduler to - // use (held, not owned) + /// The callback to invoke on received admin command. mqbnet::Session::AdminCommandEnqueueCb d_adminCb; - // The callback to invoke on received - // admin command. private: // NOT IMPLEMENTED