[Circle-dev] An overview of Tangence

[Paul LeoNerd Evans]

An overview of Tangence
=======================

Before I go much further, I need to write a lot more about what Tangence
is. Tangence is all of the following:

 1. A single server/multiple client protocol for sharing information
    about objects.

 2. An object model - it defines the abstract look-and-feel of objects 
    that are visible in the server end, and the proxies to them that
    exist in the client ends.
   
 3. A data model - it defines the types of data that objects can take as
    arguments to and results from methods, arguments to events, and
    values of properties.
 
 4. A wire protocol - it defines the bits down the wire of some stream.

 5. A collection of Perl modules (a Perl distribution) which implements
    all of the above.

These writings may sometimes suffer the "Java problem"; the problem of
the same name being applied to too many different concepts. I'll try to
make the context or wording clear to minimise confusions.


1. Server/Client
----------------

In a Tangence system, one program is distinct in being the server. It is
the program that hosts the actual objects being considered. It is also
the program that holds the networking socket to which the clients
connect.

The other programs are all clients, which connect to the server. While
each client is notionally distinct, they all share access to the same
objects within the server. The clients are not directly aware of each
other's existence, though each one's effects on the system may be
visible to the others as a result of calling methods or altering
properties on the objects.


2. Object Model
---------------

In Tangence, the primary item of interaction is an object. Tangence objects
exist in the server, most likely bearing at least some relationship to
some native objects in the server implementation (though if and when the
occasion ever arises that a C program can host a Tangence server,
obviously this association will be somewhat looser). The base class for
all Tangence objects in the server is Tangence::Object.

In the server, two special objects exist - one is the root object, the
other is the Repository. These are the only two well-known objects that
may always be known to exist. All the other objects come from these.

The client(s) interact with the server almost entirely by performing
operations on objects. These are done though instances of
Tangence::ObjectProxy. When the client connects to the server, two
special object proxies are constructed, to represent the root and
repository objects. These are the base through which all the other
interactions are performed. Other object proxies may only be obtained
by the return values of methods on existing objects, arguments passed in
events from them, or retrieved as the value of properties on objects.

Each object is an instance of some particular class. The class provides
all of the typing information for that instance. Principly, that class
defines a name, and the collection of methods, events, and properties that
exist on instances of that class. Each class may also name other classes
as parents; recursively merging the interface of all those named.

2.1. Methods

Each object class may define named methods that clients can invoke on
objects in the server. Each method has:

  + a name
  + argument types
  + a return type

The arguments to a method are positional. 

Methods on objects in the server may be invoked by clients. Once a
method is invoked by a client, the client must wait until it returns
before it can send any other request to the server.

2.2 Events

Each object class may define named events that objects may emit. Each
method has:

    + a name
    + argument types

Like methods, the arguments to an event are positional.

Events do not have return types, as they are simple notifications from the
server to the client, to inform them that some event happened. Clients are
not automatically informed of every event on every object. Instead, the
client must specifically register interest in events.

2.3 Properties

Each object class may define named properties that the object has. Each
object in the class will have a value for the property. Each property has:

    + a name
    + a laziness
    + a dimension - scalar, array, hash or object set
    + a type

Properties do not have arguments. A client can request the current value
of a property on an object, or set a new value. It can also register an
interest in the property, where the server will inform the client of
changes to the value. Changes are sent to the client in an efficient
manner - for example, adding a single element to an array or hash will not
need to resend the entire collection. More on this later.

Certain properties may be define as "autoprops", short for automatic
properties. These are property values that are deemed by the application
to be important enough for all clients to be aware of all of the time
(such as a name or other key item of information). When the server first
sends a new object to a client, the object construction message will also
contain initial values of these properties. The client will be
automatically informed of any changes to these properties when they
change, as if the client had specifically requested to be informed. When
the object is sent to a new client, it is said to be "smashed"; the
initial values of these automatic properties are called "smash values".

[There are issues here that need resolving to move Tangence out from
being Perl-specific into a more general-purpose layer - more on this in
a later email].


3. Data Model
-------------

When executing a method, firing an event, or getting, setting, or updating
the value of a property, the data involved has a type. The underlying
streaming layer recognises the following fundamental types of values:

 * Strings

 * References to Tangence objects

 * Lists of values

 * Dictionaries of (string) named keys to values

These map closely to the fundamental types in Perl. The data model is
applied to each argument to a method or event, the return value of a
method, and the type of a property. In the case of a property, the type
applies to the whole scalar, or to the individual elements in an array
or hash, depending on the dimension of the property. Object set properties
always contain objects.

As Tangence is primarily an interprocess-communication layer, its main
focus is that of communication. The Data Model applies transiently, to
data as it is in transit between the server and a client. A consequence
here is that it only considers the surface value of the types of data,
rather than any deeper significance. It does not preserve self-referential
data, nor can it cope with cyclic structures. More complex shaped data
should be represented by real Tangence objects.

[
 There are also a number of unresolved issues here to deal with export to
 other languages. Primarily, those are 
  * the string/number duallity of perl which exists almost nowhere else
  * how deeply typing information should be applied to collections
  * whether a new type of "structure" should be created, which allows for
    a hetrogenous collection, if typing is applied deeply to arrays and
    hashes
]

4. Wire Protocol
----------------


  (( This section is long enough that it has been removed, and will be
     sent in a separate email ))


5. Perl Distribution
--------------------

The perl distribution is available from

  http://bazaar.leonerd.dyndns.org/perl/Tangence/

At some stage when the details become more concrete this will start
gaining inline documentation, but for now it just has some commenting.

As a rough description of the modules:

5.1. Shared by server and client

  + Tangence::Constants
    Defines various magic numbers used in the wire streaming protocol.

  + Tangence::Stream
    Implements most of the lower level wire streaming protocol, including
    the symmetric parts of data serialisation.

5.2. Used by the client

  + Tangence::Connection
    The connection to the server. Handles the higher-level client-specific
    parts of the wire protocol.

  + Tangence::ObjectProxy
    Acts as a proxy to one particular object within the server. Used for
    invoking methods, subscribing to events, and interacting with
    properties.

5.3. Used by the server

  + Tangence::Object
    A base class for implementing Tangence objects within the server.

  + Tangence::Registry
    The object registry; keeps a reference to every Tangence object in the
    server.

  + Tangence::Server
    A base class for implementing the entire server.

  + Tangence::Server::Connection
    Server end of a client connection. Handles most of the higher-level
    server-specific parts of the wire protocol.

  + Tangence::Server::Context
    An object class to represent the client calling context during the
    invocation of a server object method or property change.


-- 
Paul "LeoNerd" Evans

leonerd at leonerd.org.uk
ICQ# 4135350       |  Registered Linux# 179460
http://www.leonerd.org.uk/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://mail.leonerd.org.uk/pipermail/circle-dev/attachments/20090215/414bea41/attachment.pgp>