traci-manager.h

/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
 * Copyright (c) 2012 Fraunhofer ESK
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation;
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Author: Karsten Roscher <karsten.roscher@esk.fraunhofer.de>
 */
#ifndef TRACI_MANAGER_H
#define TRACI_MANAGER_H

#include <ns3/object.h>
#include <ns3/ptr.h>
#include <ns3/simple-ref-count.h>
#include <ns3/nstime.h>

#include "traci-types.h"
#include "traci-vehicle.h"

namespace ns3 {

class TraCi;

/*!
 * @brief Class managing simulation steps and arrival and departure of vehicles.
 *
 * The manager will schedule an update event for every simulation step and
 * inform handlers about arrived and departed vehicles.
 */
class TraCiManager : public Object {
public:
  static TypeId GetTypeId (void);

  TraCiManager ();
  ~TraCiManager ();

  void Start (Time when = Seconds (0));
  void Stop (Time when);

  //! Set TraCi instance to use.
  void SetTraCi (Ptr<TraCi> traci);

  //! Set time for one simulation step.
  void SetSimulationStep (Time step);

  /*!
   * @brief Enable/disable automatic time sync on start.
   *
   * This will adjust for an offset in times between ns-3 and SUMO in the
   * beginning in case SUMO was started with a custom beginning time.
   *
   * @param enabled	True to enable
   */
  void SetTimeSyncOnStart (bool enabled);

  /*!
   * @brief Enable/disable automatic departure of vehicles already running on start.
   *
   * This will help in case a simulation state was loaded and all vehicles
   * already on their way should be handles as well.
   *
   * @param enabled	True to enable
   */
  void SetDepartAlreadyRunningOnStart (bool enabled);

  /*!
   * @brief Enable/disable automatic detection of the simulation step size
   * @param enabled 	True to enable
   */
  void SetUseStepSizeFromTraciHost (bool enabled);

  /*!
   * @brief Base class for node departure/arrival handlers.
   *
   * Multiple handlers can be registered at the manager and will be
   * called in order of their priority. If a handler took care of a
   * vehicle (HandleDeparture returned true) the process will stop.
   *
   * HandleArrival will be called for all registered handlers, even if
   * they did not indicate that the took care of the object. This allows
   * multiple handlers to track the lifetime of a vehicle even if they
   * do not want to terminate further mapping.
   */
  class VehicleHandler : public SimpleRefCount<VehicleHandler>
  {
  public:
    virtual ~VehicleHandler () {}

    /*!
     * @brief Handle the departure of a vehicle.
     * @param vehicle	Departed vehicle
     * @return True if this handler took care of the vehicle.
     */
    virtual bool HandleDeparture (Ptr<traci::Vehicle> vehicle) = 0;

    /*!
     * @brief Handle the arrival of a vehicle.
     * @param vehicleId Id of the arrived vehicle
     */
    virtual void HandleArrival (std::string vehicleId) = 0;

    /*!
     * @brief Handle the execution of a simulation step
     *
     * This will be invoked after a simulation step executed by the
     * remote TraCI instance. It is not mandatory to implement this.
     */
    virtual void HandleSimulationStep (Ptr<TraCi> traci) {}

  };


  /*!
   * @brief Add a vehicle handler with the provided priority.
   *
   * Higher values mean a higher priority. The order of invocation
   * for handlers with the same priority is undefined.
   *
   * @param handler   Handler to add.
   * @param priority  Priority for the handler.
   */
  void AddHandler (Ptr<VehicleHandler> handler, int priority);

  /*!
   * @brief Remove the provided handler.
   * @param handler   Handler to remove.
   */
  void RemoveHandler (Ptr<VehicleHandler> handler);

private:

  void DoStart ();
  void DoStop ();

  /*!
   * @brief Execute a simulation step (will be invoked as event callback).
   */
  void ExecuteSimulationStep ();

  /*!
   * @brief Update available nodes.
   */
  void UpdateAvailableNodes ();


  /*!
   * @brief Handle arrived vehicles.
   * @param arrived List of identifiers of arrived vehicles.
   */
  void HandleArrivedVehicles (const traci::StringList& arrived);

  /*!
   * @brief Handle a single arrived vehicle
   * @param objectId	Id of the arrived vehicle
   */
  void HandleArrivedVehicle (std::string objectId);

  /*!
   * @brief Handle departed vehicles.
   * @param departed List of identifiers of departed vehicles.
   */
  void HandleDepartedVehicles (const traci::StringList& departed);

  /*!
   * @brief Handle a single departed vehicle
   * @param objectId	Id of the departed vehicle
   * @return True if the vehicle found a handler
   */
  bool HandleDepartedVehicle (std::string objectId);

  //! Time for one simulation step
  Time m_simulationStep;

  //! Flag indicating if the time should be synced on start.
  bool m_syncTimeOnStart;

  //! Flag indicating if nodes already running at the beginning should be treated as departed now.
  bool m_departAlreadyRunningOnStart;

  //! Flag indicating if the step size of the traci host should be used
  bool m_useStepSizeFromTraciHost;

  //! Time SUMO is ahead of ns-3
  Time m_sumoOffset;

  //! Traci instance used.
  Ptr<TraCi> m_traci;

  //! Event for a simulation step
  EventId m_simulationEvent;

  EventId m_startEvent;
  EventId m_stopEvent;

  //! A vehicle handler entry consisting of a priority and a pointer to the handler.
  typedef std::pair<int, Ptr<VehicleHandler> > HandlerEntry;
  typedef std::vector<HandlerEntry> HandlerList;
  HandlerList m_handlers;
};



/*!
 * @brief A simple vehicle handler providing a callback based interface.
 *
 * If you prefer using callbacks, you can use this handler. It will
 * forward the requests to the provided callbacks.
 */
class CallbackVehicleHandler : public TraCiManager::VehicleHandler
{
public:
  virtual bool HandleDeparture (Ptr<traci::Vehicle> vehicle);
  virtual void HandleArrival (std::string vehicleId);

  typedef Callback<bool, Ptr<traci::Vehicle> > DepartureCallback;
  typedef Callback<void, std::string> ArrivalCallback;

  void SetArrivalCallback (ArrivalCallback cb);
  void SetDepartureCallback (DepartureCallback cb);

private:
  ArrivalCallback m_arrived;
  DepartureCallback m_departed;
};



}  // namespace ns3


#endif