class_docstr: Subprocess communication protocol base class for `run_async_cmd`
  
  This class implements basic subprocess output handling. Derived classes
  like `StdOutCapture` should be used for subprocess communication that need
  to capture and return output. In particular, the `pipe_data_received()`
  method can be overwritten to implement "online" processing of process
  output.
  
  This class defines a default return value setup that causes
  `run_async_cmd()` to return a 2-tuple with the subprocess's exit code
  and a list with bytestrings of all captured output streams.
docstr: Called if the timeout parameter to WitlessRunner.run()
  is not `None` and a process file descriptor could not
  be read (stdout or stderr) or not be written (stdin)
  within the specified time in seconds, or if waiting for
  a subprocess to exit takes longer than the specified time.
  
  stdin timeouts are only caught when the type of the `stdin`-
  parameter to WitlessRunner.run() is either a `Queue`,
  a `str`, or `bytes`. `Stdout` or `stderr` timeouts
  are only caught of proc_out and proc_err are `True` in the
  protocol class. Process wait timeouts are
  always caught if `timeout` is not `None`. In this case the
  `fd`-argument will be `None`.
  
  fd:
    The file descriptor that timed out or `None` if no
    progress was made at all, i.e. no stdin element was
    enqueued and no output was read from either stdout
    or stderr.
  
  return:
    If the callback returns `True`, the file descriptor
    (if any was given) will be closed and no longer monitored.
    If the return values is anything else than `True`,
    the file-descriptor will be monitored further
    and additional timeouts might occur indefinitely.
    If `None` was given, i.e. a process runtime-timeout
    was detected, and `True` is returned, the process
    will be terminated.
docstr_tok: ["Called","if","the","timeout","parameter","to","WitlessRunner.run","(",")","is","not","`","None","`","and","a","process","file","descriptor","could","not","be","read","(","stdout","or","stderr",")","or","not","be","written","(","stdin",")","within","the","specified","time","in","seconds",",","or","if","waiting","for","a","subprocess","to","exit","takes","longer","than","the","specified","time",".","stdin","timeouts","are","only","caught","when","the","type","of","the","`","stdin","`","-","parameter","to","WitlessRunner.run","(",")","is","either","a","`","Queue","`",",","a","`","str","`",",","or","`","bytes","`",".","`","Stdout","`","or","`","stderr","`","timeouts","are","only","caught","of","proc_out","and","proc_err","are","`","True","`","in","the","protocol","class",".","Process","wait","timeouts","are","always","caught","if","`","timeout","`","is","not","`","None","`",".","In","this","case","the","`","fd","`","-argument","will","be","`","None","`",".","fd",":","The","file","descriptor","that","timed","out","or","`","None","`","if","no","progress","was","made","at","all",",","i.e",".","no","stdin","element","was","enqueued","and","no","output","was","read","from","either","stdout","or","stderr",".","return",":","If","the","callback","returns","`","True","`",",","the","file","descriptor","(","if","any","was","given",")","will","be","closed","and","no","longer","monitored",".","If","the","return","values","is","anything","else","than","`","True","`",",","the","file-descriptor","will","be","monitored","further","and","additional","timeouts","might","occur","indefinitely",".","If","`","None","`","was","given",",","i.e",".","a","process","runtime-timeout","was","detected",",","and","`","True","`","is","returned",",","the","process","will","be","terminated","."]
code: def timeout(self, fd: Optional[int]) -> bool:
      """
      Called if the timeout parameter to WitlessRunner.run()
      is not `None` and a process file descriptor could not
      be read (stdout or stderr) or not be written (stdin)
      within the specified time in seconds, or if waiting for
      a subprocess to exit takes longer than the specified time.
  
      stdin timeouts are only caught when the type of the `stdin`-
      parameter to WitlessRunner.run() is either a `Queue`,
      a `str`, or `bytes`. `Stdout` or `stderr` timeouts
      are only caught of proc_out and proc_err are `True` in the
      protocol class. Process wait timeouts are
      always caught if `timeout` is not `None`. In this case the
      `fd`-argument will be `None`.
  
      fd:
        The file descriptor that timed out or `None` if no
        progress was made at all, i.e. no stdin element was
        enqueued and no output was read from either stdout
        or stderr.
  
      return:
        If the callback returns `True`, the file descriptor
        (if any was given) will be closed and no longer monitored.
        If the return values is anything else than `True`,
        the file-descriptor will be monitored further
        and additional timeouts might occur indefinitely.
        If `None` was given, i.e. a process runtime-timeout
        was detected, and `True` is returned, the process
        will be terminated.
      """
      return False
  
imports: from __future__ import annotations
  import logging
  import subprocess
  import warnings
  from collections import deque
  from locale import getpreferredencoding
  from typing import Any, Optional
  from datalad.utils import ensure_unicode
  from .exception import CommandError
label_desc: Use image node_id 8 for calling the WitlessProtocol obj's underlying member method code with example usage: obj.timeout(fd) and returns: False