Objects
[GridLAB-D Core]


Detailed Description

Object functions support object operations.

Objects have two parts, an OBJECTHDR block followed by an OBJECTDATA block. The OBJECTHDR contains all the common object information, such as it's id and clock. The OBJECTDATA contains all the data implemented by the module that created the object.

    OBJECTHDR       size                        size of the OBJECTDATA block
                    id                          unique id of the object
                    oclass                      class the implements the OBJECTDATA
                    next                        pointer to the next OBJECTHDR
                    parent                      pointer to parent's OBJECTHDR
                    rank                        object's rank (less than parent's rank)
                    clock                       object's sync clock
                    latitude, longitude         object's geo-coordinates
                    in_svc, out_svc             object's activation/deactivation dates
                    flags                       object flags (e.g., external PLC active)
    OBJECTDATA      (varies; defined by oclass)


Classes

struct  s_callbacks
struct  s_object_list

Defines

#define GETADDR(O, P)   (O?((void*)((char*)(O+1)+(unsigned int64)((P)->addr))):NULL)
 get the addr of an object's property
#define MYPARENT   ((((OBJECT*)this)-1)->parent)
 get the parent from the object's data structure
#define object_id(X)   ((X)?(X)->id:-1)
 get the id of the object X
#define object_parent(X)   ((X)?(X)->parent:NULL)
 get the parent of the object
#define object_rank(X)   ((X)?(X)->name:-1)
 get the rank of the object
#define object_size(X)   ((X)?(X)->size:-1)
 get the size of the object X
#define OBJECTDATA(X, T)   ((T*)((X)?((X)+1):NULL))
 get the object data structure
#define OBJECTHDR(X)   ((X)?(((OBJECT*)X)-1):NULL)
 get the header from the object's data structure
#define OF_HASPLC   0x0001
 Object flag; external PLC is attached, disables local PLC.
#define OF_LOCKED   0x0002
 Object flag; data write pending, reread recommended after lock clears.
#define OF_NONE   0x0000
 Object name Object flag; none set.
#define OF_RECALC   0x0008
 Object flag; recalculation of derived values is needed.
#define OF_RERANK   0x4000
 Internal use only.
#define QNAN   sqrt(-1)
 NaN quantity.

Typedefs

typedef s_callbacks CALLBACKS
 core callback function table
typedef s_object_list OBJECT
 Object header structure.
typedef char * OBJECTNAME
 Object id number.
typedef unsigned int OBJECTNUM
 Object data size.
typedef unsigned int OBJECTRANK
 Object rank number.
typedef unsigned short OBJECTSIZE

Functions

int convert_from_latitude (double v, void *buffer, int bufsize)
int convert_from_longitude (double v, void *buffer, int bufsize)
double convert_to_latitude (char *buffer)
double convert_to_longitude (char *buffer)
void debug_traverse_tree (OBJECTTREE *tree)
int object_build_object_array ()
OBJECTobject_create_array (CLASS *oclass, OBJECTSIZE size, unsigned int n_objects)
 Create multiple objects.
OBJECTobject_create_single (CLASS *oclass, OBJECTSIZE size)
 Create a single object.
int object_dump (char *outbuffer, int size, OBJECT *obj)
 Dump an object to a buffer.
OBJECTobject_find_by_id (OBJECTNUM id)
 Find an object by its id number.
OBJECTobject_find_name (OBJECTNAME name)
 Find an object from a name.
PROPERTYobject_flag_property (void)
void * object_get_addr (OBJECT *obj, char *name)
 Get the address of a property value.
complexobject_get_complex (OBJECT *obj, PROPERTY *prop)
complexobject_get_complex_by_name (OBJECT *obj, char *name)
complexobject_get_complex_quick (OBJECT *obj, PROPERTY *prop)
unsigned int object_get_count (void)
 Get the number of objects defined.
double * object_get_double (OBJECT *obj, PROPERTY *prop)
double * object_get_double_by_name (OBJECT *obj, char *name)
double * object_get_double_quick (OBJECT *obj, PROPERTY *prop)
OBJECTobject_get_first ()
 Get the first object in the model.
int16object_get_int16 (OBJECT *obj, PROPERTY *prop)
int16object_get_int16_by_name (OBJECT *obj, char *name)
int32object_get_int32 (OBJECT *obj, PROPERTY *prop)
int32object_get_int32_by_name (OBJECT *obj, char *name)
int64 * object_get_int64 (OBJECT *obj, PROPERTY *prop)
int64 * object_get_int64_by_name (OBJECT *obj, char *name)
OBJECTobject_get_next (OBJECT *obj)
 Get the next object in the model.
OBJECTobject_get_object (OBJECT *obj, PROPERTY *prop)
OBJECTobject_get_object_by_name (OBJECT *obj, PROPERTY *prop)
int object_get_oflags (KEYWORD **extflags)
PROPERTYobject_get_property (OBJECT *obj, PROPERTYNAME name)
 Get a named property of an object.
OBJECTobject_get_reference (OBJECT *obj, char *name)
 Get a reference to another object.
char * object_get_string (OBJECT *obj, PROPERTY *prop)
char * object_get_string_by_name (OBJECT *obj, char *name)
char * object_get_unit (OBJECT *obj, char *name)
 Get the unit of an object, if any.
int object_get_value_by_addr (OBJECT *obj, void *addr, char *value, int size, PROPERTY *prop)
 Get a property value by reference to its physical address.
int object_get_value_by_name (OBJECT *obj, PROPERTYNAME name, char *value, int size)
 Get a value by reference to its property name.
int object_init (OBJECT *obj)
 Initialize an object.
int object_isa (OBJECT *obj, char *type)
 Tests the type of an object.
char * object_name (OBJECT *obj)
 Get the name of an object.
char * object_property_to_string (OBJECT *obj, char *name)
OBJECTobject_remove_by_id (OBJECTNUM id)
 Removes a single object.
int object_saveall (FILE *fp)
 Save all the objects in the model to the stream fp in the .GLM format.
int object_saveall_xml (FILE *fp)
 Save all the objects in the model to the stream fp in the .XML format.
int object_saveall_xml_old (FILE *fp)
int object_set_dependent (OBJECT *obj, OBJECT *dependent)
 Set the dependent of an object.
int object_set_double_by_name (OBJECT *obj, PROPERTYNAME name, double value)
void object_set_name (OBJECT *obj, OBJECTNAME name)
 Sets the name of an object.
int object_set_parent (OBJECT *obj, OBJECT *parent)
 Set the parent of an object.
int object_set_rank (OBJECT *obj, OBJECTRANK rank)
 Set the rank of an object but forcing it's parent to increase rank if necessary.
int object_set_value_by_addr (OBJECT *obj, void *addr, char *value, PROPERTY *prop)
 Set a property value by reference to its physical address.
int object_set_value_by_name (OBJECT *obj, PROPERTYNAME name, char *value)
 Set a property value by reference to its name.
TIMESTAMP object_sync (OBJECT *obj, TIMESTAMP ts, PASSCONFIG pass)
 Synchronize an object.
void object_tree_delete (OBJECT *obj, OBJECTNAME name)
int object_tree_rebalance (OBJECTTREE *tree)
void remove_objects ()
 Convenience method use by the testing framework.
void rotate_tree_left (OBJECTTREE **tree)
void rotate_tree_right (OBJECTTREE **tree)
int tree_get_height (OBJECTTREE *tree)

Variables

KEYWORD oflags []


Function Documentation

OBJECT * object_create_array ( CLASS oclass,
OBJECTSIZE  size,
unsigned int  n_objects 
)

Create multiple objects.

Returns:
Same as create_single, but returns the first object created.
Parameters:
oclass  a pointer to the CLASS structure
size  the size of the OBJECT data structure
n_objects  the number of objects to create

Definition at line 220 of file object.c.

References object_create_single(), and s_module_list::oclass.

OBJECT * object_create_single ( CLASS oclass,
OBJECTSIZE  size 
)

Create a single object.

Returns:
a pointer to object header, NULL of error, set errno as follows:
  • EINVAL type is not valid
  • ENOMEM memory allocation failed
Parameters:
oclass  a pointer to the CLASS structure
size  the size of the OBJECT data structure

Definition at line 184 of file object.c.

References s_object_list::clock, s_object_list::flags, s_object_list::id, s_object_list::in_svc, s_object_list::latitude, s_object_list::longitude, s_object_list::name, s_object_list::next, s_class_list::numobjs, s_module_list::oclass, s_object_list::oclass, OF_NONE, s_object_list::out_svc, s_object_list::parent, s_class_list::profiler, QNAN, s_object_list::rank, s_object_list::size, TS_NEVER, and TS_ZERO.

Referenced by object_create_array().

int object_dump ( char *  outbuffer,
int  size,
OBJECT obj 
)

Dump an object to a buffer.

Returns:
the number of characters written to the buffer
Parameters:
outbuffer  the destination buffer
size  the size of the buffer
obj  the object to dump

Definition at line 933 of file object.c.

References class_get_property_typename(), s_object_list::clock, convert_from_latitude(), convert_from_longitude(), convert_from_set(), convert_from_timestamp(), s_object_list::flags, FMT_INT64, s_object_list::id, s_object_list::latitude, s_object_list::longitude, s_object_list::name, s_class_list::name, object_flag_property(), object_property_to_string(), s_object_list::oclass, output_error(), s_object_list::parent, s_class_list::pmap, PT_delegated, s_object_list::rank, throw_exception(), PROPERTY::type, and s_class_list::type.

Referenced by exec_debug().

OBJECT * object_find_by_id ( OBJECTNUM  id  ) 

Find an object by its id number.

Returns:
a pointer the object
Parameters:
id  object id number

Definition at line 130 of file object.c.

References s_object_list::id, s_object_list::next, object_build_object_array(), and object_get_count().

Referenced by convert_to_object(), and object_remove_by_id().

OBJECT * object_find_name ( OBJECTNAME  name  ) 

Find an object from a name.

This only works for named objects. See object_set_name().

Returns:
a pointer to the OBJECT structure

Definition at line 1439 of file object.c.

Referenced by convert_to_object(), and exec_debug_cmd().

void * object_get_addr ( OBJECT obj,
char *  name 
)

Get the address of a property value.

Returns:
void pointer to the data; NULL is not found
Parameters:
obj  object to look in
name  name of property to find

Definition at line 266 of file object.c.

References PROPERTY::addr, int64, s_object_list::oclass, s_class_list::pmap, and s_class_list::type.

unsigned int object_get_count ( void   ) 

Get the number of objects defined.

Returns:
the number of objects in the model

Definition at line 83 of file object.c.

Referenced by gld_loadHndl::endDocument(), find_objects(), find_runpgm(), object_build_object_array(), and object_find_by_id().

OBJECT * object_get_first (  ) 

Get the first object in the model.

Returns:
a pointer to the first OBJECT

Definition at line 738 of file object.c.

Referenced by gld_loadHndl::endDocument(), exec_debug_cmd(), find_next(), find_objects(), kml_document(), module_saveobj_xml(), and object_build_object_array().

OBJECT * object_get_next ( OBJECT obj  ) 

Get the next object in the model.

Returns:
a pointer to the OBJECT after obj
Parameters:
obj  the object from which to start

Definition at line 746 of file object.c.

References s_object_list::next.

PROPERTY * object_get_property ( OBJECT obj,
PROPERTYNAME  name 
)

Get a named property of an object.

Note that you must use object_get_value_by_name to retrieve the value of the property.

Returns:
a pointer to the PROPERTY structure
Parameters:
obj  a pointer to the object
name  the name of the property

Definition at line 96 of file object.c.

References class_get_first_property(), s_object_list::oclass, and s_class_list::type.

Referenced by cmex_set(), and object_get_unit().

int object_get_value_by_addr ( OBJECT obj,
void *  addr,
char *  value,
int  size,
PROPERTY prop 
)

Get a property value by reference to its physical address.

Returns:
the number of characters written to the buffer; 0 if failed
Parameters:
obj  the object from which to get the data
addr  the addr of the data to get
value  the buffer to which to write the result
size  the size of the buffer
prop  the property to use or NULL if unknown

Definition at line 688 of file object.c.

References class_property_to_string(), s_class_list::name, s_object_list::oclass, output_error(), and PA_PRIVATE.

int object_get_value_by_name ( OBJECT obj,
PROPERTYNAME  name,
char *  value,
int  size 
)

Get a value by reference to its property name.

Returns:
the number of characters written to the buffer; 0 if failed

Definition at line 705 of file object.c.

References object_property_to_string().

int object_init ( OBJECT obj  ) 

Initialize an object.

This should not be called until all objects that are needed are created

Returns:
1 on success; 0 on failure
Parameters:
obj  the object to initialize

Definition at line 910 of file object.c.

References s_class_list::init, s_object_list::oclass, and s_object_list::parent.

int object_isa ( OBJECT obj,
char *  type 
)

Tests the type of an object.

Parameters:
obj  the object to test
type  the type of test

Definition at line 919 of file object.c.

References s_class_list::isa, s_class_list::name, and s_object_list::oclass.

char * object_name ( OBJECT obj  ) 

Get the name of an object.

Note that this function uses a static buffer that must be used immediately. Subsequent calls will reuse the same buffer.

Returns:
a pointer to the object name string
Parameters:
obj  a pointer to the object

Definition at line 159 of file object.c.

References convert_from_object().

Referenced by cmex_object_list(), exec_test(), and object_get_unit().

OBJECT * object_remove_by_id ( OBJECTNUM  id  ) 

Removes a single object.

Returns:
Returns the object after the one that was removed.

Definition at line 239 of file object.c.

References s_object_list::id, s_class_list::name, s_object_list::name, s_module_list::name, s_object_list::next, s_module_list::next, s_class_list::numobjs, object_find_by_id(), object_tree_delete(), s_object_list::oclass, and s_class_list::profiler.

int object_saveall ( FILE *  fp  ) 

Save all the objects in the model to the stream fp in the .GLM format.

Returns:
the number of bytes written, 0 on error, with errno set.
Parameters:
fp  the stream to write to

Definition at line 984 of file object.c.

References s_object_list::clock, convert_from_latitude(), convert_from_longitude(), convert_from_object(), convert_from_set(), convert_from_timestamp(), s_object_list::flags, s_object_list::id, s_object_list::latitude, s_object_list::longitude, s_object_list::name, s_class_list::name, s_object_list::next, object_flag_property(), object_property_to_string(), s_object_list::oclass, s_object_list::parent, s_class_list::pmap, s_object_list::rank, and s_class_list::type.

int object_saveall_xml ( FILE *  fp  ) 

Save all the objects in the model to the stream fp in the .XML format.

Returns:
the number of bytes written, 0 on error, with errno set.
Parameters:
fp  the stream to write to

Definition at line 1028 of file object.c.

References s_object_list::clock, convert_from_latitude(), convert_from_longitude(), convert_from_object(), convert_from_timestamp(), s_object_list::id, s_object_list::latitude, s_object_list::longitude, s_class_list::name, s_object_list::next, object_property_to_string(), s_object_list::oclass, s_module_list::oclass, s_object_list::parent, s_class_list::pmap, s_object_list::rank, and s_class_list::type.

int object_saveall_xml_old ( FILE *  fp  ) 

Parameters:
fp  the stream to write to

Definition at line 1081 of file object.c.

References s_object_list::clock, convert_from_latitude(), convert_from_longitude(), convert_from_object(), convert_from_timestamp(), s_object_list::id, s_object_list::latitude, s_object_list::longitude, s_class_list::name, s_object_list::next, object_property_to_string(), s_object_list::oclass, s_module_list::oclass, s_object_list::parent, s_class_list::pmap, s_object_list::rank, and s_class_list::type.

int object_set_dependent ( OBJECT obj,
OBJECT dependent 
)

Set the dependent of an object.

This increases to the rank as though the parent was set, but does not affect the parent.

Returns:
the rank of the object after the dependency was set
Parameters:
obj  the object to set
dependent  the dependent object

Definition at line 819 of file object.c.

References s_object_list::rank.

void object_set_name ( OBJECT obj,
OBJECTNAME  name 
)

Sets the name of an object.

This is useful if the internal name cannot be relied upon, as when multiple modules are being used. Throws an exception when a memory error occurs or when the name is already taken by another object.

Definition at line 1449 of file object.c.

References s_object_list::name, and object_tree_delete().

int object_set_parent ( OBJECT obj,
OBJECT parent 
)

Set the parent of an object.

Returns:
the rank of the object after parent was set
Parameters:
obj  the object to set
parent  the new parent of the object

Definition at line 803 of file object.c.

References s_object_list::parent, and s_object_list::rank.

Referenced by gld_loadHndl::endDocument().

int object_set_rank ( OBJECT obj,
OBJECTRANK  rank 
)

Set the rank of an object but forcing it's parent to increase rank if necessary.

Returns:
object rank; -1 if failed
Parameters:
obj  the object to set
rank  the object

Definition at line 789 of file object.c.

References s_object_list::rank.

int object_set_value_by_addr ( OBJECT obj,
void *  addr,
char *  value,
PROPERTY prop 
)

Set a property value by reference to its physical address.

Returns:
the character written to the buffer
Parameters:
obj  the object to alter
addr  the address of the property
value  the value to set
prop  the property to use or NULL if unknown

Definition at line 495 of file object.c.

References class_string_to_property(), s_object_list::flags, s_object_list::name, s_class_list::name, NM_POSTUPDATE, NM_PREUPDATE, s_class_list::notify, s_object_list::oclass, OF_RECALC, output_error(), PA_PUBLIC, and PF_RECALC.

Referenced by object_set_value_by_name().

int object_set_value_by_name ( OBJECT obj,
PROPERTYNAME  name,
char *  value 
)

Set a property value by reference to its name.

Returns:
the number of characters written to the buffer
Parameters:
obj  the object to change
name  the name of the property to change
value  the value to set

Definition at line 630 of file object.c.

References PROPERTY::addr, FAILED, s_class_list::name, object_set_value_by_addr(), s_object_list::oclass, output_error(), PA_PUBLIC, s_class_list::pmap, and s_class_list::type.

Referenced by cmex_create(), and cmex_set().

TIMESTAMP object_sync ( OBJECT obj,
TIMESTAMP  ts,
PASSCONFIG  pass 
)

Synchronize an object.

The timestamp given is the desired increment.

If an object is called on multiple passes (see PASSCONFIG) it is customary to update the clock only after the last pass is completed.

For the sake of speed this function assumes that the sync function is properly defined in the object class structure.

Returns:
the time of the next event for this object.
Parameters:
obj  the object to synchronize
ts  the desire clock to sync to
pass  the pass configuration

Definition at line 871 of file object.c.

References s_class_list::clocks, s_class_list::count, s_object_list::flags, min, s_object_list::oclass, OF_HASPLC, OF_RECALC, PC_BOTTOMUP, s_class_list::plc, s_class_list::profiler, s_class_list::recalc, s_class_list::sync, TS_MAX, and TS_NEVER.

Referenced by exec_test().

void remove_objects ( void   ) 

Convenience method use by the testing framework.

This should only be exposed there.

Definition at line 1465 of file object.c.

References s_object_list::next, s_class_list::numobjs, s_object_list::oclass, and s_class_list::profiler.


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