Classes And Functions

Complete, technical information for the significant classes, methods and functions in the library, appears here.

Starting And Stopping The Async Machinery

Management of the ansar, async runtime.

Ensure that the support for async operation is in place when the process needs it. Ensure the support is cleared out during process termination.

ansar.create.root.boot_up(logs)

Start the async runtime. Return the root object, bool tuple.

This is the function that actually creates the threads and objects that are needed to support the SDL model of async operation. It checks to see if the runtime is already up, in a thread-safe way. It returns a 2-tuple; a root object that remains constant for the life of a process and a flag indicating whether the runtime actually needed booting or not.

The flag is used to determine the manner in which a process has been started. Some callers will use the flag to implement cleanup on process termination, i.e. using atexit().

Parameters

logs (a callable object) – an object expecting to receive log objects

Return type

2-tuple

ansar.create.root.start_up(logs)

Start the async runtime. Return the root object.

The start routine called by those who are in a position to perform proper shutdown during process termination. Just calls the lower-level boot_up() and ignores the detail about whether the runtime was already up.

Parameters

logs (a callable object) – an object expecting to receive log objects

Return type

Point-based object

ansar.create.root.tear_down(code=None)

End the async runtime. Return nothing.

This function cleans up everything created by boot_up().

Parameters

code (int) – the desired exit status or none

Return type

None

ansar.create.root.open_channel(logs=<function log_to_nowhere>)

Start the runtime for a non-standard executable. Return a unique async object.

Create a new async object for the purposes of initiating async activity, typically from within a non-async section of code. Registers a cleanup function with the process, to execute on process termination.

Parameters

logs (a callable object) – an object expecting to receive log objects

Return type

Point-based object

ansar.create.root.drop_channel(c)

End the runtime for a non-standard executable. Return nothing.

Tear down the runtime created by open_channel(), i.e. boot_up().

Parameters

c (Point-based object) – a channel returned by open_channel()

Return type

none

class ansar.create.root.OpenChannel(logs=<function log_to_nowhere>)

A context to automate the opening and closing of a channel.

Typically used in a traditional, sync application to access the async features of ansar. May be used anywhere within an application. Each instance creates a unique channel. The parameter provides for control over the fate of logs. This only has an effect on the first use of the class.

Parameters

logs (a callable object) – an object expecting to receive log objects

Implementation Of Standard Applications

ansar.create.object.create_object(object_type, *fixed_value, factory_settings=None, factory_input=None, input_type=None, factory_variables=None, upgrade=None, parameter_passing=<function object_passing>, parameter_table=None, start_vector=<function object_vector>, logs=<function log_to_nowhere>, properties=<class 'ansar.create.home.RoleProperties'>, **key_value)

Creates an async process shim around a “main” async object. Returns nothing.

Parameters

  • object_type (a function or a Point-based class) – the type of an async object to be instantiated

  • factory_settings (instance of a registered class) – persistent values

  • factory_input (instance of a registered class) – per-invocation values

  • factory_variables (instance of a registered class) – host environment values

  • upgrade (function) – function that accepts old versions of settings/input and produces the current version

  • parameter_passing (a function) – method for parsing sys.argv[]

  • parameter_table (dict) – table of sub-commands and their associated functions

  • logs (function or class with __call__ method) – a callable object expecting to receive log objects

Return type

None

ansar.create.object.object_executable()

Global access to the host executable. Returns a str.

ansar.create.object.object_words()

Global access to the words appearing on the command-line. Returns a list of words.

ansar.create.object.object_custom_settings()

Global access to the values decoded from persistent configuration. Returns the values or None.

ansar.create.object.store_settings(settings)

Global mechanism for updating the persistent configuration. Returns indication of success.

ansar.create.object.object_resource_folder()

Part of the disk management context, i.e. resource. Returns the per-executable, read-only resource folder or None.

ansar.create.object.object_tmp_folder()

Part of the disk management context, i.e tmp. Returns the empty-on-start, temporary folder or None.

ansar.create.object.object_model_folder()

Part of the disk management context, i.e. model. Returns the folder of bulk, persistent storage or None.

ansar.create.object.object_resource_path()

Partner to resource_folder(). Returns the folder path or None.

ansar.create.object.object_tmp_path()

Partner to tmp_folder(). Returns the folder path or None.

ansar.create.object.object_model_path()

Partner to model_folder(). Returns the folder path or None.

Implementation Of Asynchronous Objects

Definition of the fundamental async object.

Async objects are created and then send messages to each other. There are also timers to implement, and automated logging. There is also assistance for managing async scenarios.

class ansar.create.point.Point

The essential async object.

Methods of this class are the user entry-point for SDL primitives such as send() and start(). There are also methods associated with logging and child object management.

Point.create(object_type, *args, object_ending=<function completed_object>, **kw)

Create a child instance of object_type. Return the address of the new object.

Parameters

  • object_type (function or Point-based class) – async type to instantiate

  • args (positional arguments tuple) – arguments passed to the new object

  • kw (name arguments dict) – arguments passed to the new object

Return type

an ansar address or the actual object (e.g. Channel)

Point.send(m, to)

Transfer a message to an address.

Message delivery is not guaranteed and non-delivery is not notified. There are multiple reasons delivery can fail, e.g. the destination address no longer exists. Unless the reason is a fault within the sending machinery, failure to deliver is not considered an error. Refer to application logs for details on why a particular message failed to reach its intended destination.

A copy of the message is taken for every actual transfer, i.e. by default remote objects always receive a copy of the message originally presented to send(). Obviously this is behaviour motivated by the multi-threaded runtime context but where it is deemed unnecessary, copying can be disabled on a per-message-type basis. bind_any() for more details.

Parameters

  • m (instance of a registered message) – the message to be sent

  • to (ansar address) – the intended receiver of the message

Point.reply(m)

Send a response to the sender of the current message.

This is a shorthand for self.send(m, self.return_address). Reduces keystrokes and risk of typos.

Parameters

m (instance of a registered message) – the message to be sent

Point.forward(m, to, return_address)

Send a message to an address, as if it came from a 3rd party.

Send a message but override the return address with the address of another arbitrary object. To the receiver the message appears to have come from the arbitrary object.

Useful when building relationships between objects. This allows objects to “drop out” of 3-way conversations, leaving simpler and faster 2-way conversations behind.

Parameters

  • m (instance of a registered message) – the message to send

  • to (ansar address) – the intended receiver of the message

  • return_address (ansar address) – the other object

Point.advise(m)

Send a message to the parent of this object.

Parameters

m (instance of a registered message) – the message to be sent

Point.start(timer, seconds, repeating=False)

Start the specified timer for this object.

An instance of the timer class will be sent to this address after the given number of seconds. Any registered message can be used as a timer. Ansar provides the standard timers T1, T2, T3, and T4 for convenience and to reduce duplication.

Timers are private to each async object and there is no limit to the number of pending timers an object may have. Starting a timer with the same class is not an error, the timeout for that timer is reset to the new number of seconds. It is also not an error to terminate an object with outstanding timers - they fall on the floor.

It is difficult to make guarantees about the order that messages will arrive at an object. In the case of timers, its possible to receive the timeout after the sending of a cancellation. Async objects are best written to cope with every possible receive ordering.

Parameters

  • timer (a registered class) – the type of the object that will be sent back on timeout

  • seconds (float) – time span before expiry

Point.cancel(timer)

Abort the specified timer for this object.

Discard the pending timer. It is not an error to find that there is no such pending timer. The timeout can still be received after a cancellation.

Parameters

timer (a registered class) – the pending timer

Point.complete(value=None)

Cause an immediate termination. The method never returns.

Parameters

value (any) – value to be returned to parent.

Point.assign(address, job=True)

The specified child object is working on the given job.

Parameters

  • address (ansar address) – the async object

  • job (any) – what the child object is doing on behalf of this object

Point.working()

Check if there are child objects still active. Returns the count.

Point.progress(address=None)

Find the job for the specified address. Return the job or None.

Parameters

address (ansar address) – the async object

Return type

any or None

Point.running()

Yield a sequence of job, address tuples.

Point.abort(aborted_value=None)

Initiate the termination protocol for all pending jobs. Return the count of.

Point.debrief(address=None)

Find the job associated with the address. Return the job.

If no address is provided the current return address is used. If a match is found the record is removed, decrementing the number of active jobs.

Parameters

address (ansar address) – the async object

Return type

any or None

Point.log(tag, a)

Generate a PointLog object at the specified level.

This an internal function that should rarely be used directly by an application. Use debug(), trace(), etc instead.

Forms a standard logging object and sends it to the logging service within the ansar runtime. The message to include is passed as either a str or a tuple of strings and objects, i.e. the tuple of positional arguments. Encoding and decoding is performed to ensure a single line log. Non ASCII characters are escaped with a backslash.

Parameters

  • tag (str) – one of the logging single-character tags

  • a – the message to log

Point.debug(*a)

Generate a log at level DEBUG.

Parameters

a (tuple of positional arguments) – the message to log

Point.trace(*a)

Generate a log at level TRACE.

Parameters

a (tuple of positional arguments) – the message to log

Point.sample(**kv)

Generate a log at level TRACE.

A quick way to put runtime values in the logs. Also the basis for generating values for statistical analysis. Refer to ansar logging documentation.

Parameters

kv – the named arguments

Point.console(*a)

Generate a log at level CONSOLE.

Parameters

a (tuple of positional arguments) – the message to log

Point.warning(*a)

Generate a log at level WARNING.

Parameters

a (tuple of positional arguments) – the message to log

Point.test(condition, note)

Generate a log at level WARNING, dependent on the condition.

A PointTest is also sent to an internal collection point, for later recovery, e.g. by test applications. This is sent for both pass and fail.

Parameters

  • condition (bool) – pass or fail

  • note (str) – a simple string of text

Point.fault(*a)

Generate a log at level FAULT.

Parameters

a (tuple of positional arguments) – the message to log

class ansar.create.point.PointLog(stamp=0.0, tag=None, address=None, name=None, state=None, text=None)

Object that records a moment in time and other details.

Parameters

  • stamp (epoch float) – the moment the log was created

  • tag (a single-character string) – an enumeration of the log level

  • address (tuple of int) – address of the async object

  • name (str) – name of the class or function.

  • state (str) – name of the current FSM state or None

  • text (str) – free format text

class ansar.create.point.Threaded(blocking=False, maximum_size=8192)

Base class for async machines that require dedicated threads.

Parameters

  • blocking (bool) – block on queue full

  • maximum_size (int) – number of pending messages

class ansar.create.point.Channel

A sync object.

Used by sync code to access async features. An instance of a channel is created by ansar on behalf of each “function” object, i.e. each instance of a function object gets a thread and a channel. The thread accesses async services through it private channel object. Also used by the OpenChannel context object.

class ansar.create.point.T1

Predeclared timer class.

A class suitable for passing to Point.start(). The library provides the T1, T2, T3 and T4 timer classes for general use.

class ansar.create.point.PointTest(stamp=None, name=None, condition=None, source=None, line=None, text=None)

Results of a Point.test().

Captures the details of a check on runtime values.

Parameters

  • stamp (epoch float) – the moment the test was performed

  • name (str) – name of the class or function

  • condition (bool) – pass or fail

  • source (str) – name of the module containing the test

  • line (int) – line in the module

  • text (str) – free format text

class ansar.create.point.AutoStop(point, completed=None)

Context to automate clearance of pending objects.

Parameters

  • point (async object) – parent of the pending objects

  • completed (dict) – map of values returned by objects

ansar.create.point.bind_point(point, thread=None, lifecycle=True, message_trail=True, execution_trace=True, user_logs=1)

Set the runtime flags for the given async object type.

Parameters

  • point (class) – a class derived from Point.

  • lifecycle (bool) – log all create() and complete() events

  • message_trail (bool) – log all send() events

  • execution_trace (bool) – log all receive events

  • user_logs (enumeration) – the logging level for this object type

ansar.create.point.bind_function(routine, lifecycle=True, message_trail=True, execution_trace=True, user_logs=1)

Set the runtime flags for the given async function.

Parameters

  • routine (function) – an async function.

  • lifecycle (bool) – log all create() and complete() events

  • message_trail (bool) – log all send() events

  • execution_trace (bool) – log all receive events

  • user_logs (enumeration) – the logging level for this object type

ansar.create.point.halt(address)

Mark the object at the specified address as halted.

Parameters

address (ansar address) – an async object

ansar.create.binding.bind_any(object_type, *args, **kw_args)

Forwards all arguments on to a custom bind function according to the type of the first argument.

Refer to ansar.encode for registration of messages;

Parameters

  • object_type (message class, function or Point-based class) – type of async entity

  • args (positional argument tuple) – arguments passed to the object instance

  • kw_args (named arguments dict) – named arguments passed to the object instance

class ansar.create.lifecycle.Start

First message received by every async machine, from creator to child.

class ansar.create.lifecycle.Completed(value=None)

Last message sent, from child to creator.

Parameters

value (any) – return value for an async object

class ansar.create.lifecycle.Stop

Initiate teardown in the receiving object.

class ansar.create.lifecycle.Aborted
class ansar.create.lifecycle.TimedOut(timer=None)
class ansar.create.lifecycle.Nothing

A positive null.

class ansar.create.lifecycle.Ready

Report a positive state.

class ansar.create.lifecycle.Enquiry

Prompt an action from receiver.

class ansar.create.lifecycle.Exhausted(final_straw=None, attempts=None, started=None, ended=None, seconds=None)
class ansar.create.lifecycle.Ack

Report in the positive.

class ansar.create.lifecycle.Nak

Report in the negative.

class ansar.create.pending.Queue(blocking=False, maximum_size=8192)

Base for any object intended to operate as a message queue.

Parameters

  • blocking (bool) – behaviour on queue full

  • maximum_size (int) – number of message to hold

class ansar.create.pending.SelectTimer

Timer for managed input.

class ansar.create.pending.Player

Base for objects intending to operate message buffering with replay.

class ansar.create.pending.Buffering

Base for any object intending to perform sophisticated I/O, i.e. channels and routines.

Buffering.save(m)

Retain the [message, to, return] triplet, using values saved during input.

Parameters

m (message object) – message to be saved

Buffering.input()

Get the next message while transparently buffering.

Return type

message object

Buffering.select(*matching, saving=None, seconds=0)

Expect one of the listed messages, with optional saving and timeout.

Parameters

  • matching (the positional arguments tuple) – message types to be accepted

  • saving (tuple) – message types to be deferred

  • seconds (float) – waiting period

Return type

message object

Buffering.ask(q, r, a, saving=None, seconds=None)

Query for a response while allowing reordering, with optional timer.

Parameters

  • q (registered message) – query to be sent

  • r (tuple) – response types to be detected and returned

  • a (ansar address) – async object to be queried

  • saving (tuple) – response types to be detected and buffered

  • seconds (float) – waiting period

Return type

message object

Buffering.stop(a, r=(<class 'ansar.create.lifecycle.Completed'>, ), saving=None, seconds=None)

Request the termination of an object.

Parameters

  • a (ansar address) – async object to be queried

  • r (tuple) – response types to be detected and returned

  • saving (tuple) – response types to be detected and buffered

  • seconds (float) – waiting period

Return type

message object

class ansar.create.pending.Dispatching

Provides input mechanism for any machine with its own queue.

class ansar.create.machine.Stateless

Base for simple machines that maintain no formal state.

Messages are received by an assigned thread and dispatched to handlers according to the type of the received message.

class ansar.create.machine.StateMachine(initial)

Base for machines that maintain a formal state.

Messages are received by an assigned thread and dispatched to handlers according to the current state and the type of the received message.

Parameters

initial (class) – Start state for all instances of derived class

ansar.create.machine.bind_stateless(machine, dispatch, *args, **kw_args)

Sets the runtime environment for the given stateless machine. Returns nothing.

This function (optionally) auto-constructs the message dispatch table and also saves control values.

The dispatch is a simple list of the expected messages:

dispatch = (Start, Job, Stop)

Using this list and a naming convention the bind function searches the application for the matching functions and installs them in the appropriate dispatch entry. The naming convention is;

<machine name>_<expected message>

The control values are the same as for Points (see bind_point()). This function actually calls the bind_point function to ensure consistent initialization.

Parameters

  • machine (a class) – class derived from machine.Stateless

  • dispatch (a tuple) – the list of expected messages

  • args (a tuple) – the positional arguments to be forwarded

  • kw_args (a dict) – the named arguments to be forwarded

ansar.create.machine.bind_statemachine(machine, dispatch, *args, **kw_args)

Sets the runtime environment for the given FSM. Returns nothing.

This function (optionally) auto-constructs the message dispatch table and also saves control values.

The dispatch is a description of states, expected messages and messages that deserve saving:

dispatch = {
        STATE_1: (Start, ()),
        STATE_2: ((Job, Pause, UnPause, Stop), (Check,)),
        STATE_3: ((Stop, ()),
}

Consider STATE_2; The machine will accept 4 messages and will save an additional message, Check.

Using this list and a naming convention the bind function searches the application for the matching functions and installs them in the appropriate dispatch entry. The naming convention is;

<machine name>_<state>_<expected message>

The control values available are the same as for Points (see bind_point()). This function actually calls the bind_point function to ensure consistent initialization.

Parameters

  • machine (a class) – class derived from machine.StateMachine

  • dispatch (a dict of tuples) – specification of a FSM

  • args (a tuple) – the positional arguments to be forwarded

  • kw_args (a dict) – the named arguments to be forwarded

class ansar.create.test.TestReport(passed=0, failed=0, tested=None)

A sequence of test results.

Each call to Point.test() produces an entry in the tested member. This object is the intended return value for a test process.

Parameters

  • passed (int) – count of true tests

  • failed (int) – count of false tests

  • tested (list) – sequence of PointTests

class ansar.create.test.TestSuite(role=None, report=None, passed=0, failed=0, navigation=None)

A collection of TestReports.

Each TestReport collected by a parent process, e.g. the ansar tool, is gathered into suite of reports.

Parameters

report (dict) – a TestReport per role

class ansar.create.object.ObjectSettings(pure_object=False, call_signature=None, debug_level=None, home_path=None, role_name=None, point_of_origin=None, help=False, dump_settings=False, save_settings=False, dump_input=False, store_settings=False, store_input=False, factory_reset=False, edit_settings=False, settings_file=None, input_file=None, output_file=None, group_pid=None)

Values that capture the details of a “call” between parent and child process.

These are the values used to implement integration between parent and child processes. There are also values that are useful at the command-line, i.e. debug_level, help, dump_settings, dump_input, store_settings, store_input, settings_file, input_file and output_file are all available as command-line setttings (i.e. to dump the current input use –dump-input).

Parameters

  • call_signature ("io", "i", "o" or None) – I/O expectations of the caller

  • debug_level (str) – NONE, DEBUG, TRACE, OBJECT, CONSOLE, WARNING, FAULT

  • home_path (str) – location of a process group

  • role_name (str) – role within a process group

  • point_of_origin (1, 2, or 3) – context of execution - start, run or call (sub-process)

  • help (bool) – enable output of help page

  • dump_settings (JSON representation) – enable output of current settings

  • dump_input (JSON representation) – enable output of the stored input

  • store_settings (bool) – enable saving of the current settings

  • store_input (bool) – enable saving of the current input

  • settings_file (str) – use the settings in the specified file

  • input_file (str) – use the input in the specified file

  • output_file (str) – place any output in the specified file

Useful Asynchronous Objects

class ansar.create.processing.Process(name, input=None, input_type=None, output=True, forwarding=False, settings=None, origin=None, debug=None, home_path=None, role_name=None, subrole=True, group_pid=None, upgrade=<function no_upgrade>, **kw)

An async proxy object that starts and manages a standard sub-process.

Parameters

  • name (str) – name of the executable file

  • input (type expression) – object to be passed

  • input_type (type expression) – explicit type

  • output (bool) – enable decoding of stdout

  • forwarding (bool) – enable forwarding of parent stdin

  • settings (list of str) – additional command line arguments

  • origin (enum) – starting context, internal

  • debug (enum) – level

  • home_path (str) – location of a home, internal

  • role_name (str) – name within a home, internal

  • upgrade (function) – version translation

  • kw (named args dict) – addition args passed to Popen

class ansar.create.processing.Utility(name, *args, args_schema=None, punctuation=None, stdin=None, stdout=None, stderr=None, text=False, encoding=None, errors=None, cwd=None, **kw)

An async proxy object that starts and manages a non-standard sub-process.

The named executable is started and the machine waits for termination. If stdin is a str the contents are written to an input pipe. If stdout is str (i.e. the class) the object will return the text received on the output pipe, in the Completed message.

Parameters are passed from the calling process to the child process by translating the positional parameters according to a few rules;

  • Each parameter (i.e. args[i]) should be a tuple where the first element is the name of the parameter and the second element is the runtime value of that name.

  • A 3-tuple can also be used where the middle element contains the separator to used on the command line, between the name and the value.

  • Values are Python values and these are encoded in a best-guess fashion, e.g. a Python int will be converted to the proper sequence of digits. A Python str will be passed verbatim.

  • Explicit type information can be passed in args_schema. This is a name-type dict where the type value is used to control the encoding process, e.g. a Python float can be described as a ar.ClockTime and the float will be converted to a full ISO format string on the command line.

  • By default the command line is decorated with dashes and equals signs. Passing a Punctuation parameter takes explicit control over those decorations.

Parameters

  • name (str) – name of the executable file

  • args (tuple) – positional args

  • args_schema (dict of ansar type expressions) – explicit type information about args

  • punctuation (Punctuation) – override standard decoration of command line

  • stdin (str or None) – text to pass to child

  • stdout (type) – type of expected output, e.g. str

  • stderr (type) – type of expected output, e.g. str

  • text (bool) – nature of pipe content - text or binary

  • encoding (str) – control encoding of text, passed to Popen()

  • errors (str) – control encoding errors, passed to Popen()

  • cwd (str) – where to locate the sub-process

  • kw (named parameters dict) – additional parameters passed to Popen()

class ansar.create.processing.Punctuation(dash=None, double_dash=None, list_ends=None, list_separator=None, dict_ends=None, dict_separator=None, dict_colon=None, message_ends=None, message_separator=None, message_colon=None, true_false=None, no_value=None, flag_value_separator=None, any_separator=None)

A collection of strings for custom decoration of a command line.

Parameters

  • dash (str) – string to place before a short-form flag

  • double_dash (str) – string to place before a long-form name

  • list_ends (str, len of 2) – left-end and right-end characters bounding a list

  • list_separator (str) – string to place between list elements

  • dict_ends (str, len of 2) – left-end and right-end characters bounding a dict

  • dict_separator (str) – string to place between dict elements

  • dict_colon (str) – str to place between name and value of dict pair

  • message_ends (str, len of 2) – left-end and right-end characters bounding a message

  • message_separator (str) – string to place between message elements

  • message_colon (str) – str to place between name and value of dict pair

  • true_false (list of 2 str) – strings to encode as representations for true and false

  • no_value (str) – string to encode as a None value

  • flag_value_separator (str) – string to place between flag and value

  • any_separator (str) – string to place between elements of an Any representation