Tidy up subprocess docs + code

plugins/subprocess/subprocess.cpp

@@ -91,7 +91,6 @@ value Subprocess::get_stream( boost::optional<value> &s, T& (bp::child::* getter
     s.reset( o );
   }
   return *s;
-  //in.assign(.handle().release()); 
 }
 
 value Subprocess::get_stdin() {
@@ -120,9 +119,9 @@ void Subprocess::kill() {
 #include <boost/system/system_error.hpp>
 void Subprocess::send_signal(int sig) {
 #ifdef BOOST_POSIX_API
-  if (::kill(child_.get_id(), sig) == -1) 
+  if (::kill(child_.get_id(), sig) == -1)
     throw boost::system::system_error(
-      boost::system::error_code(errno, boost::system::get_system_category()),
+      error_code(errno, boost::system::get_system_category()),
       "Subprocess#sendSignal"
     );
 #else
@@ -144,12 +143,12 @@ value Subprocess::wait_impl(bool poll) {
 
   value ret;
   using namespace boost::system;
-#if defined(BOOST_POSIX_API) 
-  int s; 
+#if defined(BOOST_POSIX_API)
+  int s;
   pid_t wait = ::waitpid(child_.get_id(), &s, poll ? WNOHANG : 0);
-  
-  if (wait == -1) 
-      boost::throw_exception(system_error(error_code(errno, get_system_category()), "Subprocess: waitpid(2) failed")); 
+
+  if (wait == -1)
+      boost::throw_exception(system_error(error_code(errno, get_system_category()), "Subprocess: waitpid(2) failed"));
 
   if (wait == 0)
     return object();
@@ -164,19 +163,19 @@ value Subprocess::wait_impl(bool poll) {
   else
     ret = object();
 
-#elif defined(BOOST_WINDOWS_API) 
+#elif defined(BOOST_WINDOWS_API)
   DWORD ret = ::WaitForSingleObject(child_.get_process_handle(), poll? 0 : INFINITE);
-  
+
   if (ret == WAIT_FAILED)
-      boost::throw_exception(system_error(error_code(::GetLastError(), get_system_category()), "Subprocess: WaitForSingleObject failed")); 
+      boost::throw_exception(system_error(error_code(::GetLastError(), get_system_category()), "Subprocess: WaitForSingleObject failed"));
 
   if (ret == WAIT_TIMEOUT)
     ret = object();
   else {
 
-    DWORD code; 
+    DWORD code;
     if ( !GetExitCodeProcess(child_.get_process_handle(), &code) )
-        boost::throw_exception(system_error(error_code(::GetLastError(), get_system_category()), "Subprocess: GetExitCodeProcess failed")); 
+        boost::throw_exception(system_error(error_code(::GetLastError(), get_system_category()), "Subprocess: GetExitCodeProcess failed"));
 
     ret = value(code);
   }

plugins/subprocess/subprocess.pdoc

@@ -1,4 +1,4 @@
-// -*- mode:js2; -*-
+// -*- mode:js2; -*- vim: ft=javascript:
 
 /** section: Bundled Modules
  * subprocess
@@ -85,19 +85,20 @@
  **/
 
 /**
- * subprocess.Subprocess#poll() -> null|Integer
+ * subprocess.Subprocess#poll() -> null | Number
  * 
- * Checks if the subprocess is still running. Returns null if the subprocess is
- * still running or else the returncode as an Integer.
+ * Checks if the subprocess has terminated. Returns null if the subprocess is
+ * still running or else sets and returns the `returncode` attribute as an
+ * Integer.
  * 
  * See [[subprocess.Subprocess#returncode]] and [[subprocess.Subprocess#wait]].
  **/
 
 /**
  * subprocess.Subprocess#wait() -> Integer
  * 
- * Waits until the subprocess is finished and returns the returncode as an
- * Integer.
+ * Waits until the subprocess is finished and sets and returns the `returncode`
+ * attribute.
  * 
  * See [[subprocess.Subprocess#returncode]] and [[subprocess.Subprocess#poll]].
  **/
@@ -107,10 +108,21 @@
  * - input (String): data to send to the subprocess.
  * 
  * Write `input` to stdin of the process (if stdin pipe was opened) and read
- * stdout/stderr if opened. Returns an object containing the output of stdout
- * and stderr and the returncode.
+ * stdout/stderr if opened. It is an error to provide input if the stdin stream
+ * was not opened fro writing.
+ *
+ * Returns an object with properties of `returncode` and output of stdout and stderr
+ * streams, or `null` if the streams were not opened.
+ *
+ * For example, the return could look something like:
+ *
+ *     {
+ *       stdout: "Hello world\n",
+ *       stderr: null,
+ *       returncode: 0
+ *     }
  * 
- * This is a safe and fast way to handle the communication.
+ * This is a safe and fast way to handle the communication without deadlocking.
  **/
 
 /**

plugins/subprocess/subprocess_module.cpp

@@ -34,16 +34,16 @@ THE SOFTWARE.
 #ifndef WIN32
 # include <signal.h>
 #else
-# define BOOST_PROCESS_WINDOWS_USE_NAMED_PIPE 
+# define BOOST_PROCESS_WINDOWS_USE_NAMED_PIPE
 #endif
 
 #include <boost/format.hpp>
 #include <boost/logic/tribool.hpp>
 #include <boost/optional.hpp>
-#include <boost/process.hpp> 
+#include <boost/process.hpp>
 
 
-namespace bp = ::boost::process; 
+namespace bp = ::boost::process;
 using boost::optional;
 using boost::format;
 using boost::tribool;
@@ -108,7 +108,7 @@ FLUSSPFERD_LOADER_SIMPLE(exports) {
 namespace {
   std::vector<std::string> array_to_vector(array a) {
     std::vector<std::string> args;
-    
+
     array::iterator const end = a.end();
 
     for(array::iterator i = a.begin(); i != end; ++i) {
@@ -179,24 +179,24 @@ namespace {
       ctx.stderr_behavior = bp::close_stream();
 
     if ( get_bool( o, "shell") ) {
-#if defined(BOOST_POSIX_API) 
-      
+#if defined(BOOST_POSIX_API)
+
       exe = "/bin/sh";
       args.insert( args.begin(), 2, "");
       args[0] = "sh";
       args[1] = "-c";
-#elif defined(BOOST_WINDOWS_API) 
-      char sysdir[MAX_PATH]; 
-      UINT size = ::GetSystemDirectoryA(sysdir, sizeof(sysdir)); 
-      if (!size) 
-          boost::throw_exception(system::system_error(system::error_code(::GetLastError(), system::get_system_category()), "subprocess.popen: GetWindowsDirectory failed")); 
-      BOOST_ASSERT(size < MAX_PATH); 
-
-      exe = std::string(sysdir) + (sysdir[size - 1] != '\\' ? "\\cmd.exe" : "cmd.exe"); 
+#elif defined(BOOST_WINDOWS_API)
+      char sysdir[MAX_PATH];
+      UINT size = ::GetSystemDirectoryA(sysdir, sizeof(sysdir));
+      if (!size)
+          boost::throw_exception(system::system_error(system::error_code(::GetLastError(), system::get_system_category()), "subprocess.popen: GetWindowsDirectory failed"));
+      BOOST_ASSERT(size < MAX_PATH);
+
+      exe = std::string(sysdir) + (sysdir[size - 1] != '\\' ? "\\cmd.exe" : "cmd.exe");
       args.insert( args.begin(), 2, "");
-      args[0] = "cmd"; 
+      args[0] = "cmd";
       args[1] = "/c";
-#endif 
+#endif
     }
 
     bp::child c = bp::launch( exe.get(), args, ctx );
@@ -262,12 +262,5 @@ void subprocess::popen(flusspferd::call_context &x) {
     x.result = create<Subprocess>( boost::fusion::make_vector( child, ctx ) );
   }
 
-
-/*
-  bp::pistream &is = c.get_stdout(); 
-  std::string line; 
-  while (std::getline(is, line)) 
-    std::cout << "Line:" << line << std::endl; 
-*/
 }