monitor() should return on timeout; docstring changes

It appears that read() has been blocking for some time,
so for now it makes sense to change the documentation to
match the functionality!

It's not entirely clear if monitor() expects this functionality.
However, with the current blocking read() semantics, it should
definitely return (and not call read()) on a poll timeout.

So, we now return the poll() result from waitReadable() (which
should have done this already probably) and check it. In the
fullness of time, we still need to revisit the whole I/O API
and make sure that it is consistent, sane, correctly documented,
and used correctly in the examples.

See #588 for more comments.

mininet/node.py

@@ -212,7 +212,7 @@ class Node( object ):
     # Subshell I/O, commands and control
 
     def read( self, maxbytes=1024 ):
-        """Buffered read from node, non-blocking.
+        """Buffered read from node, potentially blocking.
            maxbytes: maximum number of bytes to return"""
         count = len( self.readbuf )
         if count < maxbytes:
@@ -227,7 +227,7 @@ class Node( object ):
         return result
 
     def readline( self ):
-        """Buffered readline from node, non-blocking.
+        """Buffered readline from node, potentially blocking.
            returns: line (minus newline) or None"""
         self.readbuf += self.read( 1024 )
         if '\n' not in self.readbuf:
@@ -259,9 +259,10 @@ class Node( object ):
 
     def waitReadable( self, timeoutms=None ):
         """Wait until node's output is readable.
-           timeoutms: timeout in ms or None to wait indefinitely."""
+           timeoutms: timeout in ms or None to wait indefinitely.
+           returns: result of poll()"""
         if len( self.readbuf ) == 0:
-            self.pollOut.poll( timeoutms )
+            return self.pollOut.poll( timeoutms )
 
     def sendCmd( self, *args, **kwargs ):
         """Send a command, followed by a command to echo a sentinel,
@@ -303,7 +304,9 @@ class Node( object ):
            Set self.waiting to False if command has completed.
            timeoutms: timeout in ms or None to wait indefinitely
            findPid: look for PID from mnexec -p"""
-        self.waitReadable( timeoutms )
+        ready = self.waitReadable( timeoutms )
+        if not ready:
+            return ''
         data = self.read( 1024 )
         pidre = r'\[\d+\] \d+\r\n'
         # Look for PID