package YAMI.Agents

Types

Agent

   type Agent (<>) is tagged limited private;

Message broker.

The message broker that encapsulates physical channel management, incoming and outgoing message queues, listeners, resource management and working tasks.

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, dynamically or as library-level objects.

Agent_Access

   type Agent_Access is access all Agent;

Access type designating the agent.

Variables, Constants and Fields

Max_Target_Length

   Max_Target_Length : constant := 300;

Maximum length of the target name.

Subprograms

Make_Agent

   function Make_Agent return Agent;
   function New_Agent return Agent_Access;

Creates new agent object with default option values and starts its internal tasks. Alternative New_Agent function allocates the agent object dynamically.

Make_Agent

   function Make_Agent (Options : in Parameters.Parameters_Collection)
                       return Agent;
   function New_Agent (Options : in Parameters.Parameters_Collection)
                      return Agent_Access;

Creates new agent object with the given option values. Alternative New_Agent function allocates the agent object dynamically.

Make_Agent

   function Make_Agent
     (Event_Handler : in Event_Notification_Handlers.Handler_Access;
      Options : in Parameters.Parameters_Collection)
     return Agent;
   function New_Agent
     (Event_Handler : in Event_Notification_Handlers.Handler_Access;
      Options : in Parameters.Parameters_Collection)
     return Agent_Access;

Creates new agent object with event notification handler and the given option values. Alternative New_Agent function allocates the agent object dynamically.

Free

   procedure Free (The_Agent : in out Agent_Access);

Frees the dynamically allocated agent object.

Add_Listener

   procedure Add_Listener
     (The_Agent : in out Agent;
      Target : in String;
      Resolved_Target : out String;
      Resolved_Target_Last : out Natural);

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, with rules as for TCP/IP
• "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.

Add_Listener

   procedure Add_Listener (The_Agent : in out Agent; Target : in String);

Adds new listener.

Remove_Listener

   procedure Remove_Listener (The_Agent : in out Agent; Target : in String);

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.

Register_Object

   procedure Register_Object
     (The_Agent : in out Agent;
      Object_Name : in String;
      Handler : in Incoming_Messages.Message_Handler_Access);

Registers the new logical destination object.

Unregister_Object

   procedure Unregister_Object (The_Agent : in out Agent;
                                Object_Name : in String);

Unregisters the logical destination object.

Open_Connection

   procedure Open_Connection (The_Agent : in out Agent;
                              Target : in String);

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.

Send

   procedure Send
     (The_Agent : in out Agent;
      Target : in String;
      Object_Name : in String;
      Message_Name : in String;
      Content : in Serializables.Serializable'Class;
      Message_Handler : in Outgoing_Messages.Outgoing_Message_Access;
      Priority : in Natural := 0;
      Auto_Connect : in Boolean := True);
   procedure Send
     (The_Agent : in out Agent;
      Target : in String;
      Object_Name : in String;
      Message_Name : in String;
      Message_Handler : in Outgoing_Messages.Outgoing_Message_Access;
      Priority : in Natural := 0;
      Auto_Connect : in Boolean := True);

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

   procedure Send_One_Way (The_Agent : in out Agent;
                           Target : in String;
                           Object_Name : in String;
                           Message_Name : in String;
                           Content : in Serializables.Serializable'Class;
                           Priority : in Natural := 0;
                           Auto_Connect : in Boolean := True);
   procedure Send_One_Way (The_Agent : in out Agent;
                           Target : in String;
                           Object_Name : in String;
                           Message_Name : in String;
                           Priority : in Natural := 0;
                           Auto_Connect : in Boolean := 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 procedure.

Close_Connection

   procedure Close_Connection (The_Agent : in out Agent;
                               Target : in String;
                               Priority : in Natural := 0);

Closes the given communication channel.

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

   procedure Hard_Close_Connection (The_Agent : in out Agent;
                                    Target : in String);

Immediately closes the given channel.

Closes the channel identified by the given descriptor.

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.

Register_Connection_Event_Monitor

   procedure Register_Connection_Event_Monitor
     (The_Agent : in out Agent;
      User_Event_Handler : Connection_Event_Handlers.Handler_Access);

Registers the monitor for connection-related events.

Note: The monitor callback is intentionally not synchronized. Use this procedure after constructing the agent, but before opening any connections.

Get_Outgoing_Flow_State

   procedure Get_Outgoing_Flow_State
     (The_Agent : in out Agent;
      Current_Level : out Parameters.Count_Type;
      High_Water_Mark : out Parameters.Count_Type;
      Low_Water_Mark : out Parameters.Count_Type);

Obtains the state of overall outgoing flow.

Note: The outgoing flow is a combination of all outgoing traffic, and is not tied to any particular communication channel.