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      1570571 :     WrappingCommand(T* receiver, Operation operation)
      63      1570571 :         : myReceiver(receiver), myOperation(operation),
      64      1570571 :           myAmDescheduledByParent(false) {}
      65              : 
      66              : 
      67              :     /// @brief Destructor
      68      1570556 :     ~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       216708 :         myAmDescheduledByParent = true;
      78       302287 :     }
      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     15769807 :     SUMOTime execute(SUMOTime currentTime) {
      99              :         // do not execute if the command was descheduled
     100     15769807 :         if (myAmDescheduledByParent) {
     101              :             return 0;
     102              :         }
     103              :         // execute if stil valid
     104     15297095 :         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              : };