From GridLAB-D Wiki
Jump to: navigation, search

 Proposed for review  --Dchassin 16:34, 30 March 2013 (UTC)

JSON link - JSON link target control file Template:NEW30

Synopsis

GLM file:

link target-control-file;

Target control file:

target json
name link-name
schema NONE|INPUT|OUTPUT|BOTH
buffer buffer-size
address IPv4-addr
request request
port protocol/portnum
servers maximum-connections
timeout time-delay
refresh refresh-time
debug level
uri uri

In addition the general link directives are supported.

Description

The JSON link control file is used establish a JSON-compliant connection to an external program over TCP/IP. It is always referenced by a link directive in a GLM file, i.e.,

link control-file;

In addition to the standard link commands, the link control file may contain one or more of the following commands.

name

Specifies the local name to be used when for the initialization parameter. If not specified the name "gridlabd" is used.

schema

Specifies whether the input and output JSON schemas are transmitted to the external program during the initialization handshake. The default is both.

NONE

Specifies that no schema data is sent during initialization handshake.

INPUT

Specifies that the link input JSON schema is to be transmitted during initialization handshake.

OUTPUT

Specifies that the link output JSON schema is to be transmitted during initialization handshake.

BOTH

Specifies that the both input and output JSON schemas are to be transmitted during initialization handshake.

buffer

Specifies the size (in bytes) of the transfer buffer to use when sending methods and reading results. The default buffer is 1MB.

target

Use the target parameter to select the json link target.

address

Specifies the IP address for the external host connection. The JSON link will initiate the connection if the servers is zero. The default address is 127.0.0.1.

request

Specifies the request string to transmit to the server when servers is 0. The default request is a "/".

port

Specifies the IP protocol and port number to use for the external host connection. The JSON link will initiate the connection if the servers is zero. The default port depends on the protocol:
  • TCP : server portnum + 32768 (by default 39036).
  • UDP : server portnum + 32768 + 1 (by default 39037).
  • HTTP : 80 (this is the default protocol/port)

servers

Specifies the number of servers to operate. If servers is zero, the JSON link will operate as a client (initiating the connection). If servers is positive, exactly that number of servers will be started. If servers is negative an unlimited number of servers will be permitted, created as needed to serve incoming requests.

timeout

Specifies the maximum time that JSON link protocol will wait for a response. The timeout may not exceed the refresh time if it is non-zero. The default timeout is 1 second.

refresh

Establishes the refresh time for the JSON link. The refresh time is the interval (in seconds) at which the link will be synchronized (in real time). If the refresh time is zero, the link is synchronized ever time the internal clock changes.

debug

Sets the debug level for the JSON link. Debug level 0 generates no output. Debug level 1 outputs calls. Debug level 2 outputs packet content.

uri

Set the query URI to use when sending requests. This is usually the path sent to the HTTP server.

Example

GLM file:

link json.link;
clock {
  starttime '2001-01-01 0:00:00';
  stoptime '2001-01-01 1:00:00';
}
class test {
  random x;
  double y;
}
object test:..2 {
  name `test_{id}`;
  x "type:uniform(0,1); refresh:1min";
  y 0.0;
}

Link file (json.link):

target json
schema BOTH
buffer 1048576
address 127.0.0.1
request json.php
port http/80
servers 0
global clock
input test_0.y y0
input test_1.y y1
output test_0.x x0
output test_1.x x1

Once running, the actual JSON data objects are nested inside of a JSON-based protocol control wrapper as described in the JSON link protocol. The inner data contents of these packets are described below. For a list of valid data types and ASCII conversion formats, see built-in types.

The output JSON schema data for this link is:

"schema": {
    "clock": "timestamp global.clock";
    "x0": "random test_0.x",
    "x1": "random test_1.y"
    }

The input JSON schema for this link is:

"schema": {
    "clock": "timestamp global.clock";
    "y0": "double test_0.y",
    "y1": "double test_1.y"
    }

A corresponding example output JSON data object:

"data": {   "clock": "2013-04-09 12:02:15.042";
    "x0": "0.1063242",
    "x1": "0.3569083"
}

And a corresponding example input JSON data object for this link is:

"data": {   "clock": "2013-04-09 12:02:15.143";
    "y0": "0.9552349",
    "y1": "0.7112340"
}

Issues

At this point server operations are not supported using the JSON link capability. It doesn't make a lot of sense because the XML support for server is much better at handling multiple incoming connections asynchronously. Incoming server connections are by their very nature asynchronous but the interaction between the core and glx components is naturally synchronous. As a result, clients could not be synchronized reliably without some additional signalling that GridLAB-D currently does not support through the glx API.

Client receive operations are blocking read operations and performed immediately after the send operation for each server. As a result when multiple links are active, the outbound data is sent to a remote server only after the response from the previous remote server has been received. This doesn't make a lot of sense because a long delay in the first host could hold up sending data to other hosts. This problem is somewhat mitigated by the multi-threaded iterators that allow link synchronizations to proceed in parallel and wait until they are all completed before returning to core's normal sync process. However, multithreading in GridLAB-D is normally limited to the number of available processors, so when the number of links is greater than the number of processors, the problem still exists. This issue has not been addressed yet.

The initialization handshake does not permit reading schemas from remote connections. This would be nice to have because it would allow the remote host to specify the input/output mapping tables rather than requiring the JSON link control file to specify the mapping.

Version

Link directives were introduced in Hassayampa (Version 3.0).

See also