Copyright © 2001-2008 Maciej Sobczak
The YAMI Tcl Module is a set of commands provided for the Tcl interpreter and supporting the YAMI communication concepts. The module is in fact a wrapper for the YAMI Core Library.
The YAMI Tcl Module consists of two files:
yamitcl.so - this is a shared library that should be loaded into the Tcl interpreter; the module defines and implements the YAMI commands,
pkgIndex.tcl - this file allows to use YAMI Tcl Module with the package command.
The module implements two interfaces: the procedure-based and object-based.
It is perfectly possible to use the bare-bone procedure-based interface, but the object-based interface is designed to make the use of YAMI as easy as possible. Therefore, only object-based interface is documented. For reference considering the other interface, see the source code.
Almost every command in the module can result in an error, which is set as a native Tcl exception.
All the commands are defined in the YAMI namespace.
The concept of Parameter Set is implemented with the use of Tcl lists. There is no separate object that needs to be created before the message is sent. Also, the native Tcl lists are used after receiving the message or the response.
The list of parameters can have two forms: simple and typed.
In the simple form, there is no information about the type of the parameter and all values in the list are supposed to be strings. For example:
{hello 123 3.14159}
The list above contains three string values: hello, 123 and 3.14159.
The typed form carries a type information for each value in the list. For example:
{{hello s} {123 i} {3.14159 d}}
The list above contains three values: string value hello, integer value 123 and double (floating point) value 3.14159. The typed form allows to send (and receive) the Parameter Set in a way so that it will be correctly recognized by the remote site.
The possible type indicators are:
s for string
w for wide string
i for integer
d for double (floating point)
c for byte
b for binary block
Agent is responsible for routing, sending and receiving messages over the network. Conceptually, it is similar to the ORB in CORBA systems.
The Agent object is created in (almost) every program that uses the YAMI library, no matter if the given component acts as a client or as a server in the distributed system.
The multi-threading abilities (and other things that can vary between different Agents) of the Agent object greatly depend on the parameters that are provided during its creation - these parameters are called Policies.
From the programmer's perspective, the Policies object is a structure containing the following fields:
eOverflow notification sent to the remote site (to the Agent that sent the message). Default: 10.
SO_REUSEADDR option (when the flag has non-zero value). This policy can be useful for Agents that are frequently created an destroyed on the same port. Default: 1.
Normally, the Agent can be created without any Policies - in this case it is created with the default values (the default values depend on the respective defaults in the Core Library - they can be changed by appropriate changes in the core headers and recompiling the Tcl module).
% set p [YAMI::Policies] _c8200708_p_Policies %The code above creates new Policies object and assigns a name to it, which is stored in the
p variable. The exact name assigned by the library is not important.
% $p cget -sendtries 5 % $p configure -sendtries 10 % $p cget -sendtries 10 % $p -deleteThe code above reads the
sendtries value (5 by default), later sets this value to 10, reads it again and deletes the object.
Note, that after the object was destroyed, the command associated with the object no longer exists. This approach is valid throughout the whole library.
The functionality of the message sent to the remote object is encapsulated by the Message class.
The only way to create the instances of this class is to call
send method of the Agent class.
The following methods are available in the Message class:
timeout seconds, the local Agent will set the eTimedOut status on the message, which allows the program to wake up, if it was waiting for the response after calling the wait method.
If the wait method was not called, the setTimeOut still works - it sets the eTimeOut on the message object if there is no packet coming from the remote object or the remote Agent in the meantime.
eReplied, eRejected, eUnknownObj, eOverflow, eNetError, eTimedOut or eRejectByAgent. When this happens for any reason, the calling thread wakes up and should check for the message's status. Clients calling this function should consider also setTimeOut, because without it, the wait can block forever (which can happen when the remote object crashes in the middle of processing).
typed (if not 0) indicates that the parameter set should be returned with the type information. If the status of the message is not eReplied, the exception will be set.
The functionality of the message received from the remote site is encapsulated by the IncomingMsg class.
The instances of this class are created by the Agent and for the client code provide access to the message parameters and to some essential operations like replying to the message.
The only way to create the object of this class is to call getIncoming method of the Agent object.
The following methods are available in the Message class:
getIncoming method of the Agent object).
typed parameter (if used and if not 0) causes the parameter set to be returned in the form with type information.
objectname to the domain registered as domainname. The forwarded message has the same from address, so any action performed on the remote side (like rejecting or replying) is visible to the originating object (the one, that has sent the message in the first place). There is no limit on the length of this forwarding chain. The application is allowed to completely change the name of the message as well as its parameter list. This strategy allows to perform some preprocessing before actually forwarding the message. The ``Addr'' versions allow to forward the message to the destination with explicitly given address, bypassing the Agent's internal address book.
The functionality of the YAMI message broker is encapsulated by the Agent class.
The following methods are available in the Agent class:
0 as the port number or calling the first form of this constructor has the effect of starting the Agent object with the listening socket on the port assigned by the operating system.
name is an arbitrary name (visible only to the local Agent), the address is the network address (either in the xxx.xxx.xxx.xxx form or as a human readable comp.company.com) of the remote domain. The port and level of the remote domain should comply to the actual values. If the domain with a given name is already registered, the exception will be thrown.
options parameter is a string value: either "eNone" (for simplex connections, this is the default when the first form is used) or "eFixedDuplex" (for duplex connections).
Note that this parameter is ignored when the message is forwarded to the given domain - forwards are always performed in the simplex mode.
name is arbitrary name and will be used by the remote objects to send messages to this object. If the special "YAMI_ANY_OBJECT" name is used, it denotes the default object that retrieves all messages sent to otherwise unknown objects.
domainname should be a name of the already registered domain or a special name, "YAMI_THIS_DOMAIN", denoting the local domain (then, the shortcut routing will be performed - this is only a hint to the Agent, because the Agent can figure it out by itself, if the domain is registered with the same address and port as the local Agent). The objectname should be a name of the object registered at the remote Agent (or the remote Agent should have default object set up). The messagename is a name of the new message and will be visible to the remote object. The parameters should be a (possibly empty) list of parameters that will be sent together with the message. Depending on the levels of the local and the remote Agents, there are restrictions on the types of parameters that can be put in this list. This method returns a new object of Message class (and it is the only way to create the objects of that class), which can be used for later reference, for example to retrieve the status of the message and its return parameters, if any. The ``Addr'' versions allow to send the message to the destination with explicitly given address, bypassing the Agent's internal address book.
options parameter is a string value: either "eNone" (for simplex connections, this is the default when the first form is used) or "eFixedDuplex" (for duplex connections).
send method, but the Message object is not created. It is not possible to retrieve any information about the message later. Note: it does not make any sense for the remote site to reply or to reject the message sent with this command. The ``Addr'' versions allow to send the message to the destination with explicitly given address, bypassing the Agent's internal address book.
name should be a name of already registered object. If there is no message waiting for a given object, the 0 is returned. If the second form is used, the wait parameter (if non-zero) tells the Agent to freeze the calling thread until some message arrives.
yamilimits.h header file.