% PARTOF texte:da/tex/a_home.tex
\begin{xple}
\begin{tabbing}
\hspace*{0.7cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=
\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}
\=\hspace{0.5cm}\=\kill
interface ITC                                                                      \\
import :ITCMessage                                                                 \\
export                                                                             \\
\>error :Exception reason :String end                                              \\
\>(* Raised if something goes wrong. 'reason' explains the problem.*)              \\
\>itcShutdown :Exception end                                                       \\
\>(* See rcv() for explanation.*)                                                  \\
\>itcMessageRejected :Exception end                                                \\
\>(* See rcv() for explanation.*)                                                  \\
\>Let Address = ITCMessage.Address                                                 \\
\>Let MsgBody = ITCMessage.T                                                       \\
\>Message $<$:Ok                                                                     \\
\>(*An ITC message *)                                                              \\
\>Port $<$:Ok                                                                        \\
\>(* A communication port to receive messages on it. This handle                   \\
\>\> has no direct binding to the itc system, nor to its owners                    \\
\>\> thread. It is therefore 'migration-safe' and may be passed                    \\
\>\> to other threads whithout any problems. *)                                    \\
\>nilPort() :Port                                                                  \\
\>(* The always wrong port *)                                                      \\
\>(* ====== communication ports: *)                                                \\
\>newPort() :Port                                                                  \\
\>(* Create a new anonymous communication port. *)                                 \\
\>freePort(:Port) :Ok                                                              \\
\>(* Free a port. This will also free its name if it is a named                    \\
\>\> port. *)                                                                      \\
\>equalPorts(:Port :Port) :Bool                                                    \\
\>(* True iff ports have the same id. *)                                           \\
\>unmountPort(:Port) :Ok                                                           \\
\>(* Unmount a port from an itc system. This is needed if threads attempt to       \\
\>\> migrate into the scope of another itc and refer to this port directly         \\
\>\> and not by an address (e.g. share a port value).                           \\
\>\> After an unmount no send or rcv on this port is possible until it is          \\
\>\> re-mounted. If a port is named, the port name stays allocated at              \\
\>\> the current itc if the port has been created here by newPort(). *)            \\
\>mountPort(:Port) :Ok                                                             \\
\>(* Mount a port at an itc system. This is necessary after migration into         \\
\>\> the scope of another itc system to make the port a valid one. If the          \\
\>\> given port is not known by the current itc,mountPort() will create it.      \\
\>\> Then, a subsequent unmountPort() call will free! the port. This does not      \\
\>\> happen if the port has been created by newPort(), of course. *)               \\
\>portId(:Port) :String                                                            \\
\>(* get the world wide unique port id *)                                          \\
\>getPort(id :String) :Port                                                        \\
\>(* get the port associated with $<$id$>$ *)                                          \\
\>namePort(c :Port name :String) :Ok                                               \\
\>(* Name a port to select it via an address. The name has to be                   \\
\>\> unique w.r.t the local itc. *)                                                \\
\>existsPort(address :Address) :Bool                                               \\
\>(* Check if port exists. Note: Threre is no guarantee that the                   \\
\>\> checked port will conteinue to exist after this call. *)                      \\
\>waitForPort(address :Address \ timeoutSecs :Int) :Bool                            \\
\>(* Wait until the named port exists. If no such port exists after                \\
\>\> timeoutSecs seconds the result is false. Otherwise it is true *)              \\
\>(* ====== message passing: *)                                                    \\
\>Let MsgId = Int                                                                  \\
\>(* Automatic generated per-port unique message id in case of                     \\
\>\> a message is sent off for which a reply is expected.                          \\
\>\> The replied message gets the MsgId which has been assigned                   \\
\>\> to the original message by the corresponding send() call. *)                  \\
\>send(msg :MsgBody \ to :Address \ origin :Port) :MsgId                             \\
\>(* Asynchronous send a message to the port addressed by 'to'.                    \\
\>\> If 'origin' is the nilPort, no reply for this msg is expected, otherwise      \\
\>\> any reply to this message will be delivered to the given port. *)          \\
\>rcv(c :Port) :Message                                                            \\
\>(* Receive a message on port 'c'. This call blocks until a message               \\
\>\> arrives.                                                                    \\
\>\> Will raise itcShutdown iff a itc.stop(true) is issued while waiting for       \\
\>\> a message. Will raise itcMessageRejected iff                                  \\
\>\> a message delivery failed for which rcv awaits the reply                      \\
\>\> or someone sends a message with state = rejectedState. *)                     \\
\>sendRcv(:MsgBody \ to :Address) :Message                                          \\
\>(* Synchronous send/recv pair. May raise the same exceptions like rcv(). *)      \\
\>reply(:Message \ :MsgBody) :Bool                                                  \\
\>(* Set a new message body and send the message to its origin.                    \\
\>\> Will return false if the sender                                               \\
\>\> of the message expects no reply for this message or                           \\
\>\> this message has been already replied. *)                                     \\
\>forward(message :Message \ destinationPort :Port) :Ok                             \\
\>(* Forward a message to the destinationPort. This only changes                   \\
\>\>\>the reveicerAddress and, in case of message is a reply, the                  \\
\>\>\>replyPortId of the message. The forwarded message is not mediated            \\
\>\>\>again. It is save to forward one message to mutliple destinations.           \\
\>*)                                                                               \\
\>(* ====== message access: *)                                                     \\
\>State $<$:Ok                                                                       \\
\>okState,                  (* delivery ok and appl. processing ok *)              \\
\>failedState,              (* delivery ok but appl. processing failed *)          \\
\>rejectedState :State      (* delivery failed. rcv() will raise exception. *)     \\
\>setState(:Message \ :State) :Ok                                                   \\
\>(* Set the current state of a message. *)                                        \\
\>getState(:Message) :State                                                        \\
\>(* Get the current state of a message. *)                                        \\
\>getBody(:Message) :MsgBody                                                       \\
\>(* Extract body part from a message *)                                           \\
\>getMessageId(:Message) :MsgId                                                    \\
\>(* Get the message id from a message. This is usefull if a reply port is         \\
\>\> used for more than one message. Each of them carry an unique message          \\
\>\> id (w.r.t the receiving port). *)                                             \\
\>expectsReply(:Message) :Bool                                                     \\
\>(* Return true iff a message expects to be replied. *)                           \\
\>isReply(:Message) :Bool                                                          \\
\>(* Return true iff the message given is a replied message. *)                    \\
\>getOrigin(:Message) :Address                                                     \\
\>(* Return the address of the origin of a message. It is possible                 \\
\>\> that the returned address does not carry a port name with it                  \\
\>\> (e.g. the name is equal to nilPort().name).                                   \\
\>\> The domain name is valid in any case. *)                                      \\
\>(* ====== mediator use only: *)                                                  \\
\>deliver(message :Message \ incomingPort :Port) :Ok                                \\
\>(* Forward a message to its destination. This is only valid if                   \\
\>\> incomingPort is the mediator port. Otherwise raises error. *)                \\
\>setBody(message :Message \ body :MsgBody \ incomingPort :Port) :Ok                 \\
\>(* Change the body of a message. This is only valid if                           \\
\>\>incomingPort is the mediator port. Otherwise raises error. *)                \\
\>(* ====== admin: *)                                                              \\
\>init() :Ok                                                                       \\
\>(* (Re-)initalize itc state. Only valid iff itc is not running. *)               \\
\>start() :Ok                                                                      \\
\>(* Start itc service loop. *)                                                    \\
\>stop(force :Bool) :Ok                                                            \\
\>(* Stop itc service loop. If force is false then raise error                     \\
\>\> iff stop is not possible safely. Otherwise all waiting itc                    \\
\>\> clients are signaled about itc shutdown and itc is stopped. *)                \\
\>setSocketPort(no :Int) :Ok                                                       \\
\>(* Set socket port number to use. Default 1204. Always valid but                 \\
\>\> has no effect until an init() or start() happens. *)                          \\
\>initMediator(name :String) :Ok                                                   \\
\>(* Set name of local mediator port to use by itc. Default 'THE-MEDIATOR'.        \\
\>\> Always valid and forces itc to relink to the mediator port on the next        \\
\>\> processed message. If no port with 'name' exists, itc switches                \\
\>\> mediator routing off. *)                                                      \\
end;                                                                               \\
\end{tabbing}
\end{xple}



