From GridLAB-D Wiki
Jump to: navigation, search

Class functions - Required and optional class export functions

Synopsis

Required functions
EXPORT_CREATE(class);
EXPORT_LOADMETHOD(class,method);  PROPOSED FOR 3.1  See Ticket 797
EXPORT_INIT(class);
Optional functions
EXPORT_PRECOMMIT(class);
EXPORT_SYNC(class);
EXPORT_COMMIT(class);
EXPORT_FINALIZE(class);
EXPORT_NOTIFY(class);
EXPORT_NOTIFY_PROP(class,property);
EXPORT_ISA(class);
EXPORT_PLC(class);
User defined functions
EXPORT int64 (*call-address)(OBJECT *obj, ...);
gl_publish_function(CLASS *class, const char *function_name, FUNCTIONADDR call-address);

Required functions

constructor

The constructor for a class is actually only called once to register the class with the core. Usually the new call is done in the init.cpp right after the global variables are declared, i.e.,

new myclass(module);

The constructor template is as follows

myclass::myclass(MODULE *module)
{
   if ( oclass==NULL )
   {
      oclass = gld_class::create(module,"myclass", sizeof(myclass), options);
      if ( oclass==NULL ) throw "unable to construct myclass";
      else oclass->trl = TRL_UNKNOWN;
      defaults = this;
      if ( gl_publish_variable(oclass,
        // TODO add variables to publish here
        NULL)<1 ) throw "unable to publish myclass variables";
      memset(this,0,sizeof(myclass)); // this should not be done if virtual functions are used
   }
}

create

The create function is called whenever an object for a class is instantiated. The create process is typically used to construct the object in memory and set the pre-initialization default values, if any. Every GridLAB-D class must export the create function and define it in that class as follows:

class.h
#include "gridlabd.h"
class class {
  // other declarations ...
public:
  int create(void);
}
class.cpp
#include "class.h"
EXPORT_CREATE(class-name);
int class::create(void)
{
   memcpy(this,defaults,sizeof(*this));
   // TODO add other pre-initialization defaults here
   return 1; // return 0 on failure
}

loadmethod

 PROPOSED FOR 3.1  See Ticket 797

The loadmethod functions are called whenever the main GLM loader encounters a registered term while parsing a GLM file.

[[#loadmethod|EXPORT_LOADMETHOD(class,method);
int class::method(char* value)
{
   // parse value
   // return 0 on failure, 1 on success
   return 1;
}

init

The init function is called whenever an object is initialized. The initialization process is typically used to setup the object in memory and adjust default values, if any. Every GridLAB-D class must export the init function and define it in that class as follows:

class.h
#include "gridlabd.h"
class class {
  // other declarations ...
public:
  int init(void);
}
class.cpp
#include "class.h"
EXPORT_INIT(class-name);
int class::init(void)
{
   // TODO add initialization process here
   return 1; // return 0 on failure, return 2 to defer
}

The initialization sequence can be controlled by the user or by a module by setting the init_sequence global variable. When deferred initialization is allowed, certain objects defer their initialization until after other objects have been initialized. See Initialization for details.

Optional functions

precommit

The precommit function is called whenever the clock is has just advanced and the internal states of properties have just been synchronized. The precommit process is called only once per timestep and is typically used to prepare objects for the upcoming sequence of synchronization iterations. The function is implemented as follows:

class.h
#include "gridlabd.h"
class class {
  // other declarations ...
public:
  int precommit(TIMESTAMP t0);
}
class.cpp
#include "class.h"
EXPORT_PRECOMMIT(class-name);
int class::precommit(TIMESTAMP t0)
{
   // TODO add precommit process here
   return 1; // return 0 on failure
}

sync

The presync, sync, and postsync functions are called whenever the main synchronization loop is iterating. The sync processes are called as many times as necessary to resolve a distinct time to which the global clock should advance. As long as at least one object returns the current time, the clock will not advance. The functions are implemented as follows:

class.h
#include "gridlabd.h"
class class {
  // other declarations ...
public:
  TIMESTAMP presync(TIMESTAMP t0);
  TIMESTAMP sync(TIMESTAMP t0);
  TIMESTAMP postsync(TIMESTAMP t0);
}
class.cpp
#include "class.h"
EXPORT_SYNC(class-name);
int class::presync(TIMESTAMP t0)
{
   TIMESTAMP t1 = TS_NEVER;
   // TODO add pre-topdown sync process here
   // TODO set t1 to time of next event
   return t1; // return TS_INVALID on failure
}
int class::sync(TIMESTAMP t0)
{
   TIMESTAMP t1 = TS_NEVER;
   // TODO add bottom-up sync process here
   // TODO set t1 to time of next event
   return t1; // return TS_INVALID on failure
}
int class::postsync(TIMESTAMP t0)
{
   TIMESTAMP t1 = TS_NEVER;
   // TODO add post-topdown sync process here
   // TODO set t1 to time of next event
   return t1; // return TS_INVALID on failure
}
Note
Not all sync functions are used by every class. The determination of which sync functions are called is made by the pass control flags when the class is registered.

commit

The commit function is called after the main synchronization process is completed and the next clock timestep has been determined. The commit process is called only once per timestep and is typically used to wrap up objects after sequence of synchronization iterations. The function is implemented as follows:

class.h
#include "gridlabd.h"
class class {
  // other declarations ...
public:
  TIMESTAMP commit(TIMESTAMP t0);
}
class.cpp
#include "class.h"
EXPORT_COMMIT(class-name);
TIMESTAMP class::commit(TIMESTAMP t0)
{
   TIMESTAMP t1 = TS_NEVER;
   // TODO add commit process here
   // TODO set t1 if soft or hard event is pending
   return t1; // return TS_INVALID on failure
}

Certain objects may be given observer status and allowed to defer their commit processing until after all non-observer objects have completed their commits. See creating observer classes for details.

finalize

The optional finalize function is called after the simulation loop has completed. It is called for all objects after leaving the loop, whether the simulation was successful or not. It takes no arguments and should assume that other objects have already been finalized and disposed of. The objects themselves should not be deconstructed or free'd, which is the responsibility of the core itself.

class.h
#include "gridlabd.h"
class class {
  // other declarations ...
public:
  int64 finalize();
}
class.cpp
#include "class.h"
EXPORT_FINALIZE(class-name);
int64 class::finalize()
{
   // TODO add finalize process here
   return 1; // 1 or SUCCESS on completion.
}

Finalize() is the last call that the exec loop will make to an object. If not present, the block will simply be free()'d without fanfare.

notify

 TODO: 

notify_property

 TODO: 

isa

 TODO: 

plc

 TODO: 

User-defined functions

 TODO: 

See also