From GridLAB-D Wiki
Jump to: navigation, search

Publishing properties - Procedure for publishing properties of GridLAB-D classes

Synopsis

gl_publish_variable(CLASS *oclass, PROPERTYTYPE type, const char *'name, size_t offset, ..., NULL);
Declarations
#include "gridlabd.h"
GL_ATOMIC(type,name);
GL_STRUCT(type,name);
GL_STRING(type,name);
GL_ARRAY(type,name, size);
GL_BITFLAGS(type,name);
General accessors
size_t get_name_offset();
gld_property get_name_property();
Atomic accessors
type get_name();
type get_name(gld_rlock& rlock);
type get_name(gld_wlock& wlock);
void set_name(type value);
void set_name(type value, gld_wlock& wlock);
Struct accessors
type get_name();
type get_name(gld_rlock& rlock);
type get_name(gld_wlock& wlock);
void set_name(type value);
void set_name(type value, gld_wlock& wlock);
String accessors
char* get_name();
char* get_name(gld_rlock& rlock);
char* get_name(gld_wlock& wlock);
void set_name(char* value);
void set_name(char* value, gld_wlock& wlock);
char get_name(size_t n);
char get_name(size_t n, gld_rlock& rlock);
void set_name(char value, size_t n);
void set_name(char value, size_t n, gld_wlock& wlock);
Array accessors
type* get_name();
type* get_name(gld_rlock& rlock);
type* get_name(gld_wlock& wlock);
void set_name(type* value);
void set_name(type* value, gld_wlock& wlock);
type get_name(size_t n);
type get_name(size_t n, gld_rlock& rlock);
void set_name(type value, size_t n);
void set_name(type value, size_t n, gld_wlock& wlock);
Bitflag accessors
type get_name(type mask=-1);
type get_name(gld_rlock& rlock);
type get_name(gld_wlock& wlock);
void set_name(type value);
void set_name_bits(type value);
void clr_name(type value);
void set_name(type value, gld_wlock& wlock);

Description

The gl_publish_variable function is a variable argument list call used to publish the publicly accessible properties of a GridLAB-D class. The argument list must contain a least one property type, property name and property offset tuple. The property type must be one of the members of PROPERTYTYPE. The property name must be a const char * and the property offset must be size_t. The property list must be NULL terminated.

Additional options may be added after each property definition tuple. These options include

PT_INHERIT 
This will include the properties of the parent class (if any) in searches of this class's properties.
PT_ACCESS, access 
This allows you to set special access rights (see PROPERTYACCESS for details).
PT_FLAGS, flags 
This allows you to set special property flags (see PROPERTYFLAGS for details).
PT_UNIT, "definition
This allows you to set the units for double and complex properties.
PT_SIZE, size 
This allows you to define an array of properties.
PT_EXTEND 
This allows you to enlarge the class by the size of the property.
PT_EXTENDBY, bytes 
This allows you to enlarge the class by the number of bytes given.
PT_DESCRIPTION, "description
This allows you to provide a text description of the property for use in given users help (see --modhelp for details)
PT_KEYWORD, "name", value 
This allows you to define one or more keyword values to associate with the property (see set and enumeration for details). Note that you must cast constants to appropriate built-in types to avoid argument alignment problems.

Declarations

GL_ATOMIC

GL_ATOMIC types are used strictly for data types that can set as an atomic operation on all platforms.

GL_STRUCT

If the data type cannot be set as an atomic operation, you must use the GL_STRUCT declaration.

GL_STRING

Any data type that is a character array can be declared as GL_STRING to enable string accessors.

GL_ARRAY

Data types that are general arrays can be declared as GL_ARRAY to enable array accessors.

GL_BITFLAGS

Bitmap and bitflags integers can be declared as GL_BITFLAGS to enable bit set and clear accessors.

Example

The following example is taken from the assert module:

Header file (assert.h)
class g_assert : public gld_object {
public:
  typedef enum {AS_INIT=0, AS_TRUE=1, AS_FALSE=2, AS_NONE=3} ASSERTSTATUS;
  GL_ATOMIC(ASSERTSTATUS,status)
  GL_STRING(char1024,target);
  GL_STRING(char32,part); 
  GL_ATOMIC(PROPERTYCOMPAREOP,relation);
  GL_STRING(char1024,value);
  GL_STRING(char1024,value2);
  // ...
};
Implementation file (assert.cpp)
g_assert::g_assert(MODULE *module)
{
  // ...
  if (gl_publish_variable(oclass,
    PT_enumeration,"status",get_status_offset(),PT_DESCRIPTION,"desired outcome of assert test",
      PT_KEYWORD,"TRUE",(enumeration)AS_TRUE,
      PT_KEYWORD,"FALSE",(enumeration)AS_FALSE,
      PT_KEYWORD,"NONE",(enumeration)AS_NONE,
    PT_char1024, "target", get_target_offset(),PT_DESCRIPTION,"the target property to test",
    PT_char32, "part", get_part_offset(),PT_DESCRIPTION,"the target property part to test",
    PT_enumeration,"relation",get_relation_offset(),PT_DESCRIPTION,"the relation to use for the test",
      PT_KEYWORD,"==",(enumeration)TCOP_EQ,
      PT_KEYWORD,"<",(enumeration)TCOP_LT,
      PT_KEYWORD,"<=",(enumeration)TCOP_LE,
      PT_KEYWORD,">",(enumeration)TCOP_GT,
      PT_KEYWORD,">=",(enumeration)TCOP_GE,
      PT_KEYWORD,"!=",(enumeration)TCOP_NE,
      PT_KEYWORD,"inside",(enumeration)TCOP_IN,
      PT_KEYWORD,"outside",(enumeration)TCOP_NI,
    PT_char1024, "value", get_value_offset(),PT_DESCRIPTION,"the value to compare with for binary tests",
    PT_char1024, "within", get_value2_offset(),PT_DESCRIPTION,"the bounds within which the value must bed compared",
    PT_char1024, "lower", get_value_offset(),PT_DESCRIPTION,"the lower bound to compare with for interval tests",
    PT_char1024, "upper", get_value2_offset(),PT_DESCRIPTION,"the upper bound to compare with for interval tests",
  NULL)<1)
     throw "assert property publish failed";
  // ...
}

See also