From 106cb1181f5861c9fd4b16b8217083d840065a68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonatan=20P=C3=A5lsson?= Date: Mon, 2 May 2011 12:29:03 +0200 Subject: [PATCH] Added info on coordinator module and table module --- report.lyx | 320 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+) diff --git a/report.lyx b/report.lyx index 812d734..b9866fb 100644 --- a/report.lyx +++ b/report.lyx @@ -81,6 +81,12 @@ morestring=[b]', morestring=[b]" } + +\usepackage{float} + +\floatstyle{ruled} +\newfloat{code}{thp}{lop} +\floatname{code}{Code} \end_preamble \use_default_options true \maintain_unincluded_children false @@ -3623,6 +3629,236 @@ name "sub:The-structure-of" \end_inset +\end_layout + +\begin_layout Standard +The GGS protocol is modelled after the HTTP protocol. + The main reason for this is the familiarity many developers already have + with HTTP due to its presence in internet software. + Each GGS protocol packet contains a headers section. + The headers section is followed by a data section. + In the headers section, parameters concerning the packet is placed. + In the data section, the actual data payload of the packet is placed. +\end_layout + +\begin_layout Standard +There is no requirement of any specific order of the parameters in the headers + section, however the data section must always follow directly after the + headers section. +\end_layout + +\begin_layout Standard +In the example below, line 1 contains a Game-Command parameter. + This parameter is used to determine which game-specific command the client + is trying to perform. + The handling of this parameter is specific to each game, and can be anything. +\end_layout + +\begin_layout Standard +Line 2 specifies a game token. + This is a UUID which is generated for each client upon authentication with + the GGS. + The GGS uses this token in case a client is disconnected and the new connection + created when the client reconnects must be re-paired with the player object + inside the GGS. + The UUID is also used as a unique ID within GDL VMs. +\end_layout + +\begin_layout Standard +Line 3 specifies the content type of the payload of this particular packet. + This parameter allows the GGS to invoke special parsers, should the data + be encoded or encrypted. + When encryption is employed, only the payload is encrypted, not the header + section. + This is a scheme which does not allow for strong encryption, but is deemed + feasible for gaming purposes. +\end_layout + +\begin_layout Standard +Line 4 specifies the content length of the payload following immediately + after the headers section. +\end_layout + +\begin_layout Standard +The parser of the GGS protocol implemented in the GGS prototype is designed + as a finite state machine using the gen_fsm behaviour. + When a full message has been parsed by the parser, the message is converted + into the internal structure of the GGS messages, and sent in to the system + from the protocol paser using message passing. +\end_layout + +\begin_layout Standard +\begin_inset Note Note +status open + +\begin_layout Plain Layout +Packet below is not an algorithm, but I don't know how to change that label.. +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Standard +\begin_inset Float algorithm +wide false +sideways false +status open + +\begin_layout Plain Layout +\begin_inset ERT +status open + +\begin_layout Plain Layout + + +\backslash +lstset{ +\end_layout + +\begin_layout Plain Layout + +backgroundcolor= +\backslash +color{white}, +\end_layout + +\begin_layout Plain Layout + +extendedchars=true, +\end_layout + +\begin_layout Plain Layout + +basicstyle= +\backslash +footnotesize +\backslash +ttfamily, +\end_layout + +\begin_layout Plain Layout + +showstringspaces=false, +\end_layout + +\begin_layout Plain Layout + +showspaces=false, +\end_layout + +\begin_layout Plain Layout + +numbers=left, +\end_layout + +\begin_layout Plain Layout + +numberstyle= +\backslash +footnotesize, +\end_layout + +\begin_layout Plain Layout + +numbersep=9pt, +\end_layout + +\begin_layout Plain Layout + +tabsize=2, +\end_layout + +\begin_layout Plain Layout + +breaklines=true, +\end_layout + +\begin_layout Plain Layout + +showtabs=false, +\end_layout + +\begin_layout Plain Layout + +captionpos=b +\end_layout + +\begin_layout Plain Layout + +} +\end_layout + +\begin_layout Plain Layout + + +\backslash +begin{lstlisting} +\end_layout + +\begin_layout Plain Layout + +Game-Command: chat +\end_layout + +\begin_layout Plain Layout + +Token: e30174d4-185e-493b-a21a-832e2d9d7a1a +\end_layout + +\begin_layout Plain Layout + +Content-Type: text +\end_layout + +\begin_layout Plain Layout + +Content-Length: 18 +\end_layout + +\begin_layout Plain Layout + +\end_layout + +\begin_layout Plain Layout + +Hello world, guys! +\end_layout + +\begin_layout Plain Layout + + +\backslash +end{lstlisting} +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Plain Layout +\begin_inset Caption + +\begin_layout Plain Layout +\begin_inset CommandInset label +LatexCommand label +name "alg:A-sample-packet" + +\end_inset + +A sample packet sent from a client to the GGS during a chat session +\end_layout + +\end_inset + + +\end_layout + +\end_inset + + \end_layout \begin_layout Standard @@ -3650,10 +3886,94 @@ name "sub:The-coordinator-module" \end_layout +\begin_layout Standard +The coordinator module is responsible for keeping track of all players, + their seats and tables. + Players register with the coordinator process when first connecting to + the server, and the coordinator places each player by their respective + table. +\end_layout + +\begin_layout Standard +The coordinator keeps mappings between each player and table, therefore + it is used to perform lookups on tables and players to find out which are + connected. + The connectivity of players and tables is important when sending messages + to all participants in a game. + A lookup in the coordinator process is performed prior to notifying all + players in a game to ensure the message reaches all players. + The lookup can be performed either using internal identification codes + or using the UUID associated with each client and table. +\end_layout + +\begin_layout Standard +The coordinator process contains important state, therefore a backup process + is kept at allt times. + All good data processed by the coordinator is stored for safekeeping in + the backup process as well. + Data which is potentisally harmful is not stored in the backup process. +\end_layout + +\begin_layout Standard +Upon a crash, the coordinator process recovers the prior good state from + the backup process and continues where it left off. + A supervisor process monitors the coordinator process and restarts the + process when it malfunctions. + There is a window of time between the crash of the coordinator and the + restarting of the coordinator, during this time, players can not be seated + by new tables, and can not disconnect from the server. + This window of time is very small, and the unavailability of the coordinator + process should not be noticed by more than a short time lag for the clients. +\end_layout + +\begin_layout Standard +Moving back to the example of the chess club, the coordinator process can + be seen as a judge, monitoring all moves of the players. + At the same time as acting as a judge, the coordinator process is also + a host in the chess club, seating players by their tables and offering + services to the players. +\end_layout + \begin_layout Subsection The table module \end_layout +\begin_layout Standard +The table module is mostly a hub used for communication. + New table processes are created by the coordinator on demand. + The table module does not contain any business logic, however each process + contains information concerning which players are seated by that particular + table. +\end_layout + +\begin_layout Standard +The information about which players are seated by each table is used when + notifying all players by a table of an action. + Consider a game of chess, each player notifies the table of its actions, + the table then notifies the rest of the participants of these actions after + having had the actions processed by the game VM, where an action could + be moving a playing piece. +\end_layout + +\begin_layout Standard +Each table is associated with a game VM. + The actions sent to a table are processed by the game VM, this is where + the game logic is implemented. +\end_layout + +\begin_layout Standard +After a crash in a table process, the entire table must be rebuilt and the + players must be re-associated with the table. + Data concerning players is kept in the coordinator process, and is restored + from there. + Data kept in the actual game is not automatically corrupted by the crash + in a table, however the table must be re-associated with the game VM is + was associated with prior to the crash of the table. + The table process maps well into the setting of the real-worl chess clib + scenario previously discussed. + A table works in the same way in a real world setting as in the GGS setting. +\end_layout + \begin_layout Subsection The game virtual machine module \end_layout