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 3845 : const std::string deviceName() const {
124 3845 : 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 38390108 : mySkipRouting = currentTime;
153 38390108 : }
154 :
155 : SUMOTime getPeriod() const {
156 153 : return myPeriod;
157 : }
158 :
159 : /// @brief return whether the equipped vehicle may receive dispatch information at a rail signal
160 : bool mayRerouteRailSignal() const {
161 131601 : 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 184183 : myActive = active;
172 184183 : }
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 : };
|
