Proposed for review
engine protocol - GridLAB-D engine link protocol New in 3.1!
The general engine link protocol is implemented using three general message types to maintain engine cache coherence.
- INIT : messages to establish and populate the engine cache.
- SYNC : messages to update the engine cache and synchronize the application's clock with GridLAB-D's clock.
- TERM : messages to provide a final update of the engine cache before GridLAB-D is halted.
UDP Protocol
INIT
The initialization sequence is completed using the following sequence of messages in GridLAB-D's link implementation. Every sequence of messages must be responded to using a status message as follows:
- OK
- The sequence was processed ok.
- ERROR\nmessages
- The sequence was processed but errors were encountered. The messages may be appended separated by newlines (up to the size of the message). Overflow errors are ignored.
- TERM\nmessages
- The engine link is about to shutdown. The reason may be included.
The first part of the sequence transfer basic information about the GridLAB-D environment and the engine link:
recv: INIT send: GRIDLABD major.minor.patch-build (branch) send: PROTOCOL UDP send: CACHESIZE count size send: TIMEOUT seconds recv: status
The second part of the initialization sequence sets up the engine data cache:
send: GLOBAL index type size name value (repeated) send: IMPORT index type size name value (repeated) send: EXPORT index type size name value (repeated) send: status recv: index value (repeated) recv: status
SYNC
Synchronization messages update the engine data cache:
recv: SYNC time recv: index value (repeated 0-N times) recv: status send: index value (repeated 0-N times) send: status
TERM
If termination is initiated by GridLAB-D
recv: SYNC time recv: index value (repeated 0-N times) recv: status send: index value (repeated 0-N times) send: TERM
or if termination is initiative by application
recv: TERM recv: index value (repeated 0-N times) recv: status send: index value (repeated 0-N times) send: TERM
UDP_SHMEM or UDP_MMAP Protocol
The follow protocol is used when SHMEM or MMAP is used. Note that UDP is still used to provide synchronization. But data transfer is completed using share memory to improve performance for larger models.
INIT
recv: INIT send: GRIDLABD major.minor.patch-build (branch) send: PROTOCOL SHMEM -or- MMAP send: CACHESIZE count size send: TIMEOUT seconds send: GLOBAL index type size name value (repeated) send: IMPORT index type size name value (repeated) send: EXPORT index type size name value (repeated) send: status
SYNC
recv: SYNC time send: status
TERM
If termination is initiated by GridLAB-D:
recv SYNC time send TERM
or if termination is initiated by application:
recv TERM send status
Version
The engine link was introduced in Navajo (trunk).