[Freeciv-Dev] Client AI development

[Raimar Falke <hawk@xxxxxxxxxxxxxxxxxxxxxxx>]

Cell based client structure
===========================

Problem
-------

There is a consensus that it is bad that high level functions are in
the server (for reasons see previous discussions). These functionality
is better placed outside the server: at the client. It is not clear
how this can be achieved. The following idea tries to address this
problem.

Based on experience of other people and my own a solution should
fulfill the following requirements:

 - expandable (it should be easy to insert new code)
 - stackable (it should be possible to build upon functionality which
              other parts of the structure provide)
 - no fixed language (in a heterogeneous environment like UNIX it is
                      not a good idea to force someone to use a
                      certain language)

Also the issue of concurrency has to be addressed.

Stack of Cells
--------------

The proposal is a structure of interconnected cells. These cells form
a graph. All interconnections are bidirectional. The bottom is the
network. Each cell has exactly two connections: one upward and one
downwards. It is possible to put more than one cell on the
input/output of another cell by using a connector. 

Each cell can run in its own process. But it is also possible that the
whole "stack" run in one process.

Cells exchange messages. Messages are expressed in XML. XML parsers
should available in almost every language. Every language can generate
XML. Messages travel up or down the stack. If a cell doesn't know how
to handle a messages the message is passed on. If the cell is the only
receiver of a message (its target), the message is process and not
passed on. The BottomTerminator (see figure) collects unhandled
messages.

It is allowed and encouraged to use other forms of messaged exchange
besides XML if cells run in one process (data structures) or in the
same language (Java cells can send serialized message objects).

There will be a control program which starts all cells and provides
the cell with information about their connections.

Possible Cells
--------------

The following cells are good to have:

 - BottomTerminator: issues warning about unhandled messages
 - Network: translates between the freeciv wire protocol and XML
 - History: provides information about objects (units, cities,...) 
            based on queries, issues notification messages (attribute
            "size" has change from 3 to 4 in city 23)
 - BasicCommands: translates basic commands (move unit, rename city)
                  to (XMLed) packets
 - a GUI cell: a stripped down GTK client?
 - other cells: provide high level functions (formerly known as
                agents)

Concurrency
-----------

Requests usually travel downwards and responses upwards. The other
direction is also possible (Dicider asks an Advisor cell). Not every
message is a request or a response (notification messages). A request
results in exactly one response (which can contain a lot of
information). Every request has an ID. Every response contains the ID
of the original request.

It is not possible to ensure that nothing other happens during the
execution of a request. At least if the request involves direct or
indirect communication which the server. So every Cell has to assume
that the data is only a snapshot. However the response act as a
terminator (the action has been carried out (maybe together with other
actions)).

So what can a cell do if it wants some infos about a certain object? 
It issues the request for the History and waits. But how? I see two
possibilities:
 - read the input and push all messages which isn't the expected
   response into a waiting queue. Deal with the response and
   afterward process the queued messages.
 - true multi threaded: one input thread, one thread for every message
   which get processed. After the request is sent the thread sniffs
   the incoming messages.

Open issues
-----------

 - define the DTD for the basic message. Each cell will provide its own DTD
 - determine how the connections are realized: sockets, fifo, files,...
 - determine what kind of time the History is based upon (turns are too
   broad: on a certain turn a enemy unit may be visible only for a
   short time)


What to you thing? Overengineered? Do you think it is realizable?

        Raimar

-- 
 email: rf13@xxxxxxxxxxxxxxxxx
 "Despite all the medical advances of the 20th century, the mortality 
  rate remains unchanged at 1 death per person."

cell.png
Description: PNG image