Remote

Communication with other servers at the MAL level is a delicate task. However, it is indispensable for any distributed functionality. This module provides an abstract way to store and retrieve objects on a remote site. Additionally, functions on a remote site can be executed using objects available in the remote session context. This yields in four primitive functions that form the basis for distribution methods: get, put, register and exec.

The get method simply retrieves a copy of a remote object. Objects can be simple values, strings or BATs. The same holds for the put method, but the other way around. A local object can be stored on a remote site. Upon a successful store, the put method returns the remote identifier for the stored object. With this identifier the object can be addressed, e.g. using the get method to retrieve the object that was stored using put.

The get and put methods are symmetric. Performing a get on an identifier that was returned by put, results in an object with the same value and type as the one that was put. The result of such an operation is equivalent to making an (expensive) copy of the original object.

The register function takes a local MAL function and makes it known at a remote site. It ensures that it does not overload an already known operation remotely, which could create a semantic conflict. Deregister a function is forbidden, because it would allow for taking over the remote site completely. C-implemented functions, such as io.print() cannot be remotely stored. It would require even more complicated (byte?) code shipping and remote compilation to make it work. Currently, the remote procedure may only returns a single value.

The choice to let exec only execute functions was made to avoid problems to decide what should be returned to the caller. With a function it is clear and simple to return that what the function signature prescribes. Any side effect (e.g. io.print calls) may cause havoc in the system, but are currently ignored.

This leads to the final contract of this module. The methods should be used correctly, by obeying their contract. Failing to do so will result in errors and possibly undefined behavior.

The resolve() function can be used to query Merovingian. It returns one or more databases discovered in its vicinity matching the given pattern.

MODULE remote;

PATTERN remote.batbincopy():bat[:any];
COMMENT "store the binary BAT data in the BBP and return as BAT";

PATTERN remote.batbincopy(X_0:bat[:any]):void;
COMMENT "dump BAT b in binary form to the stream";

PATTERN remote.batload(X_0:any_1, X_1:int):bat[:any_1];
COMMENT "create a BAT of the given type and size, and load values from the input stream";

PATTERN remote.bintype():void;
COMMENT "print the binary type of this mserver5";

PATTERN remote.connect(X_0:str, X_1:str, X_2:str, X_3:str):str;
COMMENT "returns a newly created connection for uri, using user name and password";

COMMAND remote.connect(X_0:str, X_1:str, X_2:str, X_3:str, X_4:bit):str;
COMMENT "returns a newly created connection for uri, using user name, password and scenario";

PATTERN remote.connect(X_0:str, X_1:str):str;
COMMENT "return a newly created connection for a table. username and password should be in the vault";

COMMAND remote.disconnect(X_0:str):void;
COMMENT "disconnects the connection pointed to by handle (received from a call to connect()";

COMMAND remote.epilogue():void;
COMMENT "release the resources held by the remote module";

PATTERN remote.exec(X_0:str, X_1:str, X_2:str):str...;
COMMENT "remotely executes <mod>.<func> and returns the handle to its result";

PATTERN remote.exec(X_0:str, X_1:str, X_2:str, X_3:ptr, X_4:str...):void;
COMMENT "remotely executes <mod>.<func> using the argument list of remote objects and applying function pointer rcb as callback to handle any results.";

PATTERN remote.exec(X_0:str, X_1:str, X_2:str, X_3:str...):str...;
COMMENT "remotely executes <mod>.<func> using the argument list of remote objects and returns the handle to its result";

PATTERN remote.exec(X_0:str, X_1:str, X_2:str, X_3:str...):void;
COMMENT "remotely executes <mod>.<func> using the argument list of remote objects and ignoring results.";

PATTERN remote.get(X_0:str, X_1:str):any;
COMMENT "retrieves a copy of remote object ident";

COMMAND remote.isalive(X_0:str):int;
COMMENT "check if conn is still valid and connected";

PATTERN remote.put(X_0:str, X_1:any):str;
COMMENT "copies object to the remote site and returns its identifier";

PATTERN remote.register(X_0:str, X_1:str, X_2:str):str;
COMMENT "register <mod>.<fcn> at the remote site";

COMMAND remote.register_supervisor(X_0:str, X_1:str):int;
COMMENT "Register the supervisor uuid at a remote site";

COMMAND remote.resolve(X_0:str):bat[:str];
COMMENT "resolve a pattern against Merovingian and return the URIs";