process8772%`python.module`
fault.system

Process invocation and management interfaces.

sys
import

os0
import

signal0
import

functools0
import

contextlib0
import

typing0
import

types0
import

builtins0
import

kernel0
import

runtime0
import

thread0
import

files0
import

__control_lock__0
data

__control_lock__ = thread.amutex()

__interject_lock__0
data

__interject_lock__ = thread.amutex()

controlled0
data

controlled = __control_lock__.locked

current_process_id0
data

current_process_id = os.getpid()

parent_process_id0
data

parent_process_id = os.getppid()

main_thread_id0
data

main_thread_id = thread.identify()

index0
data

index = {
	'root': ('thread', thread.identify(), None),
}

__fork_lock__0
data

__fork_lock__ = thread.amutex()

fork_prepare_callset0
data

fork_prepare_callset = set()

fork_parent_callset0
data

fork_parent_callset = set()

fork_child_callset0
data

fork_child_callset = set()

fork_child_cleanup0
data

fork_child_cleanup = set()

getattr0
data

getattr=getattr

signal_codes166%
data

Mapping of categorized signal names to signal (integer) codes.

signal_codes = {
	'process/suspend': signal.SIGTSTP,
	'process/resume': signal.SIGCONT,
	'process/stop': signal.SIGSTOP,
	'process/continue': signal.SIGCONT,
	'process/terminate' : signal.SIGTERM,
	'process/quit' : signal.SIGQUIT,
	'process/interrupt' : signal.SIGINT,
	'process/kill' : signal.SIGKILL,

	'limit/cpu': signal.SIGXCPU,
	'limit/file': signal.SIGXFSZ,
	'limit/time': signal.SIGVTALRM,

	'terminal/stop': signal.SIGTSTP,
	'terminal/query': getattr(signal, 'SIGINFO', None) or getattr(signal, 'SIGUSR1', None),
	'terminal/delta': getattr(signal, 'SIGWINCH', None),
	'terminal/closed': signal.SIGHUP,
	'terminal/background-read': signal.SIGTTIN,
	'terminal/background-write': signal.SIGTTOU,

	'user/1': signal.SIGUSR1,
	'user/2': signal.SIGUSR2,

	'exception/floating-point': signal.SIGFPE,
	'exception/broken-pipe': signal.SIGPIPE,

	'error/invalid-memory-access': signal.SIGBUS,
	'error/restricted-memory-access': signal.SIGSEGV,
	'error/invalid-instruction': signal.SIGILL,
	'error/invalid-system-call': signal.SIGSYS,
}

signals0
data

signals = signal_codes

signal_names0
data

Mapping of signal (integer) codes to categorized names.

signal_names = dict([(v, k) for k, v in signal_codes.items()])

fatal_signals0
data

Set of signals that would cause an immediate exit if SIG_DFL were set.

fatal_signals = {
	signal.SIGINT,
	signal.SIGTERM,
	getattr(signal, 'SIGXCPU', None),
	getattr(signal, 'SIGXFSZ', None),
	getattr(signal, 'SIGVTALRM', None),
	getattr(signal, 'SIGPROF', None),
	getattr(signal, 'SIGUSR1', None),
	getattr(signal, 'SIGUSR2', None),
}

signal_identifiers0
data

Mapping of signal codes to identifiers used in POSIX header files.

signal_identifiers = {
	getattr(signal, name): name
	for name in dir(signal)
	if name.startswith('SIG') and name[3] != '_' and isinstance(getattr(signal, name), int)
}

interject0
function

interject(main_thread_exec)

Trip the main thread by sending the process a SIGUSR2 signal in order to cause any running system call to exit early. Used in conjunction with fault.system.runtime.interject

clear_atexit_callbacks50%
function

clear_atexit_callbacks()

In cases where there may be process dependent callbacks, add this to the fork_child_callset to clear the callbacks.

_after_fork_parent340%
function

_after_fork_parent(child_pid)

_after_fork_child1135%
function

_after_fork_child()

Exit0
class

SystemExit

Extension of SystemExit for use with interjections.

Exit unspecified_status_code
data

unspecified_status_code = 255

Exit usage_query_code
data

usage_query_code = 200

Exit raised0
method

raised(self)

Invocation0
class

object

A structure representing the invocation of a system process and the specification of the means of exiting. Normally, used to describe how the process was invoked and the corresponding parameters, argv and environ, in which the invocation should be reacting to.

For system invocation, the parameters dictionary will have two entries by default: 'system' and 'type'.

Invocation context
data

The Invocation that caused the creation of this Invocation. By default and when created from system, this property is None.

context = None

Invocation parameters
data

Arbitrary storage for the parameteres of the invocation. Usually, 'type', 'system', and 'structured' keys are present.

parameters = None

Invocation init0
method

__init__(self, exit_method)

Invocation exit0
method

exit(self, result)

Perform the exit method designated during the initialization of the invocation.

Invocation fs_pwd0
property

The working directory of the process when the Invocation was created.

Invocation argv0
property

Arguments provided by the system without the leading command name.

Invocation args0
data

args = argv
	@property

Invocation environ0
property
`dict`

The environment variables collected from the system during the creation of the instance.

Invocation imports271%
method

imports(self, envvars)

Copy the given envvars from os.environ into the invocation's parameters. The snapshot of imported environment variables may be accessed using environ.

Invocation imports Parameters

self: Undocumented.
envvars: typing.Iterable[str]
The collection of variables to copy from the environment.

Invocation system664%
classmethod

system(Class, context, environ)

Create an instance representing that of the invocation from the operating system. Primarily, information is retrieved from the sys and os module.

Invocation system Parameters

Class: Undocumented.
context: A reference context identifying the Invocation caused this invocation to be created.
environ: Sequence declaring the environment variables to acquire a snapshot of.
isinstance: Undocumented.
str: Undocumented.

Invocation system_exit_method0
classmethod

system_exit_method(Class, exit_status)

A means of exit used with a Fork.trap managed process.

Injecting the exception on the main thread, this can also be used within regular Python processes.

ControlException0
class

BaseException

Process control exceptions for significant events.

This is a control exception inheriting from BaseException. It should not be directly trapped, but subclasses may use it to classify exceptions that are not necessarily indicative of a failure.

ControlException kill
data

__kill__ = None

ControlException raised0
method

raised(self)

Critical0
class

ControlException

An exception used to communicate that a fatal condition was identified.

Critical kill
data

__kill__ = True

panic0
function

panic()

Raise a Critical exception in the main thread forcing the process to exit.

Interruption0
class

ControlException

Similar to KeyboardInterrupt, but causes control to exit with the signal, and calls critical status hooks.

Primarily used to cause signal exit codes that are usually masked with KeyboardInterrupt.

Interruption kill
data

__kill__ = True

Interruption init20%
method

__init__(self, type)

Interruption str70%
method

__str__(self)

Interruption raised40%
method

raised(self)

Interruption interrupt30%
classmethod

interrupt(Class, signo, frame)

Signal handler that interjects an Interruption instance into the main thread.

Default signal handler for SIGINT.

Interruption void0
staticmethod

void(signo, frame)

Python-level signal handler that does nothing.

Interruption filter0
classmethod

filter(Class, *sigs)

Assign the void signal handler to the all of the given signal numbers.

Interruption catch0
classmethod

catch(Class, *sigs)

Assign the interrupt signal handler to the all of the given signal numbers.

Interruption trap0
classmethod

trap(Class)

Signal handler for a root process.

Fork0
class

ControlException

Exception used to signal Fork.trap to replace the existing managed call.

Usual case is that a Fork.trap call is made on the main thread where other threads are created to run the actual program. Given that the program is finished and another should be ran as if the current program were never ran, the ControlException can be raised in the main thread replacing the initial callable given to Fork.trap.

The exception should only be used through the provided classmethods.

This exception should never be displayed in a traceback as it is intended to be caught by Fork.trap.

Fork __controlled_thread_id__
data

__controlled_thread_id__ = None

Fork init0
method

__init__(self, controller, *args, **kw)

Fork str10%
method

__str__(self)

Fork pivot40%
method

pivot(self, T)

Fork substitute0
classmethod

substitute(Class, callable, *args, **kw)

Substitute the existing control call with the given one.

Immediately raises a Fork instance in the calling thread to be caught by a corresponding trap call.

Only to be used in cases where it is known that the current frame stack is being managed by trap.

Fork dispatch657%
classmethod
`int`

dispatch(Class, controller, *args, **kw)

Execute the given callable with the given arguments in a child process. This performs an interject call. Given that pivot was called to execute the program, the pivot function will catch the exception, in the child, and execute the replacement.

Fork dispatch Parameters

Class: Undocumented.
controller: The object that will be called in the clone.
args: Arguments given to the callable.
kw: Keywords given to the callable.

Fork dispatch Returns

int: The child process' PID.

Fork dispatch Exceptions

Critical: Raised when the returns in the branches did not return.

Fork trap190%
classmethod

trap(Class, controller, *args, **kw)

Establish a point for substituting the process. Trap provides an exception trap for replacing the controlling stack. This is used to perform safe fork operations that allow tear-down of process specific resources in a well defined manner.

	NOTE
	Due to the varying global process state that may exist in a given process, it is often better to start a new Python instance.

critical190%
function

critical(context, callable, *args, **kw)

A callable used to trap exceptions and interject a Critical instance caused by the original. This function is intended for critical sections where the failure is likely to cause the application to become unresponsive via usual routes.

critical may return, but must never raise.

For example:

from fault.system.process import critical

def fun():
	while True:
		# critical loop
		# any exception causes the process to terminate
		...

critical(None, fun)

protect100%
function

protect(*init)

Perpetually protect the main thread using a sleep loop that can only exit using an interjection.

Used by control to hold the main thread in Fork.trap for applications that rely on a set of threads to perform the actual work.

protect Exceptions

Critical: Raised in cases where the infinite loop exits.
Exit: Raised by an application thread using interject.

control1056%
function

control(main, *args, **kw)

A program that calls this is making an explicit declaration that signals should be defaulted and the main thread should be protected from uninterruptable calls to allow prompt process exits while still performing critical state restoration.

The given main is executed with the given positionals args and keywords kw inside of a Fork.trap call. Fork handles formal exits and main-call substitution.

timeout60%
function

timeout()

SIGALRM based context manager for maximum time interruptions.

concurrently388%
function

concurrently(controller)

Dispatch the given controller in a child process of a control controlled process. The returned object is a reference to the result that will block until the child process has written the serialized response to a pipe.

Used to create very simple fork trees or workers that need to send completion reports back to the parent. This expects the calling process to have been launched with control.

concurrently Parameters

controller: typing.Callable
typing.Callable
The object to call to use the child's controller.
exe: Undocumented.
waitpid: Undocumented.

fs_pwd0
function
`files.Path`

fs_pwd()

Construct a fault.system.files.Path instance referring to PWD or the current working directory if the environment variable is not defined or it is an empty string.

The returned path is not maintained within any cache so repeat calls will create a new instance.

fs_chdir0
function
`files.Path`

fs_chdir(directory)

Update PWD and the current working directory.

The current working directory is set prior to the environment being updated. Exceptions should not require PWD to be reset by the caller.

fs_chdir Returns

The given directory for chaining if it is a fault.system.files.Path instance. Otherwise, the result of fs_pwd is returned.

_scheduler_loop0
function

_scheduler_loop(ks, proxy, limit, final)

Scheduling0
function
`kernel.Scheduler`

Scheduling()

Initialize or return process.scheduler.

Accessing process.scheduler will perform this automatically.

getattr166%
function

__getattr__(name)

process8772%python.modulefault.system

sysimport

os0import

signal0import

functools0import

contextlib0import

typing0import

types0import

builtins0import

kernel0import

runtime0import

thread0import

files0import

__control_lock__0data

__interject_lock__0data

controlled0data

current_process_id0data

parent_process_id0data

main_thread_id0data

index0data

__fork_lock__0data

fork_prepare_callset0data

fork_parent_callset0data

fork_child_callset0data

fork_child_cleanup0data

getattr0data

signal_codes166%data

signals0data

signal_names0data

fatal_signals0data

signal_identifiers0data

interject0function

clear_atexit_callbacks50%function

_after_fork_parent340%function

_after_fork_child1135%function

Exit0class

Exitunspecified_status_codedata

Exitusage_query_codedata

Exitraised0method

Invocation0class

Invocationcontextdata

Invocationparametersdata

Invocation__init__0method

Invocationexit0method

Invocationfs_pwd0property

Invocationargv0property

Invocationargs0data

Invocationenviron0propertydict

Invocationimports271%method

Invocationsystem664%classmethod

Invocationsystem_exit_method0classmethod

ControlException0class

ControlException__kill__data

ControlExceptionraised0method

Critical0class

Critical__kill__data

panic0function

Interruption0class

Interruption__kill__data

Interruption__init__20%method

Interruption__str__70%method

Interruptionraised40%method

Interruptioninterrupt30%classmethod

Interruptionvoid0staticmethod

Interruptionfilter0classmethod

Interruptioncatch0classmethod

Interruptiontrap0classmethod

Fork0class

Fork__controlled_thread_id__data

Fork__init__0method

Fork__str__10%method

Forkpivot40%method

Forksubstitute0classmethod

Forkdispatch657%classmethodint

Forktrap190%classmethod

critical190%function

protect100%function

control1056%function

timeout60%function

concurrently388%function

process8772%`python.module`
fault.system

sys
import

os0
import

signal0
import

functools0
import

contextlib0
import

typing0
import

types0
import

builtins0
import

kernel0
import

runtime0
import

thread0
import

files0
import

__control_lock__0
data

__interject_lock__0
data

controlled0
data

current_process_id0
data

parent_process_id0
data

main_thread_id0
data

index0
data

__fork_lock__0
data

fork_prepare_callset0
data

fork_parent_callset0
data

fork_child_callset0
data

fork_child_cleanup0
data

getattr0
data

signal_codes166%
data

signals0
data

signal_names0
data

fatal_signals0
data

signal_identifiers0
data

interject0
function

clear_atexit_callbacks50%
function

_after_fork_parent340%
function

_after_fork_child1135%
function

Exit0
class

Exit unspecified_status_code
data

Exit usage_query_code
data

Exit raised0
method

Invocation0
class

Invocation context
data

Invocation parameters
data

Invocation init0
method

Invocation exit0
method

Invocation fs_pwd0
property

Invocation argv0
property

Invocation args0
data

Invocation environ0
property
`dict`

Invocation imports271%
method

Invocation system664%
classmethod

Invocation system_exit_method0
classmethod

ControlException0
class

ControlException kill
data

ControlException raised0
method

Critical0
class

Critical kill
data

panic0
function

Interruption0
class

Interruption kill
data

Interruption init20%
method

Interruption str70%
method

Interruption raised40%
method

Interruption interrupt30%
classmethod

Interruption void0
staticmethod

Interruption filter0
classmethod

Interruption catch0
classmethod

Interruption trap0
classmethod

Fork0
class

Fork __controlled_thread_id__
data

Fork init0
method

Fork str10%
method

Fork pivot40%
method

Fork substitute0
classmethod

Fork dispatch657%
classmethod
`int`

Fork trap190%
classmethod

critical190%
function

protect100%
function

control1056%
function

timeout60%
function

concurrently388%
function