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    MSTransportableDevice_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 "MSTransportableDevice.h"
      26             : 
      27             : 
      28             : // ===========================================================================
      29             : // class declarations
      30             : // ===========================================================================
      31             : class MSLane;
      32             : 
      33             : 
      34             : // ===========================================================================
      35             : // class definitions
      36             : // ===========================================================================
      37             : /**
      38             :  * @class MSTransportableDevice_Routing
      39             :  * @brief A device that performs person rerouting based on current edge speeds
      40             :  *
      41             :  * The routing-device system consists of in-vehicle devices that perform the routing
      42             :  *  and simulation-wide static methods for collecting edge weights and
      43             :  *  parallelizing in MSRoutingEngine.
      44             :  *
      45             :  * A device is assigned using the common explicit/probability - procedure.
      46             :  *
      47             :  * A device computes a new route for a person as soon as a personTrip appears in the plan.
      48             :  */
      49             : class MSTransportableDevice_Routing : public MSTransportableDevice {
      50             : public:
      51             :     /** @brief Inserts MSTransportableDevice_Routing-options
      52             :      * @param[filled] oc The options container to add the options to
      53             :      */
      54             :     static void insertOptions(OptionsCont& oc);
      55             : 
      56             :     /** @brief checks MSTransportableDevice_Routing-options
      57             :      * @param[filled] oc The options container with the user-defined options
      58             :      */
      59             :     static bool checkOptions(OptionsCont& oc);
      60             : 
      61             : 
      62             :     /** @brief Build devices for the given person, if needed
      63             :      *
      64             :      * The options are read and evaluated whether rerouting-devices shall be built
      65             :      *  for the given person.
      66             :      *
      67             :      * When the first device is built, the static container of edge weights
      68             :      *  used for routing is initialised with the mean speed the edges allow.
      69             :      *  In addition, an event is generated which updates these weights is
      70             :      *  built and added to the list of events to execute at a simulation end.
      71             :      *
      72             :      * The built device is stored in the given vector.
      73             :      *
      74             :      * @param[in] p The person for which a device may be built
      75             :      * @param[filled] into The vector to store the built device in
      76             :      */
      77             :     static void buildDevices(MSTransportable& p, std::vector<MSTransportableDevice*>& into);
      78             : 
      79             : 
      80             :     /// @brief Destructor.
      81             :     ~MSTransportableDevice_Routing();
      82             : 
      83             : 
      84             :     /// @brief return the name for this type of device
      85           0 :     const std::string deviceName() const {
      86           0 :         return "rerouting";
      87             :     }
      88             : 
      89             :     /** @brief Saves the state of the device
      90             :      *
      91             :      * @param[in] out The OutputDevice to write the information into
      92             :      */
      93             :     void saveState(OutputDevice& out) const;
      94             : 
      95             :     /** @brief Loads the state of the device from the given description
      96             :      *
      97             :      * @param[in] attrs XML attributes describing the current state
      98             :      */
      99             :     void loadState(const SUMOSAXAttributes& attrs);
     100             : 
     101             :     /// @brief initiate the rerouting, create router / thread pool on first use
     102             :     void reroute(const SUMOTime currentTime, const bool onInit = false);
     103             : 
     104             :     /// @brief try to retrieve the given parameter from this device. Throw exception for unsupported key
     105             :     std::string getParameter(const std::string& key) const;
     106             : 
     107             :     /// @brief try to set the given parameter for this device. Throw exception for unsupported key
     108             :     void setParameter(const std::string& key, const std::string& value);
     109             : 
     110             : 
     111             : private:
     112             : 
     113             :     /** @brief Constructor
     114             :      *
     115             :      * @param[in] holder The vehicle that holds this device
     116             :      * @param[in] id The ID of the device
     117             :      * @param[in] period The period with which a new route shall be searched
     118             :      */
     119             :     MSTransportableDevice_Routing(MSTransportable& holder, const std::string& id, SUMOTime period);
     120             : 
     121             :     /** @brief Performs rerouting after a period
     122             :      *
     123             :      * A new route is computed by calling the vehicle's "reroute" method, supplying
     124             :      *  "getEffort" as the edge effort retrieval method.
     125             :      *
     126             :      * This method is called from the event handler at the begin of a simulation
     127             :      *  step after the rerouting period is over. The reroute period is returned.
     128             :      *
     129             :      * @param[in] currentTime The current simulation time
     130             :      * @return The offset to the next call (the rerouting period "myPeriod")
     131             :      * @see MSVehicle::reroute
     132             :      * @see MSEventHandler
     133             :      * @see WrappingCommand
     134             :      */
     135             :     SUMOTime wrappedRerouteCommandExecute(SUMOTime currentTime);
     136             : 
     137             : 
     138             : private:
     139             :     /// @brief The period with which a vehicle shall be rerouted
     140             :     SUMOTime myPeriod;
     141             : 
     142             :     /// @brief The last time a routing took place
     143             :     SUMOTime myLastRouting;
     144             : 
     145             :     /// @brief The (optional) command responsible for rerouting
     146             :     WrappingCommand< MSTransportableDevice_Routing >* myRerouteCommand;
     147             : 
     148             : private:
     149             :     /// @brief Invalidated copy constructor.
     150             :     MSTransportableDevice_Routing(const MSTransportableDevice_Routing&);
     151             : 
     152             :     /// @brief Invalidated assignment operator.
     153             :     MSTransportableDevice_Routing& operator=(const MSTransportableDevice_Routing&);
     154             : 
     155             : 
     156             : };