6.3. PropertySlot

6.3.1. What is PropertySlot

PropertySlot is a pair of methods to access (get) and mutate (set) an object property, associated with the name of the property. Values of the object property can either be stored in a member variable of the object, or dynamically created when the methods are called.

All of the four DM base classes, Process, Variable, System and Stepper can have a set of PropertySlots, or object properties. In other words, these classes inherit PropertyInterface common base class.

6.3.1.1. What is PropertySlot for?

PropertySlots can be used from model files (such as EM files) as a means of giving parameter values to each objects in the simulation model (such as Entity and Stepper objects). It can also be ways of dynamic communications between objects during the simulation.

6.3.1.2. Type of PropertySlot

A type of a PropertySlot is any one of these four types:

  • Real

  • Integer

  • String

  • Polymorph

6.3.2. How to define a PropertySlot

To define a PropertySlot on an object class, you have to:

  1. Define set and/or get method(s).

  2. If necessary, define a member variable to store the property value.

  3. Register the method(s) as a PropertySlot.

6.3.2.1. Set method and get method

A PropertySlot is a pair of object methods, set method and get method, associated with a property name. Either one of the methods can be ommited. If there is a set method defined for a PropertySlot, the PropertySlot is said to be setable. If there is a get method, it is getable.

A set method must have the following signature to be recognized by the system.

void CLASS::* ( const T&)
And a get method must look like this:
const T	CLASS::* ( void ) const
where T is a property type and CLASS is the object class that the PropertySlot belongs to.

Don't worry, you don't need to memorize these prototypes. The following four macoros can be used to declare and define set/get methods of a specific type and a property name.

  • SET_METHOD( TYPE, NAME )

    • Expansion:

      void setNAME( const TYPE&value )

    • Usage: SET_METHOD macro is used to declare or define a property set method, of which the property type is TYPE and the property name is NAME, in a class scope (class definition). The given property value is available as the value argument variable.

    • Example:

      This code:

      class HogeProcess
      {
        SET_METHOD( Real, Flux )
        {
          theFlux = value;
        }
      
        Real theFlux;
      };
      is expanded to the following valid C++ program.
      class HogeProcess
      {
        void setFlux( const Real&value )
        {
          theFlux = value;
        }
      
        Real theFlux;
      };
      
      In this example, the given property value is stored in the member variable theFlux.

  • GET_METHOD( TYPE, NAME )

    • Expansion:

      const TYPE getNAME() const

    • Usage: GET_METHOD macro is used to declare or define a property get method, of which the property type is TYPE and the property name is NAME, in a class scope (class definition). Definition of the method must return the value of the property as a TYPE object.

    • Example:

      This code:

      class HogeProcess
      {
        GET_METHOD( Real, Flux )
        {
          return theFlux;
        }
      
        Real theFlux;
      };
      is expanded to the following valid C++ program.
      class HogeProcess
      {
        const Real getFlux() const
        {
          return theFlux;
        }
      
        Real theFlux;
      };
      

  • SET_METHOD_DEF( TYPE, NAME, CLASSNAME )

    • Expansion:

      void CLASSNAME::setNAME( const TYPE&value )

    • Usage: SET_METHOD_DEF macro is used to define a property set method outside class scope.

    • Example:

      SET_METHOD_DEF macro is usually used in conjunction with SET_METHOD macro. For instance, the following code declares a property get method in the class scope by using SET_METHOD, and defines the procedure of the method after the class definition with SET_METHOD_DEF. In this example, the method is virtual.

      class HogeProcess
      {
        virtual SET_METHOD( Real, Flux );
      
        Real theFlux;
      };
      
      SET_METHOD_DEF( Real, Flux, HogeProcess )
      {
        return theFlux;  
      }
      

  • GET_METHOD_DEF( TYPE, NAME, CLASSNAME )

    • Expansion:

      const TYPE CLASSNAME::getNAME() const

    • Usage: GET_METHOD_DEF macro is used to define a property get method outside class scope.

    • Example: See the example of SET_METHOD_DEF above.

If the property is both setable and getable, and is simply stored in a member variable, the following macro can be used.

SIMPLE_SET_GET_METHOD( NAME, TYPE )
This assumes there is a variable with the same name as the property name (NAME), and expands to a code that is equivalent to:
SET_METHOD( NAME, TYPE )
{
  NAME = value;
}

GET_METHOD( NAME, TYPE )
{
  return NAME;
}

6.3.2.2. Registering PropertySlots

To register a PropertySlot on a class, one of these macros in the LIBECS_DM_OBJECT macro of the target class:

  • PROPERTYSLOT_SET_GET( NAME, TYPE )

    Use this if the property is both setable and getable, which means that the class defines both set method and get method.

    For example, to define a property 'Flux' of type Real on the HogeProcess class, write like this in the public area of the class definition:

    
public:
    
      LIBECS_DM_OBJECT( HogeProcess, Process )
      {
        PROPERTYSLOT_SET_GET( Flux, Real );
      }
    This registers these methods:
    void HogeProcess::setFlux( const Real& );
    and
    const Real HogeProcess::getFlux() const;
    as the set and get methods of 'Flux' property of the class HogeProcess, respectively. Signatures of the methods must match with the prototypes defined in the previous section. LIBECS_DM_OBJECT can have any number of properties. It can also be empty.

  • PROPERTYSLOT_SET( NAME, TYPE )

    This is almost the same as PROPERTYSLOT_SET_GET, but this does not register get method. Use this if only a set method is available.

  • PROPERTYSLOT_GET( NAME, TYPE )

    This is almost the same as PROPERTYSLOT_SET_GET, but this does not register set method. Use this if only a get method is available.

  • PROPERTYSLOT( NAME, TYPE, SET_METHOD, GET_METHOD )

    If the name of either get or set method is different from the default format (setNAME() or getNAME()), then use this macro with explicitly specifying the pointers to the methods.

    For example, the following use of the macro registers setFlux2() and anotherGetMethod() methods of Flux property of the class HogeProcess:

    
PROPERTYSLOT( Flux, Real, 
                  &HogeProcess::setFlux2,
                  &HogeProcess::anotherGetMethod );

If more than one PropertySlots with the same name are created on an object, the last is taken.

6.3.2.3. Load / save methods

In addition to set and get methods, load and save methods can be defined. Load methods are called when the model is loaded from the model file. Similarly, save methods are called when the state of the model is saved to a file by saveModel() method of the simulator.

Unless otherwise specified, load and save methods default to set and get methods. This default definition can be changed by using the following some macros.

  • PROPERTYSLOT_LOAD_SAVE( NAME, TYPE, SET_METHOD, GET_METHOD, LOAD_METHOD, SAVE_METHOD )

    This macros is the most generic way to set the property methods; all of set method, get method, load method ans save method can be specified independently. If the LOAD_METHOD is NOMETHOD, it is said to be not loadable, and it is not savable if SAVE_METHOD is NOMETHOD.

  • PROPERTYSLOT_NO_LOAD_SAVE( NAME, TYPE, SET_METHOD, GET_METHOD )

    Usage of this macro is the same as PROPERTYSLOT in the previous section, but this sets both LOAD_METHOD and SAVE_METHOD to NOMETHOD.

    That is, this macro is equivalent to writing:

    PROPERTYSLOT_LOAD_SAVE( NAME, TYPE, SET_METHOD, GET_METHOD, NOMETHOD, NOMETHOD )

  • PROPERTYSLOT_SET_GET_NO_LOAD_SAVE( NAME, TYPE, SET_METHOD, GET_METHOD )

    PROPERTYSLOT_SET_NO_LOAD_SAVE( NAME, TYPE, SET_METHOD )

    PROPERTYSLOT_GET_NO_LOAD_SAVE( NAME, TYPE, GET_METHOD )

    Usage of these macros are the same as: PROPERTYSLOT_SET_GET, PROPERTYSLOT_SET, and PROPERTYSLOT_GET, except that load and save methods are not set instead of default to set and get methods.

6.3.2.4. Inheriting properties of base class

In most cases you may also want to use properties of base class. To inherit the baseclass properties, use INHERIT_PROPERTIES( PROPERTY_BASECLASS ) macro. This macro is usually placed before any property definition macros (such as PROPERTY_SET_GET()).

LIBECS_DM_OBJECT( CLASSNAME, DMTYPE )
{
  INHERIT_PROPERTIES( PROPERTY_BASECLASS );
  
  PROPERTYSLOT_SET_GET( NAME, TYPE );
}
Here PROPERTY_BASECLASS is usually the same as BASECLASS. An exception is when the BASECLASS does not make use of LIBECS_DM_OBJECT() macro. In this case, choose the nearest baseclass in the class hierarachy that uses LIBECS_DM_OBJECT() for PROPERTY_BASECLASS.

6.3.3. Using PropertySlots In Simulation

(1) Static direct access (using native C++ method) bypassing the PropertySlot, (2) dynamically-bound access via a PropertySlot object, (3) dynamically-bound access via PropertyInterface.