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
- Guide to Programming GridLAB-D
- Introduction
- Creating a module
- Creating a class
- Special Topics
- Source documentation
- Validation
- Debugging
- Code templates