Utility classes and functions¶
- class mtrchk.org.momotor.mixin.exec.capture.Capture(cap_stdin=True, cap_stdout=True, cap_stderr=True, *, limits=None, max_size=1048576)¶
Send and capture I/O on stdin/stdout/stderr and records timestamps when each line was sent or received.
Truncates stream if it gets too big. If a stream is truncated, the last record for that stream will contain the boolean value False.
Spools to a buffer in memory until total data size gets bigger than max_size
- lines(t)¶
The total number of lines captured for the stream with id t, where t is one of
STDIN,STDOUTorSTDERR- Return type:
- record()¶
Start recording I/O on stdin/stdout/stderr
- Return type:
- class mtrchk.org.momotor.mixin.exec.capture.CaptureLimits(max_stdout_lines=None, max_stdout_bytes=None, max_stderr_lines=None, max_stderr_bytes=None)¶
Limits for capturing stdout/stderr. The stream will be truncated (no more output captured) if any of the limits are exceeded.
- class mtrchk.org.momotor.mixin.exec.capture.CapturePlayback(file)¶
A class for playing back I/O on stdin/stdout/stderr from a
tempfile.SpooledTemporaryFileas recorded byCaptureRecorder.
- class mtrchk.org.momotor.mixin.exec.capture.CapturePlaybackBase(file)¶
A base class for playing back I/O on stdin/stdout/stderr.
- mtrchk.org.momotor.mixin.exec.capture.CaptureRecord¶
TypeAlias for a capture record. The dictionary contains the following keys:
@(str): The timestamp in seconds since execution start. Contains aDecimaltimestamp.1 (
int): The data on stdout. Contains astrorbytesvalue, or the boolean value False if the stream was truncated at this timestamp2 (
int): The data on stderr. Contains astrorbytesvalue, or the boolean value False if the stream was truncated at this timestamp
- class mtrchk.org.momotor.mixin.exec.capture.CaptureRecorder(file, capture, size, lines, trunc, limits)¶
A class for recording I/O on stdin/stdout/stderr to a
tempfile.SpooledTemporaryFile.- Parameters:
file (
SpooledTemporaryFile) – The file to write the capture tocapture (
tuple[bool,bool,bool]) – A tuple of booleans indicating which streams to capturesize (
list[int]) – A list of 3 integers where the size of the captured data for each stream is recordedlines (
list[int]) – A list of 3 integers where the number of lines of the captured data for each stream is recordedtrunc (
list[bool]) – A list of 3 booleans indicating whether the stream was truncatedlimits (
CaptureLimits) – The limits for capturing stdout/stderr
- add(*args)¶
Add data to the capture.
Expected to be called with 3 arguments, one for each stream. If a stream is not captured, the argument should be None.
- class mtrchk.org.momotor.mixin.exec.capture.CaptureRecorderBase(file, capture, size, lines, trunc, limits)¶
A base class for recording I/O on stdin/stdout/stderr. The base class only records the size and number of lines of the captured data for each stream, and checks capture limits. It does not record the actual data.
- Parameters:
file – The file to write the capture to
capture (
tuple[bool,bool,bool]) – A tuple of booleans indicating which streams to capturesize (
list[int]) – A list of 3 integers where the size of the captured data for each stream is recordedlines (
list[int]) – A list of 3 integers where the number of lines of the captured data for each stream is recordedtrunc (
list[bool]) – A list of 3 booleans indicating whether the stream was truncatedlimits (
CaptureLimits) – The limits for capturing stdout/stderr
- add(*args)¶
Add data to the capture.
Expected to be called with 3 arguments, one for each stream. If a stream is not captured, the argument should be None.
- class mtrchk.org.momotor.mixin.exec.capture.JSONCaptureEncoder(*, ensure_ascii=False, sort_keys=False, **kwargs)¶
JSON encoder to convert
CaptureRecordobjects to JSON. Differs from thejson.JSONEncoderin that it:Generates more compact JSON, by overriding the item_separator and key_separator attributes
ensure_ascii defaults to False
sort_keys defaults to False
Converts
decimal.Decimalobjects to floats
- class mtrchk.org.momotor.mixin.exec.monitor.ChildUsage(utime=0.0, stime=0.0, mem=0)¶
- class mtrchk.org.momotor.mixin.exec.monitor.Reason(*values)¶
An enum for the various reasons a process may be terminated
- class mtrchk.org.momotor.mixin.exec.monitor.ResourceMonitor(parent_pid, process, limits, shell, *, mem_maps_filter=True)¶
A thread to monitor another process and enforce runtime limits.
- join(timeout=None)¶
Wait until the thread terminates.
This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.
When the timeout argument is present and not None, it should be a floating-point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call is_alive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.
When the timeout argument is not present or None, the operation will block until the thread terminates.
A thread can be join()ed many times.
join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.
- Return type:
- run()¶
Check usage of child processes
- class mtrchk.org.momotor.mixin.exec.monitor.RunLimits(timeLimit=None, blockLimit=None, memoryLimit=None, processLimit=None)¶
Runtime limits for a process executed with
MPopen
- class mtrchk.org.momotor.mixin.exec.monitor.Usage(wctime=0.0, utime=0.0, stime=0.0, mem=0, proc=0)¶
- mtrchk.org.momotor.mixin.exec.monitor.verbose_reason: dict[Reason, str] = {Reason.BLOCKLIMIT_EXCEEDED: 'Blocked or deadlocked', Reason.MEMORYLIMIT_EXCEEDED: 'Memory usage limit exceeded', Reason.PROCESSLIMIT_EXCEEDED: 'Too many processes started', Reason.TIMELIMIT_EXCEEDED: 'Time limit exceeded'}¶
Verbose termination reason strings for use in reports and as reason property
- class mtrchk.org.momotor.mixin.exec.mpopen.MPopen(args, limits, mem_maps_filter=True, shell=False, **kwargs)¶
A monitored version of
subprocess.PopenChecklets should use the
ExecutionMixinorCapturedExecutionMixinmixin instead of this class directly.As with
subprocess.Popen, supplyingerrorsenables text mode, even withouttextorencoding.- communicate(input_file, *, input_delay_ms=None)¶
A generator variant of
subprocess.Popen.communicate()that keeps the interleaving on stdin/stdout/stderr intact.Input will be read from input_stream, output on stdout and stderr will be collected. In text mode, CRLF and CR output newlines are converted to LF, including CRLF split across reads. Each output stream keeps its own newline state. A trailing CR becomes LF at EOF. Binary output is unchanged.
- communicate_readonly()¶
A generator variant of
subprocess.Popen.communicate()that keeps the interleaving of output on stdout/stderr intact.No input will be provided on stdin, output on stdout and stderr will be collected.
- status_properties()¶
Get status to use in checklet properties.
- property returncode: int | None¶
The process return code as reported by
subprocess.Popen