class_docstr: Container for a running subprocess. Supports communication with the
  subprocess via stdin and stdout.
class_docstr_tok: ["Container","for","a","running","subprocess",".","Supports","communication","with","the","subprocess","via","stdin","and","stdout","."]
docstr: Close communication and wait for process to terminate. If the "timeout"
  parameter to the constructor was not None, and if the configuration
  setting "datalad.runtime.stalled-external" is set to "abandon",
  the method will return latest after "timeout" seconds. If the subprocess
  did not exit within this time, the attribute "wait_timed_out" will
  be set to "True".
  
  Parameters
  ----------
  return_stderr: bool
    if set to "True", the call will return all collected stderr content
    as string. In addition, if return_stderr is True and the log level
    is 5 or lower, and the configuration setting "datalad.log.outputs"
    evaluates to "True", the content of stderr will be logged.
  
  Returns
  -------
  str, optional
    stderr output if return_stderr is True, None otherwise
code: def close(self, return_stderr=False):
      """
      Close communication and wait for process to terminate. If the "timeout"
      parameter to the constructor was not None, and if the configuration
      setting "datalad.runtime.stalled-external" is set to "abandon",
      the method will return latest after "timeout" seconds. If the subprocess
      did not exit within this time, the attribute "wait_timed_out" will
      be set to "True".
  
      Parameters
      ----------
      return_stderr: bool
        if set to "True", the call will return all collected stderr content
        as string. In addition, if return_stderr is True and the log level
        is 5 or lower, and the configuration setting "datalad.log.outputs"
        evaluates to "True", the content of stderr will be logged.
  
      Returns
      -------
      str, optional
        stderr output if return_stderr is True, None otherwise
      """
  
      if self.runner:
          abandon = self._get_abandon()
  
          # Close stdin to let the process know that we want to end
          # communication. We also close stdout and stderr to inform
          # the generator that we do not care about them anymore. This
          # will trigger process wait timeouts.
          self.generator.runner.close_stdin()
  
          # Process all remaining messages until the subprocess exits.
          remaining = []
          timeout = False
          try:
              for source, data in self.generator:
                  if source == STDERR_FILENO:
                      self.stderr_output += data
                  elif source == STDOUT_FILENO:
                      remaining.append(data)
                  elif source == "timeout":
                      if data is None and abandon is True:
                          timeout = True
                          break
                  else:
                      raise ValueError(
                          f"{self}: unknown source: {source}"
                      )
              self.return_code = self.generator.return_code
  
          except CommandError as command_error:
              lgr.error(
                  "%s subprocess exited with %s (%s)",
                  self,
                  repr(command_error.code),
                  command_error,
              )
              self.return_code = command_error.code
  
          if remaining:
              lgr.debug("%s: remaining content: %s", self, remaining)
  
          self.wait_timed_out = timeout is True
          if self.wait_timed_out:
              lgr.debug(
                  "%s: timeout while waiting for subprocess to exit",
                  self,
              )
              lgr.warning(
                  "Batched process (%s) "
                  "did not finish, abandoning it without killing it",
                  self.generator.runner.process.pid,
              )
  
      result = self.get_requested_error_output(return_stderr)
      self.runner = None
      self.stderr_output = b""
      return result
  
imports: from __future__ import annotations
  import logging
  import os
  import queue
  import sys
  import warnings
  from datetime import datetime
  from operator import attrgetter
  from queue import Queue
  from subprocess import TimeoutExpired
  from typing import Any, Callable, List, Optional, Tuple, Union
  from weakref import ReferenceType, WeakValueDictionary, ref
  from datalad import cfg
  from datalad.runner.coreprotocols import KillOutput, NoCapture, StdErrCapture, StdOutCapture, StdOutErrCapture
  from datalad.runner.gitrunner import GIT_SSH_COMMAND, GitRunnerBase, GitWitlessRunner
  from datalad.runner.nonasyncrunner import STDERR_FILENO, STDOUT_FILENO, _ResultGenerator, run_command
  from datalad.runner.protocol import GeneratorMixIn, WitlessProtocol
  from datalad.runner.runner import WitlessRunner
  from datalad.runner.utils import LineSplitter
  from datalad.support.exceptions import CommandError
  from datalad.utils import auto_repr, ensure_unicode
label_desc: Use image node_id 9 for calling the BatchedCommand obj's underlying member method code with example usage: obj.close(return_stderr) and returns: result