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    WrappingCommand.h
      15             : /// @author  Christian Roessel
      16             : /// @author  Daniel Krajzewicz
      17             : /// @date    Thu, 20 Dec 2001
      18             : ///
      19             : // A wrapper for a Command function
      20             : /****************************************************************************/
      21             : #pragma once
      22             : #include <config.h>
      23             : #include "Command.h"
      24             : 
      25             : 
      26             : // ===========================================================================
      27             : // class definition
      28             : // ===========================================================================
      29             : /**
      30             :  * @class WrappingCommand
      31             :  * @brief A wrapper for a Command function
      32             :  *
      33             :  * In order to ease life, this class may encapsulate a method of a class which
      34             :  *  in order to be used as a Command. This allows to use a member methods
      35             :  *  of a class to be called as Commands are, avoiding that the instance itself
      36             :  *  is destroyed by the EventHandler.
      37             :  *
      38             :  * Because in some cases, the Command may live longer than the instance class,
      39             :  *  a boolean value indicates that the Command is "descheduled". It should
      40             :  *  be set via "deschedule" as soon as the class instance of which a method
      41             :  *  is encapsulated is destroyed and forces that the command (calling of this
      42             :  *  instace's method) is not executed.
      43             :  *
      44             :  * @see Design Patterns, Gamma et al.
      45             :  * @see Command
      46             :  * @see MSEventControl
      47             :  */
      48             : template< class T  >
      49             : class WrappingCommand : public Command {
      50             : public:
      51             :     /// @brief Type of the function to execute.
      52             :     typedef SUMOTime(T::* Operation)(SUMOTime);
      53             : 
      54             : 
      55             : public:
      56             :     /**
      57             :      * @brief Constructor.
      58             :      *
      59             :      * @param[in] receiver Pointer to object of type T that will receive a call to one of its methods.
      60             :      * @param[in] operation The objects' method that will be called on execute()
      61             :      */
      62     1683122 :     WrappingCommand(T* receiver, Operation operation)
      63     1683122 :         : myReceiver(receiver), myOperation(operation),
      64     1683122 :           myAmDescheduledByParent(false) {}
      65             : 
      66             : 
      67             :     /// @brief Destructor
      68     1683100 :     ~WrappingCommand() {}
      69             : 
      70             : 
      71             :     /** @brief Marks this Command as being descheduled
      72             :      *
      73             :      * A simple boolean marker ("myAmDescheduledByParent") is set which
      74             :      *  prevents this command from being executed.
      75             :      */
      76             :     void deschedule() {
      77      351169 :         myAmDescheduledByParent = true;
      78       61471 :     }
      79             : 
      80             :     /// @brief whether this command has been descheduled
      81             :     bool isDescheduled() {
      82             :         return myAmDescheduledByParent;
      83             :     }
      84             : 
      85             : 
      86             :     /// @name Derived from Command
      87             :     /// @{
      88             : 
      89             :     /** @brief Executes the command.
      90             :      *
      91             :      * If the command is not descheduled, the stored method of the stored instance
      92             :      *  is called.
      93             :      *
      94             :      * @param[in] currentTime The current simulation time
      95             :      * @return The time after which the command shall be executed again, 0 if this command shall be descheduled.
      96             :      * @exception ProcessError Derived actions may throw this exception
      97             :      */
      98    15911369 :     SUMOTime execute(SUMOTime currentTime) {
      99             :         // do not execute if the command was descheduled
     100    15911369 :         if (myAmDescheduledByParent) {
     101             :             return 0;
     102             :         }
     103             :         // execute if stil valid
     104    15504871 :         return (myReceiver->*myOperation)(currentTime);
     105             :     }
     106             :     /// @}
     107             : 
     108             : 
     109             : private:
     110             :     /// @brief The object the action is directed to.
     111             :     T* myReceiver;
     112             : 
     113             :     /// @brief The object's operation to perform.
     114             :     Operation myOperation;
     115             : 
     116             :     /// @brief Whether this command was descheduled (is invalid) and shall not be executed
     117             :     bool myAmDescheduledByParent;
     118             : 
     119             : 
     120             : };