package YAMI.Core.Agents

Public [types] [fields] [subprograms]

Types

Agent

   type Agent (<>) is tagged limited private;

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, 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
     (Message_Handler : in Incoming_Message_Handlers.Handler_Access;
      Closed_Connection_Handler :
      in Closed_Connection_Handlers.Handler_Access := null;
      Working_Area : in System.Address := System.Null_Address;
      Area_Size : in System.Storage_Elements.Storage_Count := 0)
     return Agent;
   function New_Agent
     (Message_Handler : in Incoming_Message_Handlers.Handler_Access;
      Closed_Connection_Handler :
      in Closed_Connection_Handlers.Handler_Access := null;
      Working_Area : in System.Address := System.Null_Address;
      Area_Size : in System.Storage_Elements.Storage_Count := 0)
     return Agent_Access;

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

Make_Agent

   function Make_Agent
     (Options : in Parameters.Parameters_Collection;
      Message_Handler : in Incoming_Message_Handlers.Handler_Access;
      Closed_Connection_Handler :
      in Closed_Connection_Handlers.Handler_Access := null;
      Working_Area : in System.Address := System.Null_Address;
      Area_Size : in System.Storage_Elements.Storage_Count := 0)
     return Agent;
   function New_Agent
     (Options : in Parameters.Parameters_Collection;
      Message_Handler : in Incoming_Message_Handlers.Handler_Access;
      Closed_Connection_Handler :
      in Closed_Connection_Handlers.Handler_Access := null;
      Working_Area : in System.Address := System.Null_Address;
      Area_Size : in System.Storage_Elements.Storage_Count := 0)
     return Agent_Access;

Creates new agent object with 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.

Install_Event_Notification_Handler

   procedure Install_Event_Notification_Handler
     (The_Agent : in out Agent;
      Handler : in Event_Notification_Handlers.Handler_Access);

Installs the event notification handler.

Installs the logging monitor. The previously installed callback (if any) is overriden.

This function is not synchronized.

Open

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

Creates new channel for the given target.

Create a new channel for the given target. If the channel already exists for the given target, this procedure does nothing.

The supported target formats are:

Open

   procedure Open (The_Agent : in out Agent;
                   Target : in String;
                   Descriptor : out Channel_Descriptor;
                   Created_New : out Boolean);

Creates new channel for the given target.

Create a new channel for the given target and return its descriptor. If the channel already exists for the given target, this procedure does nothing.

Is_Open

   procedure Is_Open (The_Agent : in out Agent;
                      Target : in String;
                      Result : out Boolean;
                      Descriptor : out Channel_Descriptor);

Checks if the given channel is already open.

If the given channel already exists, Result is set to True and the channel's descriptor is returned. Otherwise Result is set to False.

Close

   procedure Close (The_Agent : in out Agent;
                    Descriptor : in Channel_Descriptor;
                    Priority : in Natural := 0);

Closes the given channel.

Closes the channel identified by the given descriptor.

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.

Close

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

Closes the given channel.

Closes the channel identified by the target name.

Hard_Close

   procedure Hard_Close (The_Agent : in out Agent;
                         Descriptor : in Channel_Descriptor);

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.

Hard_Close

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

Immediately closes the given channel.

Immediately closes the channel identified by the target name.

Post

   procedure Post
     (The_Agent : in out Agent;
      Channel : in Channel_Descriptor;
      Message_Header : in Serializables.Serializable'Class;
      Message_Body : in Serializables.Serializable'Class;
      Priority : in Natural := 0;
      Progress_Handler : in Message_Progress_Handlers.Handler_Access := null);

Posts new message for sending.

Posts a new message to the outgoing queue of the given channel.

The message is composed of two sets of parameters, one for the header information and one for the body. This distinction is supposed to support arbitrary routing conventions defined by user code. Any of these parts can be empty.

The priority of the message is taken into account for proper ordering of the frames in the outgoing queue - frames created for messages with higher priority will be transmitted before frames having lower priority. Messages with equal priority are ordered according to the FIFO regime.

The callback handler can be provided to allow the user code trace the progress of the message. For each frame that was successfully pushed for physical transmission the callback is performed with the number of bytes that were transmitted from the beginning of the message and the total number of bytes for the whole message. When these two arguments are equal then it indicates that the whole message has been transmitted. If both are zero it means that there was an error and the message was abandoned.

Post

   procedure Post
     (The_Agent : in out Agent;
      Target : in String;
      Message_Header : in Serializables.Serializable'Class;
      Message_Body : in Serializables.Serializable'Class;
      Priority : in Natural := 0;
      Progress_Handler : in Message_Progress_Handlers.Handler_Access := null);

Posts new message for sending.

Posts a new message to the outgoing queue of the given channel where the channel is identified by its target.

Add_Listener

   procedure Add_Listener
     (The_Agent : in out Agent;
      Target : in String;
      Resolved_Target : out String;
      Resolved_Target_Last : out Natural;
      Connection_Handler : in New_Connection_Handlers.Handler_Access := null);

Adds new listener.

Adds a new listener for the given target address.

The supported target formats are:

The port for TCP/IP and UDP protocols can be 0 or *, in which case the actual port number is assigned by the system.

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.

Do_Some_Work

   procedure Do_Some_Work
     (The_Agent : in out Agent;
      Timeout : in Duration;
      Timed_Out : out Boolean;
      Allow_Outgoing_Traffic : in Boolean := True;
      Allow_Incoming_Traffic : in Boolean := True);

Performs a portion of I/O or internal management work.

Performs a portion of work with the given timeout. If there is some pending work at the call time it is performed immediately and procedure returns without waiting for further work; otherwise the call blocks waiting for the work with the given timeout.

The pending work can include any of:

Note: All callbacks initiated by the agent are executed in the context of the task that calls this procedure. The task calling this procedure is also the only one that performs actual data transfer.

Note: The timeout value is subject to system limits as defined for the select function.

Note: In the typical usage scenario this procedure should be called in a tight loop.

Interrupt_Work_Waiter

   procedure Interrupt_Work_Waiter (The_Agent : in out Agent);

Artificially interrupts the wait state of Do_Some_Work.