yami

 
Classes
       
builtins.Exception(builtins.BaseException)
YAMIError
builtins.object
Agent
IncomingMessage
Long
OutgoingMessage
Parameters
ValuePublisher

 
class Agent(builtins.object)
    Message broker.
 
The message broker that encapsulates physical channel management,
incoming and outgoing message queues, listeners and resource
management.
 
A single agent object can manage many listeners, which are responsible
for accepting remote connections, and many incoming and outgoing
connections.
 
The agent objects can be created and destroyed without constraints
on the stack, on the free store or as static objects.
 
The objects of this class can be safely used by multiple threads.
 
  Methods defined here:
__del__(self)
__enter__(self)
__exit__(self, exc_type, exc_val, exc_tb)
__init__(self, options={}, connection_event_callback=None)
Initialize self.  See help(type(self)) for accurate signature.
add_listener(self, listener)
Adds new listener.
 
Adds a new listener for the given target address.
 
The supported target formats are:
    - "tcp://host:port" for TCP/IP connections, where host
    can be provided in the symbolic or numeric form
    - "tcp://*:port" for TCP/IP connections, for "any" local address
    - "tcp://port" for TCP/IP connections, for "any" local address
    - "udp://host:port" for UDP communication
    - "unix://path" for Unix connections
 
The port for TCP/IP and UDP protocols can be 0 or *,
in which case the actual port number is assigned by the system.
close(self)
Deallocates internal resources associated with this object.
 
This function is called automatically if the object is used
as a context manager.
close_connection(self, target, priority=0)
Closes the given communication channel.
 
Closes the channel identified by name.
 
The priority allows to properly handle the existing outgoing
messages that are waiting in the outgoing queue for transmission.
The existing messages with lower priority are
abandoned, whereas the existing messages with priority equal
or higher to the one provided as parameter are retained in the
outgoing queue and are properly pushed for transmission
before the channel is physically closed.
The channel is closed immediately only if there are no
messages waiting in its outgoing queue.
hard_close_connection(self, target)
Immediately closes the given communication channel.
 
Closes the channel identified by name.
 
The channel is closed immediately and those messages that are
waiting in its outgoing queue are abandoned. Integrity of the
message that was already partly transmitted is not guaranteed.
open_connection(self, target)
Opens the new connection.
 
Opens the new channel or does nothing if the channel already exists.
 
This function is not necessary with automatic connection
recovery option in send and send_one_way.
register_object(self, object_name, callback)
Registers the new logical destination object.
 
Registers the new "object" that can be a logical destination
for incoming messages.
register_value_publisher(self, object_name, publisher)
Registers the value publisher as a new logical object.
remove_listener(self, listener)
Removes existing listener.
 
Removes the listener denoted by its actual target name.
Note that the actual target name might be different from the name
provided when the listener was created, due to target resolution.
The name which should be used for listener removal is the name
that is returned by the add_listener function.
send(self, target, object_name, message_name, content={}, priority=0, auto_connect=True)
Sends the new outgoing message.
 
Sends the new outgoing message to the given destination.
 
Note:
This function implicitly opens a new communication channel
if it is not already open. This channel is kept open until
it is explicitly closed
(see the close_connection function)
or until the agent is destroyed or the communication error
is detected.
send_one_way(self, target, object_name, message_name, content={}, priority=0, auto_connect=True)
Sends the new outgoing message.
 
Sends the new outgoing message to the given destination, without
the possibility to track its progress.
 
See the description and notes for the send function.
unregister_object(self, object_name)
Unregisters the logical destination object.
 
It is permitted to request unregistration for an object
that does not exist - such operation has no effect.
 
Note:
Due to performance and design tradeoffs it is not guaranteed
that no more messages will be ever dispatched to the given object
when this function returns.
In fact, some of the messages that have been received by agent and not
yet dispatched might be still dispatched shortly after
this function returns.
Only those messages that are received by agent after
this function returns are guaranteed not to be dispatched to the
unregistered object.
This might be particularly important with regard
to the lifetime of the callable entity that was provided when
the given object has been registered.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
CONNECTION_CLOSED = 3
NEW_INCOMING_CONNECTION = 1
NEW_OUTGOING_CONNECTION = 2
OptionNames = <class 'yami.Agent.OptionNames'>

 
class IncomingMessage(builtins.object)
    Incoming message.
 
The handler allowing to inspect the details of the incoming message
and sent back replies or rejection notifications.
 
The user code interacts with objects of this type mainly in the
functors that are provided during object registration and that are later
called back when the incoming message arrives. The handler objects
can be stored aside for further processing even after the callback
returns, but should not be kept alive longer than the agent itself.
 
Note:
The objects of this class are not supposed to be used
from multiple threads.
 
  Methods defined here:
__del__(self)
__init__(self, msg)
Initialize self.  See help(type(self)) for accurate signature.
close(self)
Deallocates internal resources associated with this object.
 
This function is called automatically if the object is used
as a context manager.
get_message_name(self)
Returns the message name.
get_object_name(self)
Returns the destination object name.
get_parameters(self)
Provides access to the message content.
get_source(self)
Returns the source of this incoming message.
reject(self, reason='', priority=0)
Sends back the rejection (exception) notification.
 
Sends back the rejection to the message identified by this object.
The rejection (or reply) can be sent only once.
reply(self, content={}, priority=0)
Sends back the reply.
 
Sends back the reply to the message identified by this object.
The reply (or rejection) can be sent only once.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Long(builtins.object)
    Typed wrapper for long integers.
 
It is possible to directly access the 'value' attribute of this object
it is equal to the integer used to initialize this object.
 
  Methods defined here:
__hash__(self)
Return hash(self).
__init__(self, content)
Initialize self.  See help(type(self)) for accurate signature.
__str__(self)
Return str(self).

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class OutgoingMessage(builtins.object)
    Outgoing message.
 
The handler allowing to track the progress of outgoing message,
inspect its state and to obtain the reply content.
 
Note:
The objects of this class can be safely used from multiple threads.
 
  Methods defined here:
__del__(self)
__enter__(self)
__exit__(self, exc_type, exc_val, exc_tb)
__init__(self, msg)
Initialize self.  See help(type(self)) for accurate signature.
close(self)
Deallocates internal resources associated with this object.
 
This function is called automatically if the object is used
as a context manager.
get_exception_msg(self)
Returns the human-readable reason for message rejection.
get_reply(self)
Provides access to the reply content.
get_state(self)
Returns the state of this message.
 
This function allows to inspect the progress of the message
transmission and returns a 3-tuple: state, sent and total_byte_count.
During transmission the sent value
is always smaller than total_byte_count.
When these two values become equal, it means that the transmission
was either succesful or abandoned.
wait_for_completion(self, timeout=0)
Waits for the full message roundtrip.
 
Waits for the full message roundtrip - that is, for some confirmation
that the message has been received and reacted upon by the
target agent.
If the timeout value is greater than 0, it means relative timeout
in milliseconds; the function returns True if the message was
completed before the timeout expired and False otherwise.
If the timeout value is non-positive, there is no timeout and the
function can wait indefinitely.
After this function returns True the state of the message is either
ABANDONED, REPLIED or REJECTED.
 
Note:
This function should not be called if the intended semantics of the
message is "one-way" - in this case this function would block
indefinitely.
wait_for_transmission(self, timeout=0)
Waits for the transmission to finish.
 
Waits for the transmission to finish - that is, to either send all
the message data or to abandon it.
If the timeout value is greater than 0, it means relative timeout
in milliseconds; the function returns True if the transmission was
finished before the timeout expired and False otherwise.
If the timeout value is non-positive, there is no timeout and the
function can wait indefinitely.
After this function returns True the state of the message is either
TRANSMITTED, ABANDONED, REPLIED or REJECTED.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
ABANDONED = 3
POSTED = 1
REJECTED = 5
REPLIED = 4
TRANSMITTED = 2

 
class Parameters(builtins.object)
    Collection of message parameters.
 
A collection of message parameters is a list of typed {name, value} pairs.
Each entry in this collection has a unique name and can have
one of the following types:
    - bool or bool array
    - int or int array
    - long or long array
    - float or float array
    - string or string array
    - binary buffers or their arrays
    - nested Parameters entry, which provides its own scope for naming.
    - nested Parameters arrays
 
The names of entries are searched for using
case-sensitive comparisons.
 
Note:
The instances of this class should not be used from multiple threads
without synchronization;
it is safe to use separate instances in separate threads.
 
Note:
The entries are ordered - the order in which they are created
influences the final serialized form of the message payload.
Newly created entries are appended to the end of the collection unless
there is an existing empty slot that can be reused - the appropriate
slot is searched for from the beginning to the end of the collection
and if no free slot is found the collection is extended at the end.
The above guarantee concerns the user code that relies on
predictable serialization.
 
  Methods defined here:
__delitem__(self, name)
Removes the given entry from the collection.
 
Note: The removed entry leaves a hole (empty slot) in
the collection that can be reused by newly added entries.
__getitem__(self, name)
Returns the value of the named slot.
__in__(self, name)
Checks if the entry with the given name (key) exists.
__init__(self)
Default constructor, creates an empty collection of parameters.
__iter__(self)
Gets the iterator over the list of keys.
 
The iterator visits only those entries which are used
(in other words, it skips unused slots).
__len__(self)
Gets the current size of the collection.
__setitem__(self, name, value)
Sets the given value in the named slot.
 
If the given slot is already used, its value is replaced.
__str__(self)
Returns a string representation of the content.
 
This function is supposed to be used by unit tests and for
simple debugging.
deserialize(self, buf)
Deserializes from the given buffer.
 
Note: The current content of this object is not cleared
before attempting deserialization and each retrieved data element
is merged into the current content as if done by inserting entries
individually.
In most cases deserialization will be performed to the empty
Parameters object (to reconstruct it to the form that was used
for serialization), but deserialization onto non-empty object
might be occasionally useful as a way of merging two collections.
items(self)
Gets the iterator over the list of items.
 
The iterator visits only those entries which are used
(in other words, it skips unused slots).
keys(self)
Gets the iterator over the list of keys.
 
The iterator visits only those entries which are used
(in other words, it skips unused slots).
serialize(self)
Serializes the content of the whole collection.
 
Returns the binary string with the serialized content.
values(self)
Gets the iterator over the list of values.
 
The iterator visits only those entries which are used
(in other words, it skips unused slots).

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class ValuePublisher(builtins.object)
    Simple subscription publisher.
 
The subscription publisher that notifies remote listeners
with published value updates.
 
Remote listeners can subscribe and unsubscribe at any time.
 
  Methods defined here:
__call__(self, message)
Call self as a function.
__init__(self, user_command=None, max_queue_length=1, overflow_command=<yami.ValuePublisher.__DefaultOverflowCommand object at 0x000001CA24059908>)
Constructor.
 
Creates the subscription publisher
that is not registered at any agent and that has a handler
for arbitrary remote commands.
 
Note:
The "subscribe" and "unsubscribe" messages are also forwarded
to the user-provided callback, but these two messages are already
processed by the publisher's implementation.
get_number_of_subscribers(self)
Returns the number of active subscribers.
get_subscribers(self)
Returns the information about all active subscribers.
 
The first component of each vector entry is a destination target
and the second component is a destination object for
the given subscriber.
publish(self, value, priority=0)
Publishes the new value.
 
Sends the update message to all active listeners with the given value.
In case of any errors or communication problems, the problematic
listener is automatically unsubscribed.
register_at(self, agent, object_name)
Registers the publisher at the given agent.
subscribe(self, destination_target, destination_object)
Subscribes the new listener.
 
This function is usually called internally as a result of
processing the remote "subscribe" message, but can be also
used locally if the listener's location is obtained via
other means.
unregister(self)
Unregisters the publisher from its associated agent.
unsubscribe(self, destination_target)
Unsubscribes the given listener.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
ABANDON_MESSAGE = 2
ABANDON_SUBSCRIPTION = 3
WAIT_FOR_PREVIOUS_MESSAGE = 1

 
class YAMIError(builtins.Exception)
    Exception type for YAMI-related run-time and logical errors.
 
 
Method resolution order:
YAMIError
builtins.Exception
builtins.BaseException
builtins.object

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__init__(self, /, *args, **kwargs)
Initialize self.  See help(type(self)) for accurate signature.
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
helper for pickle
__repr__(self, /)
Return repr(self).
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
__str__(self, /)
Return str(self).
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
Functions
       
serialize(dictionary)
Serializes the content of the given dictionary.
 
Returns the binary string with the serialized content.