[traffic] Restore and document enable/disable/pause/resume logic

Signed-off-by: mvglasow <michael -at- vonglasow.com>

map/traffic_manager.cpp

@@ -334,7 +334,7 @@ void TrafficManager::OnChangeRoutingSessionState(routing::SessionState previous,
 
 void TrafficManager::RecalculateSubscription()
 {
-  if (!IsEnabled())
+  if (!IsEnabled() || m_isPaused)
     return;
 
   if (m_currentModelView.second)
@@ -353,7 +353,7 @@ void TrafficManager::RecalculateSubscription()
     if (m_activeMwmsChanged)
     {
       if ((m_activeDrapeMwms.empty() && m_activePositionMwms.empty() && m_activeRoutingMwms.empty())
-          || IsInvalidState() || m_isPaused)
+          || IsInvalidState())
         return;
 
       m_condition.notify_one();
@@ -725,7 +725,7 @@ void TrafficManager::ThreadRoutine()
 
   while (WaitForRequest())
   {
-    if (!IsEnabled())
+    if (!IsEnabled() || m_isPaused)
       continue;
 
     /*
@@ -824,7 +824,7 @@ bool TrafficManager::WaitForRequest()
   if (!m_isRunning)
     return false;
 
-  if (IsEnabled())
+  if (IsEnabled() && !m_isPaused)
   {
     // if we have feeds in the queue, return immediately
     if (!m_feedQueue.empty())
@@ -859,7 +859,7 @@ bool TrafficManager::WaitForRequest()
     return false;
 
   // this works as long as wait timeout is at least equal to the poll interval
-  if (IsEnabled())
+  if (IsEnabled() && !m_isPaused)
     m_isPollNeeded |= timeout;
 
   LOG(LINFO, ("timeout:", timeout, "active MWMs changed:", m_activeMwmsChanged, "test mode:", IsTestMode()));

map/traffic_manager.hpp

@@ -141,12 +141,13 @@ public:
    *
    * This sets the internal state and notifies the drape engine.
    *
-   * Upon creation, the traffic manager is disabled and will not poll any sources or process any
+   * Upon creation, the traffic manager is disabled. MWMs must be loaded before first enabling the
-   * feeds until enabled. Feeds received through `Push()` will be added to the queue before the
+   * traffic manager.
-   * traffic manager is started, but will not be processed any further until the traffic manager is
-   * started.
    *
-   * MWMs must be loaded before first enabling the traffic manager.
+   * While disabled, the traffic manager will not update its subscription area (upon being enabled
+   * again, it will do so if necessary). It will not poll any sources or process any messages. Feeds
+   * added via `ReceiveFeed()` will be added to the queue but will not be processed until the
+   * traffic manager is re-enabled.
    *
    * Calling this function with `enabled` identical to the current state is a no-op.
    *
@@ -154,8 +155,6 @@ public:
    * that will not get picked up. We need to extend `TrafficManager` to react to MWMs being added
    * (and removed) – note that this affects the `DataSource`, not the set of active MWMs.
    *
-   * @todo State/pause/resume logic is not fully implemented ATM and needs to be revisited.
-   *
    * @param enabled True to enable, false to disable
    */
   void SetEnabled(bool enabled);
@@ -561,7 +560,34 @@ private:
    */
   void UniteActiveMwms(std::set<MwmSet::MwmId> & activeMwms) const;
 
+  /**
+   * @brief Pauses the traffic manager.
+   *
+   * Upon creation, the traffic manager is not paused.
+   *
+   * While paused, the traffic manager will not update its subscription area (upon being enabled
+   * again, it will do so if necessary). It will not poll any sources or process any messages. Feeds
+   * added via `ReceiveFeed()` will be added to the queue but will not be processed until the
+   * traffic manager is resumed.
+   *
+   * Pausing and resuming is similar in effect to disabling and enabling the traffic manager, except
+   * it does not change the external state. It is intended for internal use by the framework.
+   */
   void Pause();
+
+  /**
+   * @brief Resumes the traffic manager.
+   *
+   * Upon creation, the traffic manager is not paused. Resuming a traffic manager that is not paused
+   * is a no-op.
+   *
+   * Upon resume, the traffic manager will recalculate its subscription area and change its
+   * subscription if necessary. It will continue processing feeds in the queue, including those
+   * received before or while the traffic manager was paused.
+   *
+   * Pausing and resuming is similar in effect to disabling and enabling the traffic manager, except
+   * it does not change the external state. It is intended for internal use by the framework.
+   */
   void Resume();
 
   template <class F>