<!--
  - Authors:
  -   Denys Duchier     <duchier@ps.uni-sb.de>
  -   Leif Kornstaedt <kornstae@ps.uni-sb.de>
  -   Christian Schulte <schulte@ps.uni-sb.de>
  -
  - Copyright:
  -   Denys Duchier, 1998
  -   Leif Kornstaedt, 1998
  -   Christian Schulte, 1998
  -
  - Last change:
  -   $Date: 1999/01/21 09:53:02 $ by $Author: schulte $
  -   $Revision: 1.4 $
  -
  - This file is part of Mozart, an implementation
  - of Oz 3
  -    http://www.mozart-oz.org
  -
  - See the file "LICENSE" or
  -    http://www.mozart-oz.org/LICENSE.html
  - for information on usage and redistribution
  - of this file, and for a DISCLAIMER OF ALL
  - WARRANTIES.
  -
  -->

  <Chapter id="Chapter.Connection">
    <Title/Connecting Computations: <<Connection>>/

    <P>
      Oz uses a ticket-based mechanism to establish
      connections between independent Oz processes.
      One process (called <Def/server/) creates a ticket
      with which other sites (called <Def/clients/)
      can establish a connection.
    </P>

    <P>
      A <Def/ticket/ is a character string 
      which can be stored and transported through all media that can
      handle text, e.g., phone lines, electronic mail, paper,
      and so forth. Tickets are insecure, in that they can be forged
      (albeit some luck is required, since they offer some security
      against typos). The following is an example ticket encoded as an
      Oz atom: <<<'x-ozticket://134.96.186.115:9000:egbj0:DS/v:s:kn'>>>
    </P>

    <P>
      The ticket identifies both the server and the value to
      which a remote reference will be made. Independent connections
      can be made to different values on the same server. Once an
      initial connection is established by the value exchanged, then
      further connections as desired by applications can be built from
      programming abstractions, like object, classes, ports or
      procedures.
    </P>
    
    <P>
      Two different types of connections and tickets are supported:
      <List>
        <Entry>
          <Def/One-to-one connections/ and <Def/one-shot tickets/.
        <Item>
          Allow to establish a single connection only.

        <Entry>
          <Def/Many-to-one connections/ and <Def/many-shot tickets/.
        <Item>
          Allow multiple connections with the same ticket to the same
          value. Values for many-to-one connections are offered
          through gates.
       </List>
    </P>

    <P>
      The module <Span class=index/<<Connection>>/ provides procedures
      and classes that support both one-to-one and many-to-one
      connections.
    </P>

    <Section id="Section.Connection.One">
      <Title/One-to-one Connections/

      <P>
        <List>
          <Entry><Span class=index/<<offer>>/
	    <Index/<<Connection>><And><<offer>>/
          <Synopsis>
	    <<{Connection.offer ?_{X} ?_{TicketA}}>>
          <Item>
            Returns the single-shot ticket ?_{TicketA} (an atom)
            under which the value ?_{X} is offered.
          <P>
            The value ?_{X} is exported immediately. An exception is
            raised, if exportation of ?_{X} fails, because ?_{X}
            refers to sited entities.

          <Entry><Span class=index/<<take>>/
	    <Index/<<Connection>><And><<take>>/
          <Synopsis>
	    <<{Connection.take ?+{TicketV} ?_{X}}>>
          <Item>
            Returns the value ?_{X} offered under the ticket
            ?_{TicketV} (a virtual string).
          <P>
            Waits until the connection to the offering process is
            established and the ticket has been acknowledged by that
            process.
          <P>
            Raises an exception if the ticket is illegal, or if the
            offering process does not longer exist.
          <P>
            Also works for many-shot tickets, where an exception might
            be raised if the same ticket is used more than once.
        </List>
      </P>
    </Section>

    <Section id="Section.Connection.Many">
      <Title/Many-to-one Connections/
      
      <P>
        Values for many-to-one connections can be offered through
        <Def/gates/. Values offered through gates can be taken with
        <Span class=index/<<Connection.take>>/ as described for
        one-to-one connections. Gates can be closed which implies that
        the associated ticket becomes invalid. 
      </P>

      <p>
        The special case and frequently occuring case that the gate
        never gets closed is supported by the procedure
        <<Connection.offerUnlimited>> which is as follows:
      </p>

      <P>
        <List>
          <Entry><Span class=index/<<offerUnlimited>>/
	    <Index/<<Connection>><And><<offerUnlimited>>/
          <Synopsis>
	    <<{Connection.offerUnlimited ?_{X} ??{TicketA}}>>
          <Item>
            offers the value ?_{X} under the returned many-shot ticket
            ?_{TicketA} (an atom).
          <P>
            The value ?_{X} is exported immediately. An exception is
            raised, if exportation of ?_{X} fails, because ?_{X} might
            refer to sited entities.
          <p>
            The ticket remains valid until the current Oz process
            terminates.
        </List>
      </P>

      <P>
        Gates are provided as instances of the class
        <Span class=index/<<Connection.gate>>/. The methods of
        <<Connection.gate>> are as follows.
      </P>

      <P>
        <List>
          <Entry><Span class=index/<<init>>/
	    <Index/<<Connection>><And><<gate>><And><<init>>/
          <Synopsis>
	    <code/init(?_{X} ?_{TicketA} <= _)/
          <Item>
            Optionally returns the many-shot ticket ?_{TicketA} (an atom)
            under which the value ?_{X} is offered.
          <P>
            The value ?_{X} is exported immediately. An exception is
            raised, if exportation of ?_{X} fails, because ?_{X} might
            refer to sited entities.

          <Entry><Span class=index/<<getTicket>>/
	    <Index/<<Connection>><And><<gate>><And><<getTicket>>/
          <Synopsis>
	    <code/getTicket(?_{TicketA})/
          <Item>
            Returns the many-shot ticket ?_{TicketA} (an atom) of the
            gate. 

          <Entry><Span class=index/<<close>>/
	    <Index/<<Connection>><And><<gate>><And><<close>>/
          <Synopsis>
	    <code/close()/
          <Item>
            Closes the gate, which makes further use of the associated
            ticket illegal.

        </List>
      </P>
      
    </Section>

  </Chapter>



<!--
Local Variables:
mode: sgml
mode: auto-fill
sgml-default-dtd-file: "part.ced"
sgml-auto-activate-dtd: t
adaptive-fill-mode: nil
End:
-->
