1 /****************************************************************************/
2 // Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.org/sumo
3 // Copyright (C) 2001-2019 German Aerospace Center (DLR) and others.
4 // This program and the accompanying materials
5 // are made available under the terms of the Eclipse Public License v2.0
6 // which accompanies this distribution, and is available at
7 // http://www.eclipse.org/legal/epl-v20.html
8 // SPDX-License-Identifier: EPL-2.0
9 /****************************************************************************/
10 /// @file    MSEventControl.h
11 /// @author  Christian Roessel
12 /// @author  Daniel Krajzewicz
13 /// @author  Michael Behrisch
14 /// @author  Matthias Heppner
15 /// @date    Mon, 12 Mar 2001
16 /// @version $Id$
17 ///
18 // Stores time-dependant events and executes them at the proper time
19 /****************************************************************************/
20 #ifndef MSEventControl_h
21 #define MSEventControl_h
22 
23 
24 // ===========================================================================
25 // included modules
26 // ===========================================================================
27 #include <config.h>
28 
29 #include <utility>
30 #include <queue>
31 #include <vector>
32 #include <map>
33 #include <utils/common/SUMOTime.h>
34 #include <utils/common/UtilExceptions.h>
35 
36 
37 // ===========================================================================
38 // class declarations
39 // ===========================================================================
40 class Command;
41 
42 
43 // ===========================================================================
44 // class definitions
45 // ===========================================================================
46 /**
47  * @class MSEventControl
48  * @brief Stores time-dependant events and executes them at the proper time
49  */
50 class MSEventControl {
51 public:
52     /// @brief Combination of an event and the time it shall be executed at
53     typedef std::pair< Command*, SUMOTime > Event;
54 
55 
56 public:
57     /// @brief Default constructor.
58     MSEventControl();
59 
60 
61     /// @brief Destructor.
62     virtual ~MSEventControl();
63 
64 
65     /** @brief Adds an Event.
66      *
67      * @param[in] operation The event to add
68      * @param[in] execTimeStep The time the event shall be executed at (-1 means at sim start)
69      * @see Command
70      */
71     virtual void addEvent(Command* operation, SUMOTime execTimeStep = -1);
72 
73 
74     /** @brief Executes time-dependant commands
75      *
76      * Loops over all stored events, continuing until the first event which
77      *  execution time lies beyond the given time + deltaT. If the event
78      *  had to be executed before the given time, a warning is generated and
79      *  the event deleted. Otherwise (the event is valid), the event is executed.
80      *
81      * Each executed event must return the time that has to pass until it shall
82      *  be executed again. If the returned time is 0, the event is deleted.
83      *  Otherwise it is readded, after the new execution time (returned + current)
84      *  is computed.
85      *
86      * ProcessErrors thrown by executed commands are rethrown.
87      *
88      * @param[in] time The current simulation time
89      * @exception ProcessError From an executed Command
90      */
91     virtual void execute(SUMOTime time);
92 
93 
94     /** @brief Returns whether events are in the que.
95      *
96      * @return  whether events are in the que
97      */
98     bool isEmpty();
99 
100 
101     /** @brief Set the current Time.
102      *
103      * This method is only for Unit Testing.
104      * Set the current TimeStep used in addEvent.
105      * Normally the time is set automatically from an instance of MSNet.
106      */
107     void setCurrentTimeStep(SUMOTime time);
108 
109 
110 protected:
111     /** @brief Sort-criterion for events.
112      *
113      * Sorts events by their execution time
114      */
115     class EventSortCrit {
116     public:
117         /// @brief compares two events
operator()118         bool operator()(const Event& e1, const Event& e2) const {
119             return e1.second > e2.second;
120         }
121     };
122 
123 
124 private:
125     /// @brief Container for time-dependant events, e.g. traffic-light-change.
126     typedef std::priority_queue< Event, std::vector< Event >, EventSortCrit > EventCont;
127 
128     /// The current TimeStep
129     SUMOTime currentTimeStep;
130 
131     /// @brief Event-container, holds executable events.
132     EventCont myEvents;
133 
134     /// get the Current TimeStep used in addEvent.
135     SUMOTime getCurrentTimeStep();
136 
137 
138 private:
139     /// @brief invalid copy constructor.
140     MSEventControl(const MSEventControl&);
141 
142     /// @brief invalid assignment operator.
143     MSEventControl& operator=(const MSEventControl&);
144 
145 
146 };
147 
148 
149 #endif
150 
151 /****************************************************************************/
152 
153