Classes of objects


Detailed Description

GridLAB-D modules implement classes of objects, which are supported by the functions in this module.

Object classes are defined by runtime modules. Each class implements a type of object and links the runtime modules implementation to the core. Key behaviors of classes include


Defines

#define PC_BOTTOMUP   0x02
 used when the class requires synchronization on the bottom-up pass
#define PC_FORCE_NAME   0x20
 used to indicate the this class must define names for all its objects
#define PC_NOSYNC   0x00
 used when the class requires no synchronization
#define PC_PARENT_OVERRIDE_OMIT   0x40
 used to ignore parent's use of PC_UNSAFE_OVERRIDE_OMIT
#define PC_POSTTOPDOWN   0x04
 used when the class requires synchronization on the second top-down pass
#define PC_PRETOPDOWN   0x01
 used when the class requires synchronization on the first top-down pass
#define PC_UNSAFE_OVERRIDE_OMIT   0x80
 used to flag that omitting overrides is unsafe
#define PF_CHARSET   0x0002
 set supports single character keywords (avoids use of |)
#define PF_DEPRECATED   0x8000
 set this flag to indicate that the property is deprecated (warning will be displayed anytime it is used
#define PF_DEPRECATED_NONOTICE   0x04000
 set this flag to indicate that the property is deprecated but no reference warning is desired
#define PF_RECALC   0x0001
 property has a recalc trigger (only works if recalc_<class> is exported)
#define PT_EXTENDED   0x0004
 indicates that the property was added at runtime

Typedefs

typedef char char1024 [1025]
 strings up to 1024 characters
typedef char char256 [257]
 strings up to 256 characters
typedef char char32 [33]
 strings up to 32 characters
typedef char CLASSNAME [64]
 the name a GridLAB class
typedef struct s_delegatedtype DELEGATEDTYPE
 type delegation specification
typedef struct s_delegatedvalue DELEGATEDVALUE
 a delegation entry
typedef char FUNCTIONNAME [64]
 the name of a function (not used)
typedef short int16
 8-bit integers
typedef int int32
 16-bit integers
typedef char int8
 string up to 8 characters
typedef unsigned char PASSCONFIG
 the entry point of a module function
typedef struct s_property_map PROPERTY
 property definition item
typedef void * PROPERTYADDR
 the offset of a property from the end of the OBJECT header
typedef char PROPERTYNAME [64]
 the name of a property

Enumerations

enum  NOTIFYMODULE {
  NM_PREUPDATE = 0, NM_POSTUPDATE = 1, NM_RESET = 2, NM_PREUPDATE = 0,
  NM_POSTUPDATE = 1, NM_RESET = 2
}
enum  PROPERTYACCESS {
  PA_PUBLIC, PA_REFERENCE, PA_PROTECTED, PA_PRIVATE,
  PA_PUBLIC, PA_REFERENCE, PA_PROTECTED, PA_PRIVATE
}
enum  PROPERTYTYPE { ,
  PT_void, PT_double, PT_complex, PT_enumeration,
  PT_set, PT_int16, PT_int32, PT_int64,
  PT_char8, PT_char32, PT_char256, PT_char1024,
  PT_object, PT_delegated, PT_bool, PT_timestamp,
  PT_double_array, PT_complex_array, PT_float, PT_real,
  PT_loadshape, PT_enduse , PT_void, PT_double,
  PT_complex, PT_enumeration, PT_set, PT_int16,
  PT_int32, PT_int64, PT_char8, PT_char32,
  PT_char256, PT_char1024, PT_object, PT_delegated,
  PT_bool, PT_timestamp, PT_double_array, PT_complex_array,
  PT_float, PT_real, PT_loadshape, PT_enduse
}

Functions

int class_define_enumeration_member (CLASS *oclass, char *property_name, char *member, enumeration value)
 Define an enumeration member.
FUNCTION * class_define_function (CLASS *oclass, FUNCTIONNAME functionname, FUNCTIONADDR call)
 Define a class function.
int class_define_map (CLASS *oclass,...)
 Define one or more class properties.
int class_define_set_member (CLASS *oclass, char *property_name, char *member, unsigned int64 value)
 Define a set member.
PROPERTY * class_find_property (CLASS *oclass, PROPERTYNAME name)
 Find the named property in the class.
CLASS * class_get_class_from_classname (char *name)
 Get the class from the class name.
CLASS * class_get_class_from_classname_in_module (char *name, MODULE *mod)
 Get the class from the class name and a module pointer.
unsigned int class_get_count (void)
 Get the number of registered class.
CLASS * class_get_first_class (void)
 Get the first registered class.
PROPERTY * class_get_first_property (CLASS *oclass)
 Get the first property in a class's property list.
CLASS * class_get_last_class (void)
 Get the last registered class.
PROPERTY * class_get_next_property (PROPERTY *prop)
 Get the next property of within the current class.
char * class_get_property_typename (PROPERTYTYPE type)
 Get the name of a property from its type.
PROPERTYTYPE class_get_propertytype_from_typename (char *name)
 Get the type of a property from its name.
int class_get_xsd (CLASS *oclass, char *buffer, size_t len)
 Generate the XSD snippet of a class.
void class_profiles (void)
 Generate profile information for the classes used.
PROPERTY * class_prop_in_class (CLASS *oclass, PROPERTY *prop)
 Search class hierarchy for a property.
int class_property_to_string (PROPERTY *prop, void *addr, char *value, int size)
 Convert a property value to a string.
CLASS * class_register (MODULE *module, CLASSNAME name, unsigned int size, PASSCONFIG passconfig)
 Register an object class.
DELEGATEDTYPEclass_register_type (CLASS *oclass, char *type, int(*from_string)(void *, char *), int(*to_string)(void *, char *, int))
 Register a type delegation for a property.
int class_saveall (FILE *fp)
 Save all class information to a stream in glm format.
int class_saveall_xml (FILE *fp)
 Save all class information to a stream in xml format.
int class_string_to_property (PROPERTY *prop, void *addr, char *value)
 Convert a string value to property data.
unsigned long property_size (PROPERTY *prop)
 Get the size of a single instance of a property.

Variables

PROPERTYACCESS s_property_map::access
 property access flags
FUNCTIONADDR s_function_map::addr
 the call address of the function
PROPERTYADDR s_property_map::addr
 property location, offset from OBJECT header
DELEGATEDTYPEs_property_map::delegation
 property delegation, if any; NULL if none
char * s_property_map::description
 description of property
PROPERTYFLAGS s_property_map::flags
 property flags (e.g., PF_RECALC)
int(* s_delegatedtype::from_string )(void *addr, char *value)
 the function that converts from a string to the data
KEYWORD * s_property_map::keywords
 keyword list, if any; NULL if none (only for set and enumeration types)
FUNCTIONNAME s_function_map::name
 the name of the function
PROPERTYNAME s_property_map::name
 property name
struct s_property_map * s_property_map::next
 next property in property list
CLASS * s_delegatedtype::oclass
 the class implementing the delegated type
CLASS * s_class_list::parent
 parent class from which properties should be inherited
PROPERTYTYPE s_property_map::ptype
 property type
unsigned long s_property_map::size
 property array size
int(* s_delegatedtype::to_string )(void *addr, char *value, int size)
 the function that converts from the data to a string
DELEGATEDTYPEs_delegatedvalue::type
 the delegation specification to use
UNITs_property_map::unit
 property unit, if any; NULL if none


Typedef Documentation

typedef unsigned char PASSCONFIG

the entry point of a module function

the pass configuration

Definition at line 125 of file class.h.


Enumeration Type Documentation

Enumerator:
NM_PREUPDATE  notify module before property change
NM_POSTUPDATE  notify module after property change
NM_RESET  notify module of system reset event
NM_PREUPDATE  notify module before property change
NM_POSTUPDATE  notify module after property change
NM_RESET  notify module of system reset event

Definition at line 134 of file class.h.

Enumerator:
PA_PUBLIC  property is public (visible, saved, and loaded)
PA_REFERENCE  property is FYI (visible and saved, but not loaded
PA_PROTECTED  property is semipublic (visible, but not saved or loaded)
PA_PRIVATE  property is nonpublic (not-visible, saved or loaded)
PA_PUBLIC  property is public (visible, saved, and loaded)
PA_REFERENCE  property is FYI (visible and saved, but not loaded
PA_PROTECTED  property is semipublic (visible, but not saved or loaded)
PA_PRIVATE  property is nonpublic (not-visible, saved or loaded)

Definition at line 116 of file class.h.

Enumerator:
PT_void  the type has no data
PT_double  the data is a double-precision float
PT_complex  the data is a complex value
PT_enumeration  the data is an enumeration
PT_set  the data is a set
PT_int16  the data is a 16-bit integer
PT_int32  the data is a 32-bit integer
PT_int64  the data is a 64-bit integer
PT_char8  the data is NULL -terminated string up to 8 characters in length
PT_char32  the data is NULL -terminated string up to 32 characters in length
PT_char256  the data is NULL -terminated string up to 256 characters in length
PT_char1024  the data is NULL -terminated string up to 1024 characters in length
PT_object  the data is a pointer to a GridLAB object
PT_delegated  the data is delegated to a module for implementation
PT_bool  the data is a true/false value, implemented as a C++ bool
PT_timestamp  timestamp value
PT_double_array  the data is a fixed length double[]
PT_complex_array  the data is a fixed length complex[]
PT_float  the data is a fixed length array of object pointers

Single-precision float

PT_real  Single or double precision float ~ allows double values to be overriden.
PT_loadshape  Loadshapes are state machines driven by schedules.
PT_enduse  Enduse load data.
PT_void  the type has no data
PT_double  the data is a double-precision float
PT_complex  the data is a complex value
PT_enumeration  the data is an enumeration
PT_set  the data is a set
PT_int16  the data is a 16-bit integer
PT_int32  the data is a 32-bit integer
PT_int64  the data is a 64-bit integer
PT_char8  the data is NULL -terminated string up to 8 characters in length
PT_char32  the data is NULL -terminated string up to 32 characters in length
PT_char256  the data is NULL -terminated string up to 256 characters in length
PT_char1024  the data is NULL -terminated string up to 1024 characters in length
PT_object  the data is a pointer to a GridLAB object
PT_delegated  the data is delegated to a module for implementation
PT_bool  the data is a true/false value
PT_timestamp  timestamp value
PT_double_array  the data is a fixed length double[]
PT_complex_array  the data is a fixed length complex[]
PT_float  the data is a fixed length array of object pointers

Single-precision float

PT_real  Single or double precision float ~ allows double values to be overriden.
PT_loadshape  Loadshapes are state machines driven by schedules.
PT_enduse  Enduse load data.

Definition at line 70 of file class.h.


Function Documentation

int class_define_enumeration_member ( CLASS *  oclass,
char *  property_name,
char *  member,
enumeration  value 
)

Define an enumeration member.

Returns:
0 on failure, 1 on success
Parameters:
oclass  pointer to the class which implements the enumeration
property_name  property name of the enumeration
member  member name to define
value  enum value to associate with the name

Definition at line 985 of file class.c.

References class_find_property().

Referenced by class_define_map().

FUNCTION * class_define_function ( CLASS *  oclass,
FUNCTIONNAME  functionname,
FUNCTIONADDR  call 
)

Define a class function.

Returns:
A structure with the function pointer and the function's published name.

Definition at line 1025 of file class.c.

References output_error().

int class_define_map ( CLASS *  oclass,
  ... 
)

Define one or more class properties.

The variable argument list must be NULL -terminated. Each property declaration begins with a PROPERTYTYPE value, followed by a char* pointing to the name of the property, followed the offset from the end of the OBJECT header's address (or the absolution address of the data if PT_SIZE is used). If the property name includes units in square brackets, they will be separated from the name and added to the property's definition, provided the are defined in the file unitfile.txt.

You may use the flag PT_INHERIT to specify a parent class from which to inherit published properties. If this is used, you may add the PC_UNSAFE_OVERRIDE_OMIT flag in class_register to force child classes to use all the pass configured.

You may use special flags to customize the property registration:

  • PT_ACCESS will set special access rights (see PROPERTYACCESS)
  • PT_SIZE will cause memory to be allocated for the value. If addr is non-NULL, the data is points to will be converted to the property.
  • PT_FLAGS will allow you set property flags (see PROPERTYFLAGS)
  • PT_INHERIT will allow you to include the parent classes properties
  • PT_UNITS will allow you to specify the units (instead of using [] syntax)
  • PT_EXTEND will expand the size of the class by the size of the property being mapped
  • PT_EXTENDBY will expand the size of the class by the unsigned int provided in the next argument

Returns:
a count of variables mapped; <=0 indicates not all mapped (-count successfully mapped before it failed), errno:
  • E2BIG: variable name too long to store
  • ENOMEM: memory allocation failed
  • ENOENT: oclass type not found
  • EINVAL: keyword is invalid
Parameters:
oclass  the object class

Definition at line 653 of file class.c.

References class_define_enumeration_member(), class_define_set_member(), class_get_class_from_classname_in_module(), class_get_property_typename(), int64, output_error(), output_warning(), PA_PRIVATE, PA_PROTECTED, PA_PUBLIC, PA_REFERENCE, PC_BOTTOMUP, PC_PARENT_OVERRIDE_OMIT, PC_POSTTOPDOWN, PC_PRETOPDOWN, PC_UNSAFE_OVERRIDE_OMIT, PF_DEPRECATED, PT_delegated, PT_enduse, PT_enumeration, PT_set, and unit_find().

int class_define_set_member ( CLASS *  oclass,
char *  property_name,
char *  member,
unsigned int64  value 
)

Define a set member.

Parameters:
oclass  pointer to the class which implements the set
property_name  property name of the set
member  member name to define
value  set value to associate with the name

Definition at line 1002 of file class.c.

References class_find_property(), and PF_CHARSET.

Referenced by class_define_map().

PROPERTY * class_find_property ( CLASS *  oclass,
PROPERTYNAME  name 
)

Find the named property in the class.

Returns:
a pointer to the PROPERTY, or NULL if the property is not found.
Parameters:
oclass  the object class
name  the property name

Definition at line 229 of file class.c.

References output_error(), output_warning(), PF_DEPRECATED, and PF_DEPRECATED_NONOTICE.

Referenced by aggregate_mkgroup(), class_define_enumeration_member(), class_define_set_member(), cmex_get(), convert_from_complex(), convert_from_double(), object_get_addr(), object_get_property(), object_get_reference(), and object_set_value_by_name().

CLASS * class_get_class_from_classname ( char *  name  ) 

Get the class from the class name.

Returns:
a pointer to the class having that name, or NULL if no match found.
Parameters:
name  a pointer to a NULL -terminated string containing the class name

Definition at line 586 of file class.c.

References output_verbose().

Referenced by class_register(), cmdarg_load(), cmex_create(), cmex_get(), exec_debug_cmd(), and output_xsd().

CLASS * class_get_class_from_classname_in_module ( char *  name,
MODULE *  mod 
)

Get the class from the class name and a module pointer.

Returns:
a pointer to the class registered to that module having that name, or NULL if no match found.

Definition at line 499 of file class.c.

Referenced by class_define_map().

unsigned int class_get_count ( void   ) 

Get the number of registered class.

Returns:
the number of classes registered

Definition at line 338 of file class.c.

CLASS * class_get_first_class ( void   ) 

Get the first registered class.

Returns:
a pointer to the first registered CLASS, or NULL if none registered.

Definition at line 490 of file class.c.

Referenced by class_saveall(), class_saveall_xml(), cmdarg_load(), exec_start(), module_load(), and output_xsd().

PROPERTY * class_get_first_property ( CLASS *  oclass  ) 

Get the first property in a class's property list.

All subsequent properties that have the same class can be scanned. Be careful not to scan off the end of the list onto the next class. The iterator should look like this

    PROPERTY *p;
    for (p=class_get_first_property(oclass);
        p!=NULL && p->otype==oclass->type;
        p=p->next) 
    {
    // your code goes here
    }

Returns:
a pointer to first PROPERTY in the CLASS definition, or NULL is none defined
Parameters:
oclass  the object class

Definition at line 124 of file class.c.

References throw_exception().

CLASS * class_get_last_class ( void   ) 

Get the last registered class.

Returns:
the last class registered

Definition at line 330 of file class.c.

Referenced by module_load().

PROPERTY * class_get_next_property ( PROPERTY *  prop  ) 

Get the next property of within the current class.

Returns:
a pointer to the PROPERTY, or NULL if there are no properties left

Definition at line 138 of file class.c.

char * class_get_property_typename ( PROPERTYTYPE  type  ) 

Get the name of a property from its type.

Returns:
a pointer to a string containing the name of the property type
Parameters:
type  the property type

Definition at line 346 of file class.c.

Referenced by class_define_map(), class_get_xsd(), class_saveall(), class_saveall_xml(), cmdarg_load(), cmex_get(), and object_dump().

PROPERTYTYPE class_get_propertytype_from_typename ( char *  name  ) 

Get the type of a property from its name.

Returns:
the property type
Parameters:
name  a string containing the name of the property type

Definition at line 357 of file class.c.

References PT_void.

int class_get_xsd ( CLASS *  oclass,
char *  buffer,
size_t  len 
)

Generate the XSD snippet of a class.

Returns:
the number of characters written to the buffer
Parameters:
oclass  a pointer to the class to convert to XSD
buffer  a pointer to the first character in the buffer
len  the size of the buffer

Definition at line 1260 of file class.c.

References class_get_property_typename().

Referenced by output_xsd().

PROPERTY * class_prop_in_class ( CLASS *  oclass,
PROPERTY *  prop 
)

Search class hierarchy for a property.

Returns:
property pointer if found, NULL if not in class hierarchy

Definition at line 149 of file class.c.

int class_property_to_string ( PROPERTY *  prop,
void *  addr,
char *  value,
int  size 
)

Convert a property value to a string.

The addr must be the physical address in memory.

Returns:
the number character written to value
Parameters:
prop  the property type
addr  the address of the property's data
value  the value buffer to which the string is to be written
size  the maximum number of characters that can be written to the value buffer

Definition at line 393 of file class.c.

References output_error(), and PT_delegated.

Referenced by global_getvar(), and object_get_value_by_addr().

CLASS * class_register ( MODULE *  module,
CLASSNAME  name,
unsigned int  size,
PASSCONFIG  passconfig 
)

Register an object class.

Returns:
the object class; NULL on error errno:
  • E2BIG: class name too long
  • ENOMEM: memory allocation failed
Parameters:
module  the module that implements the class
name  the class name
size  the size of the data block
passconfig  the passes for which sync should be called

Definition at line 420 of file class.c.

References class_get_class_from_classname(), output_error(), output_fatal(), and output_verbose().

DELEGATEDTYPE * class_register_type ( CLASS *  oclass,
char *  type,
int(*)(void *, char *)  from_string,
int(*)(void *, char *, int)  to_string 
)

Register a type delegation for a property.

Returns:
a pointer DELEGATEDTYPE struct if successful, NULL if delegation failed
Type delegation is used to transform data to string and string to data conversion to routines implemented in a module, instead of in the core. This allows custom data type to be implemented, including enumerations, sets, and special objects.
Parameters:
oclass  the object class
type  the property type
from_string  the converter from string to data
to_string  the converter from data to string

Definition at line 1194 of file class.c.

References output_error().

int class_saveall ( FILE *  fp  ) 

Save all class information to a stream in glm format.

Returns:
the number of characters written to the stream
Parameters:
fp  a pointer to the stream FILE structure

Definition at line 1075 of file class.c.

References class_get_first_class(), and class_get_property_typename().

int class_saveall_xml ( FILE *  fp  ) 

Save all class information to a stream in xml format.

Returns:
the number of characters written to the stream
Parameters:
fp  a pointer to the stream FILE structure

Definition at line 1105 of file class.c.

References class_get_first_class(), and class_get_property_typename().

int class_string_to_property ( PROPERTY *  prop,
void *  addr,
char *  value 
)

Convert a string value to property data.

The addr must be the physical address in memory.

Returns:
the number of value read from the value string; 0 on failure
Parameters:
prop  the type of the property at the addr
addr  the address of the property's data
value  the string from which the data is read

Definition at line 379 of file class.c.

Referenced by global_setvar(), and object_set_value_by_addr().

unsigned long property_size ( PROPERTY *  prop  ) 

Get the size of a single instance of a property.

Returns:
the size in bytes of the a property

Definition at line 171 of file class.c.

Referenced by global_create().


GridLAB-DTM Version 2.0
An open-source project initiated by the US Department of Energy