Updated documentation.

src/network/protocol_manager.hpp

@@ -87,10 +87,48 @@ public:
  *  This class is in charge of storing and managing protocols.
  *  It is a singleton as there can be only one protocol manager per game
  *  instance. Any game object that wants to start a protocol must create a
- *  protocol and give it to this singleton. The protocols are updated in a
+ *  protocol and give it to this singleton. The protocols are updated in two
- *  special thread, to ensure that they are processed independently from the
+ *  different ways:
- *  frames per second. Then, the management of protocols is thread-safe: any
+ *  1) Asynchronous updates:
- *  object can start/pause/... protocols whithout problems.
+ *     A separate threads runs that delivers asynchronous events 
+ *     (i.e. messages), updates each protocol, and handles new requests
+ *     (start/stop protocol etc). Protocols are updated using the
+ *     Protocol::asynchronousUpdate() function.
+ 
+ *  2) Synchronous updates:
+ *     This is called from the main game thread, and will deliver synchronous
+ *     events (i.e. messages), and updates each protocol using
+ *     Protocol::update(). 
+ *
+ *  Since the STK main loop is not thread safe, any game changing events must
+ *  (e.g. events that push a new screen, ...) be processed synchronoysly.
+ *  On the other hand, asynchronous updates will be handled much more
+ *  frequently, so synchronous updates should be avoided as much as possible.
+ *  The sender selects if a message is synchronous or asynchronous. The
+ *  network layer (separate thread) calls propagateEvent in the
+ *  ProtocolManager, which will add the event to the synchronous or
+ *  asynchornous queue.
+ *  Protocol start/pause/... requests are also stored in a separate queue,
+ *  which is thread-safe, and requests will be handled by the ProtocolManager
+ *  thread, to ensure that they are processed independently from the
+ *  frames per second.
+ *
+ *  Events received by ENET are queried and then handled by STKHost::mainLoop.
+ *  Besides messages these events also include connection and disconnection
+ *  notifications. Protocols can decide to receives those notifications or
+ *  not. The Enet events are converted into STK events, which store e.g. the
+ *  sender as STKPeer info, and the message data is converted into a
+ *  NetworkString. This STK event is then forwarded to the corresponding
+ *  protocols.
+ *
+ *  There are some protocols that can have more than one instance running at
+ *  a time (e.g. on the server a connect to peer protocol). The Protocol
+ *  Manager stores each protocol with the same protocol id in a OneProtocol
+ *  structure (so in most cases this is just one protocol instance in one
+ *  OneProtocol structure, but e.g. several connect_to_peer instances would
+ *  be stored in one OneProtocoll instance. The OneProtocol instance is 
+ *  responsible to forward events to all protocols with the same id.
+ *  
  */ 
 class ProtocolManager : public AbstractSingleton<ProtocolManager>,
                         public NoCopy

src/network/stk_host.cpp

@@ -70,7 +70,7 @@ void STKHost::create()
 /** \class STKHost
  *  \brief Represents the local host. It is the main managing point for 
  *  networking. It is responsible for sending and receiving messages,
- *  and keeping track of onnected peers. It also provides some low
+ *  and keeping track of connected peers. It also provides some low
  *  level socket functions (i.e. to avoid that enet adds its headers
  *  to messages, useful for broadcast in LAN and for stun). It can be
  *  either instantiated as server, or as client. 
@@ -141,7 +141,7 @@ void STKHost::create()
  *
  * Server:
  *
- *   The ServerLobby (SLR) will then detect the above client
+ *   The ServerLobbyProtocol (SLP) will then detect the above client
  *   requests, and start a ConnectToPeer protocol for each incoming client.
  *   The ConnectToPeer protocol uses:
  *         1. GetPeerAddress to get the ip address and port of the client.
@@ -151,7 +151,7 @@ void STKHost::create()
  *            destination (unless if it is a LAN connection, then UDP
  *            broadcasts will be used). 
  *
- *  Each client will run a ClientLobbyProtocol (CLR) to handle the further
+ *  Each client will run a ClientLobbyProtocol (CLP) to handle the further
  *  interaction with the server. The client will first request a connection
  *  with the server (this is for the 'logical' connection to the server; so
  *  far it was mostly about the 'physical' connection, i.e. being able to send
@@ -163,8 +163,8 @@ void STKHost::create()
  *  sent by protocol X on the server will be received by protocol X on the
  *  client and vice versa. The only exception are the client- and server-lobby:
  *  They share the same id (set in LobbyProtocol), so a message sent by
- *  the SLR will be received by the CLR, and a message from the CLR will be
+ *  the SLP will be received by the CLP, and a message from the CLP will be
- *  received by the SLR.
+ *  received by the SLP.
  *
  *  The server will reply with either a reject message (e.g. too many clients
  *  already connected), or an accept message. The accept message will contain
@@ -179,17 +179,17 @@ void STKHost::create()
  *  of all connected clients. This information is stored in an array of
  *  NetworkPlayerProfile managed in GameSetup (which is stored in STKHost).
  *
- *  When the authorised clients starts the kart selection, the SLR
+ *  When the authorised clients starts the kart selection, the SLP
- *  informs all clients to start the kart selection (SLR::startSelection).
+ *  informs all clients to start the kart selection (SLP::startSelection).
  *  This triggers the creation of the kart selection screen in 
- *  CLR::startSelection / CLR::update for all clients. The clients create
+ *  CLP::startSelection / CLP::update for all clients. The clients create
  *  the ActivePlayer object (which stores which device is used by which
  *  player).  The kart selection in a client calls
- *  (NetworkKartSelection::playerConfirm) which calls CLR::requestKartSelection.
+ *  (NetworkKartSelection::playerConfirm) which calls CLP::requestKartSelection.
- *  This sends a message to SLR::kartSelectionRequested, which verifies the
+ *  This sends a message to SLP::kartSelectionRequested, which verifies the
  *  selected kart and sends this information to all clients (including the
  *  client selecting the kart in the first place). This message is handled
- *  by CLR::kartSelectionUpdate. Server and all clients store this information
+ *  by CLP::kartSelectionUpdate. Server and all clients store this information
  *  in the NetworkPlayerProfile for the corresponding player, so server and
  *  all clients now have identical information about global player id, player
  *  name and selected kart. The authorised client will set some default votes
@@ -198,9 +198,9 @@ void STKHost::create()
  *
  *  After selecting a kart, the track selection screen is shown. On selecting
  *  a track, a vote for the track is sent to the client
- *  (TrackScreen::eventCallback, using CLR::voteTrack). The server will send
+ *  (TrackScreen::eventCallback, using CLP::voteTrack). The server will send
- *  all votes (track, #laps, ...) to all clients (see e.g. SLR::playerTrackVote
+ *  all votes (track, #laps, ...) to all clients (see e.g. SLP::playerTrackVote
- *  etc), which are handled in e.g. CLR::playerTrackVote().
+ *  etc), which are handled in e.g. CLP::playerTrackVote().
  *
  *  --> Server and all clients have identical information about all votes
  *  stored in RaceConfig of GameSetup.