Line data    Source code

       1             : /****************************************************************************/
       2             : // Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
       3             : // Copyright (C) 2001-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    Command.h
      15             : /// @author  Christian Roessel
      16             : /// @author  Daniel Krajzewicz
      17             : /// @date    Thu, 20 Dec 2001
      18             : ///
      19             : // Base (microsim) event class
      20             : /****************************************************************************/
      21             : #pragma once
      22             : #include <config.h>
      23             : #include <utils/common/SUMOTime.h>
      24             : #include <utils/common/UtilExceptions.h>
      25             : 
      26             : 
      27             : // ===========================================================================
      28             : // class definitions
      29             : // ===========================================================================
      30             : /**
      31             :  * @class Command
      32             :  * @brief Base (microsim) event class
      33             :  *
      34             :  * Classes derived from Command may be added to MSEventControl instances in
      35             :  *  order to be executed at a certain time step.
      36             :  *
      37             :  * As soon as the simulation reaches the desired time step, the command (event)
      38             :  *  is executed by calling "execute" with the current time step. The method must
      39             :  *  return either 0, if the event shall not be executed again or a positive value
      40             :  *  (in simulation seconds) that described when it shall be executed again. The method
      41             :  *  must not return a value below zero, the behaviour is undefined in this case.
      42             :  *
      43             :  * @warning The EventControl the Command is added to gets responsible for
      44             :  *  this command's deletion.
      45             :  *
      46             :  * @see Design Patterns, Gamma et al.
      47             :  * @see WrappingCommand
      48             :  * @see MSEventControl
      49             :  */
      50             : class Command {
      51             : public:
      52             :     /// @brief Constructor
      53     1838042 :     Command() { }
      54             : 
      55             : 
      56             :     /// @brief Destructor.
      57         567 :     virtual ~Command() { }
      58             : 
      59             : 
      60             :     /** @brief Executes the command.
      61             :      *
      62             :      * The implementations should return 0 if the command shall not be repeated,
      63             :      *  or a value larger than 0 that describe the time after which the command
      64             :      *  shall be executed again. Values below 0 must not be returned.
      65             :      *
      66             :      * @param[in] currentTime The current simulation time
      67             :      * @return The time after which the command shall be executed again, 0 if this command shall be descheduled.
      68             :      * @exception ProcessError Derived actions may throw this exception
      69             :      */
      70             :     virtual SUMOTime execute(SUMOTime currentTime) = 0;
      71             : 
      72             :     /** @brief Reschedule or deschedule the command when quick-loading state
      73             :      *
      74             :      * The implementations should return -1 if the command shall not be re-scheduled,
      75             :      *  or a value >= 0 that describe the new time at which the command
      76             :      *  shall be executed again.
      77             :      *
      78             :      * @param[in] currentTime The current simulation time
      79             :          * @param[in] execTime The time at which the command would have been executed
      80             :      * @param[in] newTime The simulation time at which the simulation is restarted
      81             :      * @return The time at which the command shall be executed again
      82             :      */
      83         128 :     virtual SUMOTime shiftTime(SUMOTime /*currentTime*/, SUMOTime /*execTime*/, SUMOTime /*newTime*/) {
      84         128 :         return -1;
      85             :     }
      86             : 
      87             :     int priority = 0;
      88             : 
      89             : };