Line data    Source code

       1             : /****************************************************************************/
       2             : // Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
       3             : // Copyright (C) 2007-2024 German Aerospace Center (DLR) and others.
       4             : // This program and the accompanying materials are made available under the
       5             : // terms of the Eclipse Public License 2.0 which is available at
       6             : // https://www.eclipse.org/legal/epl-2.0/
       7             : // This Source Code may also be made available under the following Secondary
       8             : // Licenses when the conditions for such availability set forth in the Eclipse
       9             : // Public License 2.0 are satisfied: GNU General Public License, version 2
      10             : // or later which is available at
      11             : // https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html
      12             : // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
      13             : /****************************************************************************/
      14             : /// @file    MSDevice_Routing.h
      15             : /// @author  Michael Behrisch
      16             : /// @author  Daniel Krajzewicz
      17             : /// @author  Jakob Erdmann
      18             : /// @date    Tue, 04 Dec 2007
      19             : ///
      20             : // A device that performs vehicle rerouting based on current edge speeds
      21             : /****************************************************************************/
      22             : #pragma once
      23             : #include <config.h>
      24             : 
      25             : #include <set>
      26             : #include <vector>
      27             : #include <map>
      28             : #include <utils/common/SUMOTime.h>
      29             : #include <utils/common/WrappingCommand.h>
      30             : #include <microsim/MSVehicle.h>
      31             : #include "MSVehicleDevice.h"
      32             : 
      33             : 
      34             : // ===========================================================================
      35             : // class declarations
      36             : // ===========================================================================
      37             : class MSLane;
      38             : 
      39             : 
      40             : // ===========================================================================
      41             : // class definitions
      42             : // ===========================================================================
      43             : /**
      44             :  * @class MSDevice_Routing
      45             :  * @brief A device that performs vehicle rerouting based on current edge speeds
      46             :  *
      47             :  * The routing-device system consists of in-vehicle devices that perform the routing
      48             :  *  and simulation-wide static methods for collecting edge weights and
      49             :  *  parallelizing in MSRoutingEngine.
      50             :  *
      51             :  * A device is assigned to a vehicle using the common explicit/probability - procedure.
      52             :  *
      53             :  * A device computes a new route for a vehicle as soon as the vehicle is inserted
      54             :  *  (within "enterLaneAtInsertion") - and, if the given period is larger than 0 - each
      55             :  *  x time steps where x is the period. This is triggered by an event that executes
      56             :  *  "wrappedRerouteCommandExecute".
      57             :  */
      58             : class MSDevice_Routing : public MSVehicleDevice {
      59             : public:
      60             :     /** @brief Inserts MSDevice_Routing-options
      61             :      * @param[filled] oc The options container to add the options to
      62             :      */
      63             :     static void insertOptions(OptionsCont& oc);
      64             : 
      65             :     /** @brief checks MSDevice_Routing-options
      66             :      * @param[filled] oc The options container with the user-defined options
      67             :      */
      68             :     static bool checkOptions(OptionsCont& oc);
      69             : 
      70             : 
      71             :     /** @brief Build devices for the given vehicle, if needed
      72             :      *
      73             :      * The options are read and evaluated whether rerouting-devices shall be built
      74             :      *  for the given vehicle.
      75             :      *
      76             :      * When the first device is built, the static container of edge weights
      77             :      *  used for routing is initialised with the mean speed the edges allow.
      78             :      *  In addition, an event is generated which updates these weights is
      79             :      *  built and added to the list of events to execute at a simulation end.
      80             :      *
      81             :      * The built device is stored in the given vector.
      82             :      *
      83             :      * @param[in] v The vehicle for which a device may be built
      84             :      * @param[filled] into The vector to store the built device in
      85             :      */
      86             :     static void buildVehicleDevices(SUMOVehicle& v, std::vector<MSVehicleDevice*>& into);
      87             : 
      88             : 
      89             :     /// @brief Destructor.
      90             :     ~MSDevice_Routing();
      91             : 
      92             : 
      93             : 
      94             :     /// @name Methods called on vehicle movement / state change, overwriting MSDevice
      95             :     /// @{
      96             : 
      97             :     /** @brief Computes a new route on vehicle insertion
      98             :      *
      99             :      * A new route is computed by calling the vehicle's "reroute" method, supplying
     100             :      *  "getEffort" as the edge effort retrieval method.
     101             :      *
     102             :      * If the reroute period is larger than 0, an event is generated and added
     103             :      *  to the list of simulation step begin events which executes
     104             :      *  "wrappedRerouteCommandExecute".
     105             :      *
     106             :      * @param[in] veh The entering vehicle.
     107             :      * @param[in] reason how the vehicle enters the lane
     108             :      * @return Always false
     109             :      * @see MSMoveReminder::notifyEnter
     110             :      * @see MSMoveReminder::Notification
     111             :      * @see MSVehicle::reroute
     112             :      * @see MSEventHandler
     113             :      * @see WrappingCommand
     114             :      */
     115             :     bool notifyEnter(SUMOTrafficObject& veh, MSMoveReminder::Notification reason, const MSLane* enteredLane = 0);
     116             : 
     117             :     /// @brief called to do the rerouting we missed whuile stopping
     118             :     void notifyStopEnded();
     119             : 
     120             :     /// @}
     121             : 
     122             :     /// @brief return the name for this type of device
     123        4368 :     const std::string deviceName() const {
     124        4368 :         return "rerouting";
     125             :     }
     126             : 
     127             :     /** @brief Saves the state of the device
     128             :      *
     129             :      * @param[in] out The OutputDevice to write the information into
     130             :      */
     131             :     void saveState(OutputDevice& out) const;
     132             : 
     133             :     /** @brief Loads the state of the device from the given description
     134             :      *
     135             :      * @param[in] attrs XML attributes describing the current state
     136             :      */
     137             :     void loadState(const SUMOSAXAttributes& attrs);
     138             : 
     139             :     /// @brief initiate the rerouting, create router / thread pool on first use
     140             :     void reroute(const SUMOTime currentTime, const bool onInit = false);
     141             : 
     142             : 
     143             :     /** @brief Labels the current time step as "unroutable".
     144             :      *
     145             :      * Sets mySkipRouting to the current time in order to skip rerouting.
     146             :      * This is useful for pre insertion routing when we know in advance
     147             :      * we cannot insert.
     148             :      *
     149             :      * @param[in] currentTime The current simulation time
     150             :      */
     151             :     void skipRouting(const SUMOTime currentTime) {
     152    62439177 :         mySkipRouting = currentTime;
     153    62439177 :     }
     154             : 
     155             :     SUMOTime getPeriod() const {
     156        7596 :         return myPeriod;
     157             :     }
     158             : 
     159             :     /// @brief return whether the equipped vehicle may receive dispatch information at a rail signal
     160             :     bool mayRerouteRailSignal() const {
     161       11215 :         return myRerouteRailSignal;
     162             :     }
     163             : 
     164             :     /// @brief try to retrieve the given parameter from this device. Throw exception for unsupported key
     165             :     std::string getParameter(const std::string& key) const;
     166             : 
     167             :     /// @brief try to set the given parameter for this device. Throw exception for unsupported key
     168             :     void setParameter(const std::string& key, const std::string& value);
     169             : 
     170             :     void setActive(bool active) {
     171      171448 :         myActive = active;
     172      171448 :     }
     173             : 
     174             : private:
     175             : 
     176             :     /** @brief Constructor
     177             :      *
     178             :      * @param[in] holder The vehicle that holds this device
     179             :      * @param[in] id The ID of the device
     180             :      * @param[in] period The period with which a new route shall be searched
     181             :      * @param[in] preInsertionPeriod The route search period before insertion
     182             :      */
     183             :     MSDevice_Routing(SUMOVehicle& holder, const std::string& id, SUMOTime period, SUMOTime preInsertionPeriod);
     184             : 
     185             :     /** @brief Performs rerouting before insertion into the network
     186             :      *
     187             :      * A new route is computed by calling the reroute method. If the routing
     188             :      *  involves taz the internal route cache is asked beforehand.
     189             :      *
     190             :      * @param[in] currentTime The current simulation time
     191             :      * @return The offset to the next call (the rerouting period "myPreInsertionPeriod")
     192             :      * @see MSVehicle::reroute
     193             :      * @see MSEventHandler
     194             :      * @see WrappingCommand
     195             :      */
     196             :     SUMOTime preInsertionReroute(const SUMOTime currentTime);
     197             : 
     198             :     /** @brief Performs rerouting after a period
     199             :      *
     200             :      * A new route is computed by calling the vehicle's "reroute" method, supplying
     201             :      *  "getEffort" as the edge effort retrieval method.
     202             :      *
     203             :      * This method is called from the event handler at the begin of a simulation
     204             :      *  step after the rerouting period is over. The reroute period is returned.
     205             :      *
     206             :      * @param[in] currentTime The current simulation time
     207             :      * @return The offset to the next call (the rerouting period "myPeriod")
     208             :      * @see MSVehicle::reroute
     209             :      * @see MSEventHandler
     210             :      * @see WrappingCommand
     211             :      */
     212             :     SUMOTime wrappedRerouteCommandExecute(SUMOTime currentTime);
     213             : 
     214             :     /// @brief rebuild reroute command according to period
     215             :     void rebuildRerouteCommand();
     216             : 
     217             : private:
     218             :     /// @brief The period with which a vehicle shall be rerouted
     219             :     SUMOTime myPeriod;
     220             : 
     221             :     /// @brief The period with which a vehicle shall be rerouted before insertion
     222             :     SUMOTime myPreInsertionPeriod;
     223             : 
     224             :     /// @brief The last time a routing took place
     225             :     SUMOTime myLastRouting;
     226             : 
     227             :     /// @brief The time for which routing may be skipped because we cannot be inserted
     228             :     SUMOTime mySkipRouting;
     229             : 
     230             :     /// @brief The (optional) command responsible for rerouting
     231             :     WrappingCommand< MSDevice_Routing >* myRerouteCommand;
     232             : 
     233             :     /// @brief Whether the equipped vehicle may receive dispatch information at a rail signal
     234             :     bool myRerouteRailSignal;
     235             : 
     236             :     /// @brief the previous time that a vehicle entered a lane
     237             :     SUMOTime myLastLaneEntryTime;
     238             : 
     239             :     /// @brief Whether the equipped vehicle missed a reroute while stopping and should do so after the stop has ended
     240             :     bool myRerouteAfterStop;
     241             : 
     242             :     /// @brief Whether the equipped vehicle may perform rerouting
     243             :     bool myActive;
     244             : 
     245             : private:
     246             :     /// @brief Invalidated copy constructor.
     247             :     MSDevice_Routing(const MSDevice_Routing&);
     248             : 
     249             :     /// @brief Invalidated assignment operator.
     250             :     MSDevice_Routing& operator=(const MSDevice_Routing&);
     251             : 
     252             : 
     253             : };