YAMI4 Python Library 2.0.0
Messaging Solution for Distributed Systems
Loading...
Searching...
No Matches
Classes | Public Member Functions | Static Public Attributes | List of all members
yami.Agent Class Reference
Inheritance diagram for yami.Agent:

Classes

class  __DispatcherThread
 
class  OptionNames
 

Public Member Functions

def __init__ (self, options={}, connection_event_callback=None)
 
def __enter__ (self)
 
def __exit__ (self, exc_type, exc_val, exc_tb)
 
def __del__ (self)
 
def close (self)
 
def add_listener (self, listener)
 
def remove_listener (self, listener)
 
def register_object (self, object_name, callback)
 
def register_value_publisher (self, object_name, publisher)
 
def unregister_object (self, object_name)
 
def open_connection (self, target)
 
def get_next_message_id (self)
 
def send (self, target, object_name, message_name, content={}, priority=0, auto_connect=True)
 
def send_with_header (self, target, header, content, message_id, priority=0, auto_connect=True)
 
def send_one_way (self, target, object_name, message_name, content={}, priority=0, auto_connect=True)
 
def send_one_way_with_header (self, target, header, content, message_id, priority=0, auto_connect=True)
 
def close_connection (self, target, priority=0)
 
def hard_close_connection (self, target)
 

Static Public Attributes

int NEW_INCOMING_CONNECTION = 1
 
int NEW_OUTGOING_CONNECTION = 2
 
int CONNECTION_CLOSED = 3
 

Detailed Description

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.

Member Function Documentation

◆ add_listener()

def yami.Agent.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()

def yami.Agent.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()

def yami.Agent.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.

◆ get_next_message_id()

def yami.Agent.get_next_message_id (   self)
Obtains a new unique message identifier.

Obtains a new unique message identifier, appropriate for
filling custom header for the newly created message.

◆ hard_close_connection()

def yami.Agent.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()

def yami.Agent.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()

def yami.Agent.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()

def yami.Agent.register_value_publisher (   self,
  object_name,
  publisher 
)
Registers the value publisher as a new logical object.

◆ remove_listener()

def yami.Agent.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()

def yami.Agent.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()

def yami.Agent.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.

◆ send_one_way_with_header()

def yami.Agent.send_one_way_with_header (   self,
  target,
  header,
  content,
  message_id,
  priority = 0,
  auto_connect = True 
)
Sends the new outgoing message, with custom header.

Sends the new outgoing message to the given destination, without
the possibility to track its progress. The message has header data
that is fully controlled by the user.

See the description and notes for the send function.

◆ send_with_header()

def yami.Agent.send_with_header (   self,
  target,
  header,
  content,
  message_id,
  priority = 0,
  auto_connect = True 
)
Sends the new outgoing message, with custom header.

Sends the new outgoing message to the given destination,
with header data that is fully controlled by the user.

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.

◆ unregister_object()

def yami.Agent.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.

The documentation for this class was generated from the following file: