mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-31 14:15:30 +00:00
3421774080
Message sequencing allows Marionette to provide an asynchronous,
parallel pipelining user-facing interface, limit chances of payload
race conditions, and remove stylistic inconsistencies in how commands
and responses are dispatched internally.
Clients that deliver a blocking WebDriver interface are still be expected
to not send further command requests before the response from the last
command has come back, but if they still happen to do so because of
programming error or otherwise, no harm will be done. This will guard
against bugs such as bug 1207125.
This patch formalises the command and response concepts, and applies
these concepts to emulator callbacks. Through the new message format,
Marionette is able to provide two-way parallel communication. In other
words, the server will be able to instruct the client to perform a
command in a non ad-hoc way.
runEmulatorCmd and runEmulatorShell are both turned into command
instructions originating from the server. This resolves a lot of
technical debt in the server code because they are no longer special-cased
to circumvent the dispatching technique used for all other commands;
commands may originate from either the client or the server providing
parallel pipelining enforced through message sequencing:
client server
| |
msgid=1 |----------->|
| command |
| |
msgid=2 |<-----------|
| command |
| |
msgid=2 |----------->|
| response |
| |
msgid=1 |<-----------|
| response |
| |
The protocol now consists of a "Command" message and the corresponding
"Response" message. A "Response" message must always be sent in reply
to a "Command" message.
This bumps the Marionette protocol level to 3.
r=dburns
r=jgriffin
--HG--
extra : commitid : 1kz4Oa2q3Un
112 lines
3.4 KiB
JavaScript
112 lines
3.4 KiB
JavaScript
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this file,
|
|
* You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
"use strict";
|
|
|
|
const {classes: Cc, interfaces: Ci, utils: Cu} = Components;
|
|
|
|
Cu.import("resource://gre/modules/Log.jsm");
|
|
Cu.import("resource://gre/modules/XPCOMUtils.jsm");
|
|
|
|
const logger = Log.repository.getLogger("Marionette");
|
|
|
|
this.EXPORTED_SYMBOLS = ["Emulator"];
|
|
|
|
/**
|
|
* Represents the connection between Marionette and the emulator it's
|
|
* running on.
|
|
*
|
|
* When injected scripts call the JS routines {@code runEmulatorCmd} or
|
|
* {@code runEmulatorShell}, the second argument to those is a callback
|
|
* which is stored in cbs. They are later retreived by their unique ID
|
|
* using popCallback.
|
|
*
|
|
* @param {function(Object)} sendToEmulatorFn
|
|
* Callback function that sends a message to the emulator.
|
|
* @param {function(Object)} sendToEmulatorFn
|
|
* Callback function that sends a message asynchronously to the
|
|
* current listener.
|
|
*/
|
|
this.Emulator = function(sendToEmulatorFn) {
|
|
this.sendToEmulator = sendToEmulatorFn;
|
|
};
|
|
|
|
/**
|
|
* Instruct the client to run an Android emulator command.
|
|
*
|
|
* @param {string} cmd
|
|
* The command to run.
|
|
* @param {function(?)} resCb
|
|
* Callback on a result response from the emulator.
|
|
* @param {function(?)} errCb
|
|
* Callback on an error in running the command.
|
|
*/
|
|
Emulator.prototype.command = function(cmd, resCb, errCb) {
|
|
assertDefined(cmd, "runEmulatorCmd");
|
|
this.sendToEmulator(
|
|
"runEmulatorCmd", {emulator_cmd: cmd}, resCb, errCb);
|
|
};
|
|
|
|
/**
|
|
* Instruct the client to execute Android emulator shell arguments.
|
|
*
|
|
* @param {Array.<string>} args
|
|
* The shell instruction for the emulator to execute.
|
|
* @param {function(?)} resCb
|
|
* Callback on a result response from the emulator.
|
|
* @param {function(?)} errCb
|
|
* Callback on an error in executing the shell arguments.
|
|
*/
|
|
Emulator.prototype.shell = function(args, resCb, errCb) {
|
|
assertDefined(args, "runEmulatorShell");
|
|
this.sendToEmulator(
|
|
"runEmulatorShell", {emulator_shell: args}, resCb, errCb);
|
|
};
|
|
|
|
Emulator.prototype.processMessage = function(msg) {
|
|
let resCb = this.resultCallback(msg.json.id);
|
|
let errCb = this.errorCallback(msg.json.id);
|
|
|
|
switch (msg.name) {
|
|
case "Marionette:runEmulatorCmd":
|
|
this.command(msg.json.command, resCb, errCb);
|
|
break;
|
|
|
|
case "Marionette:runEmulatorShell":
|
|
this.shell(msg.json.arguments, resCb, errCb);
|
|
break;
|
|
}
|
|
};
|
|
|
|
Emulator.prototype.resultCallback = function(msgId) {
|
|
return res => this.sendResult({result: res, id: msgId});
|
|
};
|
|
|
|
Emulator.prototype.errorCallback = function(msgId) {
|
|
return err => this.sendResult({error: err, id: msgId});
|
|
};
|
|
|
|
Emulator.prototype.sendResult = function(msg) {
|
|
// sendToListener set explicitly in GeckoDriver's ctor
|
|
this.sendToListener("emulatorCmdResult", msg);
|
|
};
|
|
|
|
/** Receives IPC messages from the listener. */
|
|
Emulator.prototype.receiveMessage = function(msg) {
|
|
try {
|
|
this.processMessage(msg);
|
|
} catch (e) {
|
|
this.sendResult({error: `${e.name}: ${e.message}`, id: msg.json.id});
|
|
}
|
|
};
|
|
|
|
Emulator.prototype.QueryInterface = XPCOMUtils.generateQI(
|
|
[Ci.nsIMessageListener, Ci.nsISupportsWeakReference]);
|
|
|
|
function assertDefined(arg, action) {
|
|
if (typeof arg == "undefined") {
|
|
throw new TypeError("Not enough arguments to " + action);
|
|
}
|
|
}
|