Runtime module API

---

Detailed Description

The GridLAB-D external module header file.

The runtime module API links the GridLAB-D core to modules that are created to perform various modeling tasks. The core interacts with each module according to a set script that determines which exposed module functions are called and when. The general sequence of calls is as follows:

• Registration: A module registers the object classes it implements and registers the variables that each class publishes.
• Creation: The core calls object creation functions during the model load operation for each object that is created. Basic initialization can be completed at this point.
• Definition: The core sets the values of all published variables that have been specified in the model being loaded. After this is completed, all references to other objects have been resolved.
• Validation: The core gives the module an opportunity to check the model before initialization begins. This gives the module an opportunity to validate the model and reject it or fix it if it fails to meet module-defined criteria.
• Initialization: The core calls the final initialization procedure with the object's full context now defined. Properties that are derived based on the object's context should be initialized only at this point.
• Synchronization: This operation is performed repeatedly until every object reports that it no longer expects any state changes. The return value from a synchronization operation is the amount time expected to elapse before the object's next state change. The side effect of a synchronization is a change to one or more properties of the object, and possible an update to the property of another object.

Note that object destruction is not supported at this time.

GridLAB-D modules usually require a number of functions to access data and interaction with the core. These include

• memory locking,
• memory exception handlers,
• variable publishers,
• output functions,
• management routines,
• module management,
• class registration,
• object management,
• property management,
• object search,
• random number generators, and
• time management.

Todo:

Many of the module API macros would be better implemented as inline functions (ticket #9)

Modules
	Publishing variables
	Modules must register public variables that are accessed by other modules, and the core by publishing them.
	Exception handling
	Module exception handling is provided for modules implemented in C to perform exception handling, as well to allow C++ code to throw exceptions to the core's main exception handler.
	Output functions
	Module may output messages to stdout, stderr, and the core test record file using the output functions.
	Memory allocation functions
	The core is responsible for managing any memory that is shared.
	Core access functions
	Most module function use core library functions and variables.
	Class registration
	Class registration is used to make sure the core knows how objects are implemented in modules.
	Object management
	Object management macros are create to allow modules to create, test, control ranks, and reveal members of objects and registered classes.
	Property management
	Use the property management functions to provide and gain access to published variables from other modules.
	Object search
	Searches and navigates object lists.
	Random numbers
	The random number library provides a variety of random number generations for different distributions.
	Time handling functions
	Global variables
	Locking memory
Defines
#define	CDECL
#define	EXPORT   CDECL
#define	EXTERN   extern
#define	gl_get_oflags   (*callback->get_oflags)
#define	INIT(X)
#define	PADDR(X)   ((char*)&(this->X)-(char*)this)
	The PUBLISH_SET(C,N,E) macro is used to define a keyword for a set variable.

---

GridLAB-D^TM Version 1.0

An open-source project initiated by the US Department of Energy