[Freeciv-Dev] patches: multi_conn1 (multiple connections per player)

[David Pfitzner <dwp@xxxxxxxxxxxxxx>]

I have done some work towards having Freeciv allow multiple 
connections per player, such that it is now at "proof of concept"
- aka "basic stuff working for development purposes" - stage.
(Some more general/simple stuff which has come up along the way 
I have been checking-in recently.)

Rather than send too much to this list in one go I have uploaded:

   ftp://ftp.freeciv.org/freeciv/incoming/multi_conn1.tar

This contains 9 patches (+ 1 hack, + .txt explanations) :

conn_lists4
cmd_list_conn2
lsend1c         (need to run automake, adds 3 files)
conn_rulesets1a
notify_conn1
page_conn1
conn_misc1
conn_send_all_info1
conn_easy
hack_multi    (for development/testing only)

Each of these (applied in order) should leave Freeciv compilable 
and runnable, with few user-visible changes at this stage, but 
lots of preparation for future change.  Adding the "hack" patch 
(a better user control is required ;-) allows basic multiple-
connection ability - multiple connections can see same map, move 
same units, etc, although some things may not work, may be awkward 
etc at this stage.

The following section added to freeciv_hackers_guide.txt by one of
the patches outlines the basic architecture and features:

+===========================================================================
+Connections
+===========================================================================
+
+The code is currently transitioning from 1 or 0 connections per player
+only, to allowing multiple connections for each player (recall
+'player' means a civilization, see above), where each connection may
+be either an "observer" or "controller".
+
+This discussion is mostly about connection in the server.  The client
+only has one real connection: 'aconnection' - its connection to the
+server, though it does use some other connection structs (currently
+pplayer->conn) to store information about other connected clients
+(eg, capability strings).
+
+In the old paradigm, server code would usually send information to a
+single player, or to all connected players (usually represented by
+destination being a NULL player pointer).  With multiple connections
+per player things become more complicated.  Sometimes information
+should be sent to a single connection, or to all connections for a
+single player, or to all (established) connections, etc.  To handle
+this, "destinations" should now be specified as a pointer to a struct
+conn_list (list of connections).  For convenience the following
+commonly applicable lists are maintained:
+   game.all_connections   -  all connections
+   game.est_connections   -  established connections
+   game.game_connections  -  connections observing and/or involved in game
+   pplayer->connections   -  connections for specific player
+   pconn->self            -  single connection (as list)
+
+Connections can be classified as follows:  (first match applies)
+
+1. (pconn->used == 0) Not a real connection (closed/unused), should
+   not exist in any list of have any information sent to it.
+
+(All following cases exist in game.all_connections.)
+
+2. (pconn->established == 0) TCP connection has been made, but initial
+   Freeciv packets have not yet been negotiated (join_game etc).
+   Exists in game.all_connections only.  Should not be sent any
+   information except directly as result of join_game etc packets, 
+   or server shutdown, or connection close, etc.
+
+(All following cases exist in game.est_connections.)
+
+3. (pconn->player == NULL) Connection has been established, but is not
+   yet associated with a player.  Currently this is not possible, but
+   the plan is to allow this in future, so clients can connect and
+   then see list of players to choose from, or just control the server
+   or observe etc. Two subcases:
+
+   3a. (pconn->observer == 0) Not observing the game.  Should receive
+       information about other clients, game status etc, but not map,
+       units, cities, etc.
+
+(All following cases exist in game.game_connections.)
+
+   3b. (pconn->observer == 1) Observing the game.  Exists in
+       game.game_connections.  Should receive game information about
+       map, units, cities, etc.
+
+4. (pconn->player != NULL) Connected to specific player, either as
+   "observer" or "controller".  (But observers not yet implemented.)
+   Exists in game.game_connections, and in pconn->player->connections.


Also interesting from a high-level point of view is lsend1c.diff, 
which adds a perl-script which autogenerates a module packets_lsend.[ch].
This is intended to be run manually be developers, so users won't 
need to have perl to compile freeciv etc.

To be properly useable for multi-connections much work is still
required, including client work (above is mostly all server),
but I'm hoping the above patches (except hack_multi) can be added
to CVS soon, since without hack_multi users shouldn't see any 
significant changes.  At least thats the idea - some parts of the 
patches get a bit icky and I may have accidently broken some 
existing code along the way...  (The patches touch enough code that 
they probably won't apply cleanly to changing CVS for very long...)

-- David