              Mobile Ambients primitives on top of Acute
              ******************************************

                       Francesco Zappa Nardelli

                            September 2004

Version: 0.2

Summary:

1) The ambients.ac library
2) The ambients-compiler preprocessor
3) Examples
4) To do
5) License


Section 1: The ambients.ac library
**********************************

The ambients.ac library provides the module Ambients, whose public
interface is

      val ambient : string -> (unit -> unit) -> unit
      val spawn : (unit -> unit) -> unit
      val c_in : string -> unit
      val c_out : string -> unit
      val c_open : string -> unit

      val init : (Tcp.ip option * Tcp.port option) -> unit
      val migrate : Tcp.addr -> unit
      val dump_top_level : unit -> unit

ambient n t
        creates a new ambient named n running t inside the ambient
        where the thread invoking the function is running.

spawn t
        spawns a new thread t inside the ambient where the thread
        invoking the function is running.

c_in n, c_out n, c_open n
        exercise respectively the in n, out n, open n, capabilities;
        they block if the capability cannot be exercised.

init (ipo,po)
        initialises the daemon to receive incoming ambients on the
        port po, if specified (follows usual TCP/IP socket
        conventions).

migrate addr
        disguting implementation of migration of an ambient, together
        with its content to a different runtime, listening on addr.

dump_top_level ()
        dumps on stdout the current ambient structure.


Property 1 (correctness): if P reduces to Q according to MA reduction
semantics, then [[P]] can reduce to a term which is structurally
congruent to [[Q]].


Remark: the correct operation of this module depends on the client
code not using any low-level primitives, in particular thread
creation.  Also, the client code should not interact with the
top_level ambient, eg., the behaviour of an in n capability exercised
at top_level is unspecified.


Section 2: The ambients-compiler preprocessor
*********************************************

The ambients-compiler preprocessor transforms MA processes into the
correspondent Acute clients of the ambients.ac library.

The syntax of processes is defined as

P ::= 0         C ::= in n
   |  C.P          |  out n
   |  P | P        |  open n
   |  n[ P ]       |  dump
   |  *P           |  migrate <port>

where n is an identifier, and port is a port number where an ambient
daemon is lsistening on the local machine.  *P implements sequential
replication.  Parentheses ( ) can also be used.

The syntax of a source file is

<port> P

The port number specified at the beginning of the source file
idenitifies the port at which the local ambient daemon will listen for
incoming ambients.

The dump capability is compiled into an invocation of
Ambients.dump_top_level ().

Usage:

> ambients-compiler filename.ma

preprocesses the file filename.ma, generating filename.ac.  This file
can be edited, and executed using

> ambients-go filename.ac

Alternatively,

> ambients-go filename.ma

compiles the filename.ma file, and then executes the generated
filename.ac.

To build ambients-compiler: the provided Makefile compiles the
ambients-compiler from the ml sources.  It also compiles some .ac
files, for increased speed.


Section 3: Examples
*******************

Below, some terms that exhibit the 9 combinations of capabilities
blocked on other capabilities.  In all cases, synchronisations assure
that the thread exercing the capability being tested has been
initialised.

- in c waits for in a

        a[ b[ open m.in c.dump.0 | m[l[ out b.out a.0] ] ] ]
        | open l.c[ in a.0 ]

- in c waits for out k

        a[ open r.in c.dump.0 | r[ l[out a.in k.in c.0] ] ]
        | k[ c[ open l.out k.0 ] ]

- in c waits for open k

        a[ open r.in c.dump.0 | r[ l[ out a.0 ] ] ]
        | k[ c[ 0 ] ] | open l.open k.0

- out a waits for in a

        k[ open l.in a.0 | open k.out a.dump.0 | l[k[0]]] | a[0]

- out a waits for out b

        a[ b [ k[ open r.out a.dump.0 | open n.out b.0 | r[n[0]]]]]

- out a waits for open l

        a[l[k[ open w.out a.dump.0 | w[ u[out k.out l.0]]]]
        | open u.open l.0   ]

- open k waits for in a

        a[ open b.open k.dump.0 | b[l[out a.in k.0]]] | k [ open l.in a.0 ]

- open k waits for out a

        open l.open k.dump.0 | l[r[in a.in k.0 ]] | a[ k[open r.out a.0] ]

- open k waits for open a

        open r.open k.dump.0 | a[k[0]] | r[l[0]] | open l.open a.0



Section 4: To do
****************

- Optimise the code that is sent by migrate.
- Cleanup the synchronisation informations after a signal.
- Remove the noisy debug informations.
- Add communication.
- Properly trap exceptions.
- Add a transparent top-level (get rid of disgusting migrate).
- Rethink what an ambient name is.
- Add memory protection.


Section 5: License
******************

*** Copyright 2002-2004 The Acute Team

  Allen-Williams, Mair
  Bishop, Steven
  Fairbairn, Matthew
  Habouzit, Pierre [*]
  Leifer, James [*]
  Sewell, Peter
  Sjberg, Vilhelm
  Steinruecken, Christian
  Vafeiadis, Viktor
  Wansbrough, Keith
  Zappa Nardelli, Francesco [*]
  Institut National de Recherche en Informatique et en Automatique (INRIA)

  Contributions of authors marked [*] are copyright INRIA.

All rights reserved.

This file is distributed under the terms of the GNU Lesser General
Public License, with the special exception on linking described in
file NEW-LICENSE.

***


