Add popen_handle:wait() parameter and new errors (#5099)

* Add popen_handle:wait() parameter and new errors

Since version 3.2.0 the popen_handle:wait() method has one more parameter and may raise two more errors:
Param timeout
Error TimedOut
Error ChannelIsClosed

* Add popen_handle:wait() parameter and new errors

Fixes previous commit syntax errors

* Add popen_handle:wait() parameter and new errors

Fixes previous commit syntax errors

Author: AArdeev

doc/reference/reference_lua/popen.rst

@@ -745,19 +745,34 @@ Below is a list of all ``popen`` functions and handle methods.
         :param handle ph: handle of a child process created with
                           :ref:`popen.new() <popen-new>` or
                           :ref:`popen.shell() <popen-shell>`
+        :param number timeout: since version 3.2.0. The parameter defines the period in seconds for the method to wait for a resolution.
         :return: (if success) formatted result
         :rtype: res
 
-        Possible raised errors are:
+        Possible raised errors:
 
-        * IllegalParams: an incorrect handle parameter
-        * IllegalParams: called on a closed handle
-        * FiberIsCancelled: cancelled by an outside code
+        * ``IllegalParams``: an incorrect handle parameter
+        * ``IllegalParams``: called on a closed handle
+        * ``FiberIsCancelled``: cancelled by an outside code
+        * ``TimedOut``: since version 3.2.0. The error means that the method has not reached the positive result but has reached the defined **timeout**.
+        * ``ChannelIsClosed``: since version 3.2.0. The error is returned when the target popen handle is closed from another fiber.
 
         The formatted result is a process status table (the same as the
         ``status`` component of the table returned by
         :ref:`popen_handle:info() <popen-info>`).
 
+        **Timeout parameter example**
+
+        ..  code-block:: lua
+          
+            local ph = popen.new(<...>)
+            local res, err = ph:wait({timeout = 1})
+            if res == nil then
+            -- Timeout is reached.
+            assert(err.type == 'TimedOut')
+            <...>
+            end
+
     ..  _popen-close:
 
     ..  method:: close()