issue #1 closed. add sandboxIn to callback args

doc/api.markdown

@@ -54,7 +54,7 @@ Removes a script by name.
 
 `name` is an arbitrary script identifier as previously passed to `addScript`.
 
-## .runScript(name, sandbox, callback)
+## .runScript(name, sandboxIn, callback)
 
 Runs the script and calls back with the result.
 
@@ -65,20 +65,19 @@ Runs the script and calls back with the result.
 `callback` is a function that is called back when the script has completed
 running in some child process.  
 
-The arguments to the callback are `(error, response)`.  
+The arguments to the callback are `(error, sandboxIn, sandboxOut)`.  
 
 If the child was killed for taking too much time or using too much memory, the
-`error` argument will be an `Error` object a `message` equal to one of the
-`ERR_*` constants of the `jefe` module.
+`error` argument will be a `String` message equal to one of the `ERR_*`
+constants of the `jefe` module (e.g. `jefe.ERR_TOO_MUCH_TIME`).
 
 If the script was run successfully but threw an exception, the `error` argument
-will equal an `Error` object equal to the message of the exception thrown by
-the script, and `response` will equal `null`.
+will equal a `String` message equal to the exception thrown by the script.
 
 If the script was run successfully and did not throw an exception, the `error`
-argument will equal `null`, and `response` will equal the "globals" at the time
-the run of the script ended.  Note that the `sandbox` object argument to
-`runScript` is never altered.
+argument will equal `null`, `sandboxIn` will be the original input sandbox
+object, and `sandboxOut` will be the "globals" at the time the run of the
+script ended.  
 
 ## .getScriptStats(name)
 

examples/circumference.js

@@ -46,19 +46,20 @@ try {
 
 var nDone = 0;
 for (var i = 0; i < 10; ++i) {
-  elJefe.runScript(scriptName, { R:i+1 }, function (error, updatedSandbox) {
+  elJefe.runScript(scriptName, { R:i+1 }, function (error, sandboxIn, sandboxOut) {
 
     // If there's a problem with Jefe (bug; someone else killed the child
     // process from the outside; etc.) then `error` will be a message
     // indicating what went wrong.  If `error == jefe.ERR_TOO_MUCH_TIME` then
     // the script took too long to finish.  If `error == jefe.ERR_TOO_MUCH_MEMORY` 
     // then the script used too much memory.  Otherwise, if `error` is non-null 
     // then the script threw an exception.  If `error === null` then the 
-    // `updatedSandbox` contains the contents of the sandbox at script end.
+    // `sandboxOut` contains the contents of the sandbox at script end.
 
     if (error) throw new Error(error); 
 
-    sys.puts("The circumference of a circle with radius " + updatedSandbox.R + " = " + updatedSandbox.C);
+    sys.puts("The circumference of a circle with radius " + sandboxIn.R + 
+             " equals " + sandboxOut.C);
 
     if (++nDone == 10) finalize();
   });

examples/simple.js

@@ -6,10 +6,14 @@ var
 
 elJefe.addScript(scriptName, "FOOBAR=1");
 
-elJefe.runScript(scriptName, { FOOBAR: 2 }, function (error, response) {
-  if (error)  
-    sys.log("[EXAMPLE/SIMPLE] error = " + error);
-  else 
-    sys.log("[EXAMPLE/SIMPLE] response = " + JSON.stringify(response));
+elJefe.runScript(scriptName, { FOOBAR: 2 }, function (error, sandboxIn, sandboxOut) {
+  if (error) {
+    sys.log("error = " + error);
+  } else {
+    sys.log("sandboxIn  = " + JSON.stringify(sandboxIn));
+    sys.log("sandboxOut = " + JSON.stringify(sandboxOut));
+  }
+
+  process.exit(0);
 });
 

lib/jefe.js

@@ -347,9 +347,9 @@ Jefe.prototype._runRequestOnChild = function (request, childIndex) {
       throw new Error("Internal error: malformed response = " + JSON.stringify(response));
 
     if (response.body.exception)
-      request.callback(response.body.exception, null);
+      request.callback(response.body.exception, request.sandbox, null);
     else if (response.body.sandbox)
-      request.callback(null, response.body.sandbox);
+      request.callback(null, request.sandbox, response.body.sandbox);
     else 
       throw new Error("Internal error: response=" + JSON.stringify(response));