RPCs

Lens applications can define RPCs that can be called by nearby machines. RPCs can take arguments and return values. If you need to synchronize data across machines, you can also use Lens.DB to coordinate between machines.

Calling RPCs

To find an RPC on a particular machine:

var machine = Lens.Machines.machine("some-hostname");
var rpc = machine.rpc("someRPC");

You can also search machine by RPC using Lens.Machines.findByRPC:

var machines = Lens.Machines.findByRPC("someRPC");
if(machines.length == 0) {
    console.log("Couldn't find the RPC");
}
else {
    var rpc = machines[0].rpc("someRPC");
    // so something with rpc
}

To call an RPC:

rpc.call(["argument1", "argument2"]);

Arguments can be any JSON-serializable type. You can specify a callback to receive the return value:

rpc.call(["argument1", "argument2"], function(result) {
    // do something with result
})

For a void RPC (one that doesn't return a value), you can still attach a callback which will be called if the RPC completes without error. result will be true for void RPCs.

rpc.call returns a jQuery Promise, so you can use the promise API to attach callback, as well. This also allows you to attach failure callbacks, which will be called if the RPC throws an error:

rpc.call(["argument1", "argument2"]).done(function(result) {
    // RPC was successful; use result
}).fail(function(errorMessage) {
    // RPC failed; look at errorMessage for details
});

See RPC for more information on the full RPC API, including introspecting on RPCs.

Defining Void RPCs

Use the Machine#registerVoidRPC method of Lens.Machines.localhost to register a void RPC (one that doesn't return a value). Void RPCs can take arguments from the remote machine. In addition, they are executed with "this" set to an object that has an originatingMachine property so RPCs know what machine is calling them.

RPCs can throw errors; the error will be reported to the caller.

Here's a basic example:

Lens.Machines.localhost.registerVoidRPC("alert", function(message) {
    if(alert.length > 100) {
        throw "Message is too long";
    }
    alert("Message from " + this.originatingMachine.name() + ": " + message);
});

Defining Valued RPCs

Use the Machine#registerValuedRPC method of Lens.Machines.localhost to register a valued RPC (one that returns a value).

Similarly to void RPCs, valued RPCs can receive arguments from the remote machine, and are executed with this set to an object that has an originatingMachine property so RPCs know what machine is calling them. In addition, this has two methods, return and throw, that allow the function to return an error asynchronously.

Here's an example of a synchronous valued RPC:

Lens.Machines.localhost.registerValuedRPC("getInput", function(message) {
    if(!message) {
        throw "You must provide a message";
    }

    return prompt(message);
});

And an example of an asynchronous valued RPC:

Lens.Machines.localhost.registerValuedRPC("getInput", function(defaultText) {
    // assign this to that so we can access it inside the callback
    var that = this;

    Lens.Components.TextEntry.getText(defaultText, function(text) {
        if(text.length == 0) {
            that.throw("User didn't enter any text");
        }
        else {
            that.return(text);
        }
    });
});