1 =Remote Procedure Call=
\r
2 Databoard RPC is a method call interface.
\r
3 Server is an object that handles service requests.
\r
4 The server publishes an [[#Interfaces]] that contains a list of callable methods.
\r
6 ===Network Protocol===
\r
7 The protocol is very simple. There are two conversing peers, one is ''the client'' and the other ''the server''.
\r
8 Both parties introduce callable ''network interface''. Typically, the server's has plenty of procedures, and client's
\r
10 The connection starts with handshake and is then followed by repeating conversation of writing ''Requests'' and reading ''Responses''.
\r
12 In handshake, boths peers write their ''InterfaceDescription'' and message size limits.
\r
13 (See [[#Definitions|Definitions]]).
\r
14 Then both parties make a decision to whether accept or reject the other's interface.
\r
17 ''A function type'' can be constructed as <tt>D -> R</tt>, where <tt>D</tt> is the domain and <tt>R</tt> the range of the function.
\r
18 If the function can throw exceptions, it is denoted as <tt>D -> R throws E<sub>1</sub>, ..., E<sub>k</sub></tt>, where
\r
19 <tt>E<sub>i</sub></tt> is a datatype for an exception. Multi-parameter types can be defined using the tuple notation:
\r
22 (Integer,Integer) -> Integer
\r
23 Integer -> Integer throws IndexOutOfRange
\r
25 ''A method definition'' is a combination of name and method type.
\r
26 The format is following, <tt>method M : T</tt>, where <tt>M</tt> is the name and <tt>T</tt> the type of the method.
\r
27 <tt>T</tt> has to be a function type.
\r
28 method getSamples : TimeSegment -> Sample[],
\r
29 method read : ReadRequest -> Sample,
\r
30 method getValueBounds : TimeSegment -> Sample[2]
\r
32 ''Interface'' is a specification of fields and methods the interface has to have.
\r
33 The interface is defined as a record that contains fields and methods definitions in the curly braces.
\r
34 interface HistoryRecord = {
\r
35 records : TimeSeries,
\r
37 method getSamples : TimeSegment -> Sample[],
\r
38 method read : ReadRequest -> Sample,
\r
39 method getValueBounds : TimeSegment -> Sample[2]
\r
42 Interfaces may extend other interfaces. This is denoted as <tt>interface I extends B<sub>1</sub>, ..., B<sub>k</sub> { ... }</tt>.
\r
43 interface MutableHistoryRecord extends HistoryRecord = {
\r
44 method write : Sample[] -> {},
\r
45 method clear : {} -> {}
\r
49 Client sends RequestHeader, followed by a serialization of the message's request argument.
\r
50 The datatype and thus serialization format of the request argument was defined in MethodType which was informed by the server in the handshake.
\r
52 The server processes the procedure request.
\r
53 * On procedure success, ResponseHeader is sent, followed by a serialization of ResponseType. ResponseType serialization format was declared in MethodType.
\r
54 * On procedure failure, ExecutionError_ is sent, followed by a serialization of ErrorType. ErrorType format was declared in MethodType.
\r
55 * On unexpected error, Exception_ is sent
\r
56 * On invalid method number, InvalidMethodError is sent
\r
57 * On request or response message size exceeded, ResponseTooLargeError is sent
\r
62 methodDefinitions : Map(MethodTypeDefinition, {})
\r
65 type InterfaceDefinition = {
\r
71 requestType : DataType,
\r
72 responseType : DataType,
\r
73 errorType : UnionType
\r
76 type MethodTypeDefinition = {
\r
81 type Handshake = | Version0
\r
84 recvMsgLimit : Integer,
\r
85 sendMsgLimit : Integer,
\r
86 methods : MethodTypeDefinition[]
\r
89 type Message = | RequestHeader RequestHeader
\r
90 | ResponseHeader ResponseHeader
\r
91 | ExecutionError_ ExecutionError_
\r
92 | Exception_ Exception_
\r
93 | InvalidMethodError InvalidMethodError
\r
94 | ResponseTooLarge ResponseTooLarge
\r
96 type RequestHeader = {
\r
97 requestId : Integer,
\r
101 type ResponseHeader = {
\r
102 requestId : Integer
\r
105 type ExecutionError_ = {
\r
106 requestId : Integer
\r
109 type InvalidMethodError = {
\r
110 requestId : Integer
\r
113 type Exception_ = {
\r
114 requestId : Integer,
\r
118 type ResponseTooLarge = {
\r
119 requestId : Integer
\r