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
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).