E-Cell Simulation Environment Version 3.1.100 User's Manual (Draft: Dec. 18, 2003) | ||
---|---|---|
Prev | Chapter 6. Creating New Object Classes | Next |
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.
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.
A type of a PropertySlot is any one of these four types:
Real
Integer
String
Polymorph
To define a PropertySlot on an object class, you have to:
Define set and/or get method(s).
If necessary, define a member variable to store the property value.
Register the method(s) as a PropertySlot.
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 ) constwhere 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
( constTYPE
&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:
constTYPE
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:
SET_METHOD_DEF(
TYPE
, NAME
, CLASSNAME
)
Expansion:
voidCLASSNAME
::setNAME
( constTYPE
&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:
constTYPE
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(This assumes there is a variable with the same name as the property name (NAME
,TYPE
)
NAME
), and expands to a
code that is equivalent to:
SET_METHOD(NAME
,TYPE
) {NAME
= value; } GET_METHOD(NAME
,TYPE
) { returnNAME
; }
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(This registers these methods:HogeProcess
,Process
) { PROPERTYSLOT_SET_GET(Flux
,Real
); }
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.
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.
In most cases you may also want to use properties of
base class. To inherit the baseclass properties, use
INHERIT_PROPERTIES(
macro. This macro is usually placed before any property
definition macros (such as
PROPERTY_BASECLASS
)PROPERTY_SET_GET()
).
LIBECS_DM_OBJECT(HereCLASSNAME
,DMTYPE
) { INHERIT_PROPERTIES(PROPERTY_BASECLASS
); PROPERTYSLOT_SET_GET(NAME
,TYPE
); }
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
.
(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.