Classes of objects
[GridLAB-D Core]

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


Classes

struct  s_class_list
struct  s_delegatedtype
struct  s_delegatedvalue
struct  s_function_map
struct  s_keyword
struct  s_property_map

Defines

#define _MODULE_DEFINED_
#define false   (0)
#define PC_BOTTOMUP   0x02
 used when the class requires synchronization on the bottom-up pass
#define PC_NOSYNC   0x00
 used when the class requires no synchronization
#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 PF_CHARSET   0x0002
 set supports single character keywords (avoids use of |)
#define PF_RECALC   0x0001
 property has a recalc trigger (only works if recalc_<class> is exported)
#define SET_ADD(set, value)   (set = set | value )
#define SET_CLEAR(set)   (set = 0)
#define SET_DEL(set, value)   (set = (value^SET_MASK)&set)
#define SET_HAS(set, value)   (set & value)
#define SET_MASK   0xffff
#define true   (1)

Typedefs

typedef unsigned char bool
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 char8 [9]
typedef s_class_list CLASS
typedef char CLASSNAME [32]
 the name a GridLAB class
typedef DELEGATEDVALUE * delegated
typedef s_delegatedtype DELEGATEDTYPE
 type delegation specification
typedef s_delegatedvalue DELEGATEDVALUE
 a delegation entry
typedef long enumeration
typedef int64(*) FUNCTIONADDR (void *,...)
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 s_module_list MODULE
typedef s_object_list * object
typedef unsigned short OBJECTTYPE
 the type ID on an object
typedef unsigned char PASSCONFIG
 the entry point of a module function the pass configuration
typedef s_property_map PROPERTY
 property definition item
typedef void * PROPERTYADDR
 the offset of a property from the end of the OBJECT header
typedef unsigned long PROPERTYFLAGS
typedef char PROPERTYNAME [64]
 the name of a property
typedef unsigned int64 set
typedef double triplet [3]
typedef complex triplex [3]

Enumerations

enum  NOTIFYMODULE { NM_PREUPDATE = 0, NM_POSTUPDATE = 1, NM_RESET = 2 }
enum  PROPERTYACCESS { PA_PUBLIC, PA_REFERENCE, PA_PROTECTED, PA_PRIVATE }
enum  PROPERTYTYPE {
  _PT_FIRST = -1, 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_LAST,
  PT_AGGREGATE, PT_KEYWORD, PT_ACCESS, PT_SIZE,
  PT_FLAGS, INTEGER, REAL
}

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)
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 long value)
 Define a set member.
int class_define_type (CLASS *oclass, DELEGATEDTYPE *delegation,...)
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.
CLASS * class_get_class_from_objecttype (OBJECTTYPE type)
 Get the class from the object type.
char * class_get_classname_from_objecttype (OBJECTTYPE type)
 Get the class name from the object type.
OBJECTTYPE class_get_classtype_from_classname (char *name)
 Get the object type from the class name.
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.
FUNCTIONADDR class_get_function (char *classname, char *functionname)
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.
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, PASSCONFIG passconfig)
 Register an object class.
DELEGATEDTYPE * class_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
PROPERTYADDR s_property_map::addr
 property location, offset from OBJECT header
int64   s_class_list::clocks
int32   s_class_list::count
FUNCTIONADDR s_class_list::create
DELEGATEDTYPE * s_property_map::delegation
 property delegation, if any; NULL if none
PROPERTY * first_property = NULL
PROPERTYFLAGS s_property_map::flags
 property flags (e.g., PF_RECALC)
FUNCTION * s_class_list::fmap
int(* s_delegatedtype::from_string )(void *addr, char *value)
 the function that converts from a string to the data
FUNCTIONADDR s_class_list::init
FUNCTIONADDR s_class_list::isa
KEYWORD * s_property_map::keywords
 keyword list, if any; NULL if none (only for set and enumeration types)
OBJECTTYPE last_object_type = 0
PROPERTY * last_property = NULL
MODULE * s_class_list::module
CLASSNAME s_class_list::name
FUNCTIONNAME s_function_map::name
PROPERTYNAME s_property_map::name
 property name
s_class_list * s_class_list::next
s_function_map * s_function_map::next
s_property_map * s_property_map::next
 next property in property list
s_keyword * s_keyword::next
FUNCTIONADDR s_class_list::notify
CLASS * s_delegatedtype::oclass
 the class implementing the delegated type
PASSCONFIG s_class_list::passconfig
FUNCTIONADDR s_class_list::plc
PROPERTY * s_class_list::pmap
PROPERTYTYPE s_property_map::ptype
 property type
FUNCTIONADDR s_class_list::recalc
unsigned long s_property_map::size
 property array size
FUNCTIONADDR s_class_list::sync
int(* s_delegatedtype::to_string )(void *addr, char *value, int size)
 the function that converts from the data to a string
DELEGATEDTYPE * s_delegatedvalue::type
 the delegation specification to use
UNIT * s_property_map::unit
 property unit, if any; NULL if none
unsigned long s_keyword::value

Enumeration Type Documentation

enum NOTIFYMODULE

Enumerator:
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 114 of file class.h.

enum PROPERTYACCESS

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)

Definition at line 99 of file class.h.

enum PROPERTYTYPE

Enumerator:
_PT_FIRST 
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_LAST  the data is a fixed length array of object pointers
PT_AGGREGATE 
PT_KEYWORD 
PT_ACCESS 
PT_SIZE 
PT_FLAGS 
INTEGER 
REAL 

Definition at line 62 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 579 of file class.c.

References class_find_property(), s_keyword::name, s_keyword::next, and s_keyword::value.

Referenced by class_define_map().

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 special flags to customize the property registration:

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 432 of file class.c.

References _PT_LAST, PROPERTY::addr, arg(), class_define_enumeration_member(), class_define_set_member(), class_get_property_typename(), first_property, last_property, output_error(), output_verbose(), output_warning(), PA_PRIVATE, PA_PROTECTED, PA_PUBLIC, PA_REFERENCE, s_class_list::pmap, PT_ACCESS, PT_delegated, PT_enumeration, PT_FLAGS, PT_KEYWORD, PT_set, PT_SIZE, s_class_list::type, and unit_find().

int class_define_set_member ( CLASS *  oclass,
char *  property_name,
char *  member,
unsigned long  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 596 of file class.c.

References class_find_property(), s_keyword::name, s_keyword::next, PF_CHARSET, and s_keyword::value.

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 144 of file class.c.

References s_class_list::pmap, and s_class_list::type.

Referenced by aggregate_mkgroup(), class_define_enumeration_member(), class_define_set_member(), and cmex_get().

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 360 of file class.c.

References s_class_list::module, module_find(), s_class_list::name, s_class_list::next, and output_verbose().

Referenced by class_get_function(), class_register(), 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 343 of file class.c.

References s_class_list::module, s_class_list::name, and s_class_list::next.

CLASS* class_get_class_from_objecttype ( OBJECTTYPE  type  ) 

Get the class from the object type.

Returns:
a pointer the class that implemented the type, or NULL is no match found
Parameters:
type  the object type

Definition at line 314 of file class.c.

References s_class_list::next, and s_class_list::type.

char* class_get_classname_from_objecttype ( OBJECTTYPE  type  ) 

Get the class name from the object type.

Returns:
a pointer to the string containing the class name
Parameters:
type  the object type

Definition at line 328 of file class.c.

References s_class_list::name, s_class_list::next, and s_class_list::type.

OBJECTTYPE class_get_classtype_from_classname ( char *  name  ) 

Get the object type from the class name.

Returns:
an OBJECTTYPE
Parameters:
name  a pointer to a NULL -terminated string containing then name of the class

Definition at line 395 of file class.c.

References s_class_list::name, s_class_list::next, and s_class_list::type.

unsigned int class_get_count ( void   ) 

Get the number of registered class.

Returns:
the number of classes registered

Definition at line 167 of file class.c.

Referenced by gld_loadHndl::endDocument().

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 305 of file class.c.

Referenced by class_saveall(), class_saveall_xml(), kml_document(), 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 111 of file class.c.

References first_property, and s_class_list::pmap.

Referenced by object_get_property().

CLASS * class_get_last_class ( void   ) 

Get the last registered class.

Returns:
the last class registered

Definition at line 159 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 122 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 175 of file class.c.

References _PT_LAST.

Referenced by class_define_map(), class_get_xsd(), class_saveall(), class_saveall_xml(), 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 186 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 828 of file class.c.

References class_get_property_typename(), s_keyword::name, s_class_list::name, s_keyword::next, oflags, s_class_list::pmap, and s_class_list::type.

Referenced by output_xsd().

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 220 of file class.c.

References _PT_FIRST, _PT_LAST, output_error(), and PT_delegated.

Referenced by global_dump(), global_getvar(), object_get_value_by_addr(), and object_property_to_string().

CLASS * class_register ( MODULE *  module,
CLASSNAME  name,
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
passconfig  the passes for which sync should be called

Definition at line 243 of file class.c.

References _PT_FIRST, _PT_LAST, class_get_class_from_classname(), s_class_list::clocks, s_class_list::count, s_class_list::create, s_class_list::fmap, s_class_list::module, s_class_list::name, s_module_list::name, s_class_list::next, s_class_list::numobjs, output_error(), output_fatal(), output_verbose(), s_class_list::passconfig, s_class_list::pmap, s_class_list::profiler, s_class_list::sync, and s_class_list::type.

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 770 of file class.c.

References s_delegatedtype::from_string, s_delegatedtype::oclass, output_error(), s_delegatedtype::to_string, and s_delegatedtype::type.

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 655 of file class.c.

References class_get_first_class(), class_get_property_typename(), s_class_list::fmap, s_function_map::name, s_class_list::name, s_function_map::next, s_class_list::next, s_function_map::otype, s_class_list::pmap, and s_class_list::type.

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 683 of file class.c.

References class_get_first_class(), class_get_property_typename(), s_class_list::fmap, s_function_map::name, s_class_list::name, s_function_map::next, s_class_list::next, s_function_map::otype, s_class_list::pmap, and s_class_list::type.

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 201 of file class.c.

References _PT_FIRST, _PT_LAST, output_error(), and PT_delegated.

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 133 of file class.c.

References _PT_FIRST, and _PT_LAST.

Referenced by global_create().

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