From GridLAB-D Wiki
Jump to: navigation, search

 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 McNary (trunk).

See also