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      1745473 :     Command() { }
      54              : 
      55              : 
      56              :     /// @brief Destructor.
      57          952 :     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          112 :     virtual SUMOTime shiftTime(SUMOTime /*currentTime*/, SUMOTime /*execTime*/, SUMOTime /*newTime*/) {
      84          112 :         return -1;
      85              :     }
      86              : 
      87              :     int priority = 0;
      88              : 
      89              : };