fault.system
fault.systemSystem process execution interfaces and process global registry for controlling the composition of Specification for system process execution.
Purpose
Primarily, this process global registry is intended for test cases that need to allow the harness to override the execution methods for selecting the correct executable. However, general purpose usage is reasonable for formalizing system process execution.
Interface
The select callable returns the handler for a given execution method Identifier. This allows the command constructor to be cached for repeat use. The prepare callable selects and invokes the method returning the invocation specification.
Default Methods
python-moduleExecute a Python module available in the sys.path of the Python subprocess.
Types
Symbolic names for annotations used by execution.
- Specification
A pair containing a selector for the executable and the argument vector to be used upon invocation. typing.AnyStr is used to denote the possibility of mixed encoded and decoded strings. Usage may require resolutions depending on the target execution interface.
- Vector
An argument vector used to designate the parameters to a process. A sequence of any string types; this is used from the perspective of a calling process whose arguments may require encoding or conversion.
- Method
Signature of a Specification constructor.
- Identifier
The hashable used to access a Method.
sys
os0
typing0
Identifier0
Identifier = typing.Hashable
Vector0
Vector = typing.Sequence[typing.AnyStr]
Specification0
Specification = typing.Tuple[typing.AnyStr, Vector]
Method0
Method = typing.Callable[[typing.AnyStr, Vector], Specification]
KInvocation0
default_python_script60%
default_python_script(index, script, arguments)
default_python_module60%
default_python_module(index, module, arguments)
default_executable50%
default_executable(index, executable, arguments)
_defaults0
_defaults = (
('python-script', default_python_script),
('python-module', default_python_module),
('executable', default_executable),
)
Index0
Execution Method index associating a set of Identifier's with their corresponding Method's.
Index__slots__0
__slots__ = ('_get', '_storage', '__weakref__')
Index__init__0
__init__(self)
Indexfork325%"Index"
fork(self, methods)
Duplicate the Index instance self and update it with the given methods.
Indexinstall420%Method
install(self, method, new)
Register new as the handler for method and return the previously installed Method. Returns the old Method installed for method identifier.
Indexselect233%Method
select(self, method)
Return the Specification constructor identified by method.
Indexprepare233%Specification
prepare(self, method, executable, arguments)
Construct a pair suitable for creating a fault.system.kernel.Invocation instance.
root0
root = Index()
select0
select = root.select
prepare0
prepare = root.prepare
dataclass0
Delta0
Descriptor of change in a subprocess' state.
Deltaevent0str
event:(str) = None
Deltastatus0int
status:(int) = None
Deltacore0typing.Optional[bool]
core:(typing.Optional[bool]) = None
@property
Deltarunning10%
Deltaexited10%
Deltacored30%
Deltacontinued10%
Deltastopped10%
decode_process_status765%Delta
decode_process_status(status)
The process or SIGCHLD signals. This is an abstraction to os.waitpid and can only be used with child processes.
decode_process_statusParameters
statusint
The status code produced by os.waitpid. (stat_loc)
decode_process_statusExceptions
- ValueError
Raised when the given status code could not be recognized.
reap271%typing.Optional[Delta]
reap(pid, options)
Transform pending process events such as exits into a Delta describing the event. Normally used to respond to process exit events in order to reap the process or SIGCHLD signals. This is an abstraction to os.waitpid and can only be used with child processes.
reapParameters
reapReturns
- None
No status was available due to error.
dereference180%
dereference(invocation)
Execute the given invocation collecting /dev/stdout into a bytes instance. dereference blocks until EOF is read from the created pipe and should only be used to execute reliable processes.
If SIGALRM is not appropriate for timeouts, invocation should be managed directly.
effect20%
effect(invocation)
Execute the given invocation collecting /dev/stderr into a bytes instance. effect blocks until EOF is read from the created pipe and should only be used to execute reliable processes.
perform325%int
perform(invocation)
Execute an invocation waiting for the subprocess to exit before allowing the thread to continue. The invocation will inherit the process' standard input, output, and error.
Returns the status of the subprocess; negative if the process exited due to a signal.
Pipeline0
Structure holding the file descriptors associated with a running pipeline of operating system processes. Returned by called PInvocation instances to provide access to the input and output pipes and the standard errors of each process.
Pipeline__slots__0
__slots__ = ()
@property
Pipelineinput0int
Pipe file descriptor for the pipeline's input.
Pipelineoutput0int
Pipe file descriptor for the pipeline's output.
Pipelineprocess_identifiers0
The sequence of process identifiers of the commands that make up the pipeline.
Pipelinestandard_errors0typing.Sequence[int]
Mapping of process identifiers to the standard error file descriptor.
Pipeline__new__0
__new__(Class, input, output, pids, errfds)
Pipelinevoid70%None
void(self)
Close all file descriptors and terminate all processes (SIGKILL) involved in the pipeline. Processes are not reaped.
PInvocation0
A sequence of fault.system.kernel.Invocation instances used to form a pipeline for system processes; a process image where the file descriptors 0, 1, and 2 refer to standard input, standard output, and standard error.
Pipelines of zero commands can be created; it will merely represent a pipe with no standard errors and no process identifiers.
PInvocation__slots__0
__slots__ = ()
PInvocationInvocation0
Invocation = KInvocation
@classmethod
PInvocationfrom_commands0
from_commands(Class, *commands)
Create a PInvocation instance from a sequences of commands.
pr = libexec.PInvocation.from_commands(
['/bin/cat', '/bin/cat', 'somefile'],
['/usr/bin/tee', 'tee', 'duplicate-1', 'duplicate-2'],
)
The command tuples must specify the absolute path to the executable as the first item, the second item is the program's runtime name that is accessible as the first argument. Often, the basename of the command if it were invoked using PATH resolution.
PInvocationfrom_pairs20%
from_pairs(Class, commands)
Create a Pipeline Invocation from a sequence of process-path and process-arguments pairs.
pr = libexec.PInvocation.from_pairs([("/bin/cat", ("cat", "file", "-")), ...])
PInvocationspawn779%Pipeline
spawn(self, signal)
Execute the series of invocations returning a Pipeline instance containing the file descriptors used for input, output and the standard error of all the commands.
PInvocationspawnParameters
PInvocation__call__0
__call__ = spawn
parse_sx_plan195%typing.Tuple[ typing.Sequence[typing.Tuple[str, str]], str, typing.Sequence[str] ]
parse_sx_plan(text)
Parse a System Execution Plan string into structured environment settings, executable path, and command arguments.
serialize_sx_plan0str
serialize_sx_plan(triple)
Serialize the environment, execution path, and command arguments into a string.
Platform0
Factor Execution Platform structure for defining architecture specific runtimes.
Platformparse_architecture_list0
parse_architecture_list(pfa)
Produce the architectures and their synonyms from a string that uses newline separated records and space separated fields.
Platformfs_load_system0
fs_load_system(path)
Platformfs_load_plans0
fs_load_plans(source, names)
Read the plans identified by names from the given directory, source.
Platformfs_load_sections0
fs_load_sections(Class, path)
Interpret a stored platform emitting section records.
Platformfrom_directory0
from_directory(Class, path)
Create an instance from a platform directory.
Platformfrom_system0
from_system(Class, system, origins)
Compose a Platform from a sequence of paths given that they are extensions of system.
Platform__init__0
__init__(self, system)
Platformpriority0int
priority(self, architecture)
Platformidentify350%
identify(self, architecture)
Select the canonical identifier for the given architecture.
Platformextend0
extend(self, architectures)
Define additional architectures extending the current set.
Platformsections0
sections(self)
Iterate the platform's defined architectures with their synonyms and execution plans.
Platformprepare0
prepare(self, architecture, identifier, argv)
Prepare the necessary information for dispatching an executable with the identified architecture on the host system.