add: report source and pdf

report/Report.cls

@@ -0,0 +1,73 @@
+% --- identification
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesClass{standard-doc}[2001/03/03 UoBnote class]
+
+% --- using pkgs
+\RequirePackage{fancyhdr}
+\RequirePackage{lastpage}
+\RequirePackage[T1]{fontenc}
+\RequirePackage[british]{babel}
+%\RequirePackage[margin=0.5in]{geometry}
+%\RequirePackage[margin=0.5in]{geometry}
+
+% --- define options
+\DeclareOption{twocolumn}{\OptionNotUsed}
+\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
+\ProcessOptions\relax
+
+\LoadClass[a4paper,11pt]{article}
+
+% --- load class
+
+
+% color is switched on, use the color package
+
+\def\issue#1{\gdef\@issue{#1}}
+\def\@issue{\@latex@error{No \noexpand\issue given}\@ehc}
+\def\shorttitle#1{\gdef\@shorttitle{#1}}
+\def\@shorttitle{\@latex@error{No \noexpand\shorttitle given}\@ehc}
+
+\renewcommand\maketitle{
+  \begin{titlepage}\begin{center}
+      {\includegraphics[scale=0.1]{TrentoLOGO.png}}
+      \vskip2cm
+      {\LARGE \bf \@title \par}%
+      \vskip 3em%
+      {\large
+        \lineskip .75em%
+        \begin{tabular}[t]{c}%
+          \@author
+        \end{tabular}\par}%
+      \vskip 1.5em%
+      {\normalsize \@date \par}%
+      \vfil\null%
+      {\small
+        University of Trento\\
+        Department of Information Engineering and Computer Science~-~DISI\\
+        Via Sommarive, 9 I-38123\\
+        Povo (TN), Italy\\
+        % E-Mail: Username[at]star.sr.bham.ac.uk
+      } \end{center}
+  \end{titlepage}
+}
+
+\newcommand\fancytoc{
+    \pagestyle{plain}
+
+    \pagenumbering{roman}
+
+    \tableofcontents{\clearpage}
+
+    \pagestyle{fancy}
+
+    \pagenumbering{arabic}
+}
+
+\rhead{\@title}
+
+\lfoot{} 
+\cfoot{{\footnotesize \thepage~\textit{of}~\pageref{LastPage}}} 
+\rfoot{}
+
+
+\message{note completed OK}

report/img/election.drawio

@@ -0,0 +1,113 @@
+<mxfile host="app.diagrams.net" modified="2024-08-06T13:59:41.664Z" agent="Mozilla/5.0 (X11; Linux x86_64; rv:128.0) Gecko/20100101 Firefox/128.0" etag="nvtsWTmICnw4uKqCY2U_" version="23.1.1" type="device">
+  <diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">
+    <mxGraphModel dx="1685" dy="894" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="WIyWlLk6GJQsqaUBKTNV-0" />
+        <mxCell id="WIyWlLk6GJQsqaUBKTNV-1" parent="WIyWlLk6GJQsqaUBKTNV-0" />
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="WIyWlLk6GJQsqaUBKTNV-3" target="mqRZgJOydVEEGR6u9X0a-1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="WIyWlLk6GJQsqaUBKTNV-3" value="Election message arrives" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+          <mxGeometry x="354" y="20" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-1" target="mqRZgJOydVEEGR6u9X0a-3">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-1" value="Sends ElectionACK to the sender" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="354" y="110" width="120" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-6" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;horizontal=1;comic=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-3" target="mqRZgJOydVEEGR6u9X0a-5">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-11" value="Yes" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="mqRZgJOydVEEGR6u9X0a-6">
+          <mxGeometry x="-0.1316" y="1" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-41" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-3" target="mqRZgJOydVEEGR6u9X0a-37">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="655" y="280" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-42" value="No" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="mqRZgJOydVEEGR6u9X0a-41">
+          <mxGeometry x="-0.1589" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-3" value="Already in &lt;br&gt;election state?" style="rhombus;whiteSpace=wrap;html=1;align=center;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="359.25" y="200" width="109.5" height="70" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-13" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-5" target="mqRZgJOydVEEGR6u9X0a-12">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-14" value="Yes" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="mqRZgJOydVEEGR6u9X0a-13">
+          <mxGeometry x="-0.25" y="1" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-16" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-5" target="mqRZgJOydVEEGR6u9X0a-15">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-17" value="No" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="mqRZgJOydVEEGR6u9X0a-16">
+          <mxGeometry x="-0.0533" y="-1" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-5" value="Is the message id&lt;br&gt;equals to my id?" style="rhombus;whiteSpace=wrap;html=1;align=center;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="70" y="280" width="130" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-26" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-12" target="mqRZgJOydVEEGR6u9X0a-25">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-12" value="Become new coordinator" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="280" y="310" width="80" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-19" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-15" target="mqRZgJOydVEEGR6u9X0a-18">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-21" value="Yes" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="mqRZgJOydVEEGR6u9X0a-19">
+          <mxGeometry x="-0.0705" y="1" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-24" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-15" target="mqRZgJOydVEEGR6u9X0a-23">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-15" value="Is the received candidate&lt;br&gt;better than the store one?" style="rhombus;whiteSpace=wrap;html=1;align=center;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="40" y="430" width="190" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-18" value="Forward received message" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="374" y="455" width="80" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-23" value="Do nothing" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="95" y="565" width="80" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-25" value="Multicast synch" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="279.25" y="380" width="80" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-43" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-37" target="mqRZgJOydVEEGR6u9X0a-18">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-44" value="Yes" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="mqRZgJOydVEEGR6u9X0a-43">
+          <mxGeometry x="0.3699" y="-1" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-46" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="WIyWlLk6GJQsqaUBKTNV-1" source="mqRZgJOydVEEGR6u9X0a-37" target="mqRZgJOydVEEGR6u9X0a-45">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-47" value="No" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="mqRZgJOydVEEGR6u9X0a-46">
+          <mxGeometry x="-0.0304" y="2" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-37" value="Is the received candidate&lt;br&gt;better than the store one?" style="rhombus;whiteSpace=wrap;html=1;align=center;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="560" y="285" width="190" height="90" as="geometry" />
+        </mxCell>
+        <mxCell id="mqRZgJOydVEEGR6u9X0a-45" value="Sends me as new leader" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" vertex="1" parent="WIyWlLk6GJQsqaUBKTNV-1">
+          <mxGeometry x="615" y="455" width="80" height="40" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

report/main.tex

@@ -0,0 +1,49 @@
+\documentclass[11pt]{report}
+
+\usepackage{hyperref}
+%\usepackage[sorting=nty,backend=biber]{biblatex}
+\usepackage[paperheight=29.7cm,paperwidth=21cm,outer=1.5cm,inner=2.5cm,top=2cm,bottom=2cm]{geometry}
+\usepackage{graphicx}
+\usepackage{fancyhdr}
+\usepackage{amsmath}
+%\usepackage{listings}
+
+\graphicspath{{./img/}}
+%\addbibresource{biblio.bib}
+\pagestyle{fancy}
+%\lstdefinestyle{mystyle}{
+%  basicstyle=\ttfamily\footnotesize,
+%  breakatwhitespace=false,
+%  breaklines=true,
+%  captionpos=b,
+%  keepspaces=true,
+%  numbers=left,
+%  numbersep=5pt,
+%  showspaces=false,
+%  showstringspaces=false,
+%  showtabs=false,
+%  tabsize=2
+%}
+%\lstset{style=mystyle}
+
+\author{Blascovich Alessio, Cereser Lorenzo}
+\title{Distributed Systems Report}
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+%\fancytoc
+
+\input{sections/simulation.tex}
+
+\input{sections/aux-data-struct.tex}
+
+\input{sections/crashes.tex}
+
+\input{sections/election.tex}
+
+\input{sections/synch.tex}
+
+\end{document}

report/sections/aux-data-struct.tex

@@ -0,0 +1,37 @@
+\section{Auxiliary data structures}
+
+%Description of these two data structures. Particular emphasis on the timeout system.
+
+\subsection{Pairs History}\label{subsec:pairshostory}
+
+\texttt{it.unitn.disi.ds1.qtop.PairsHistory.java}
+
+To maintain a certain degree of consistency, the nodes had to keep track of the various updates proposed by the coordinator.
+
+We decided to use a matrix to represent the history of updates. The epoch and sequence are used as indices to access and update the matrix. Every matrix's cell contains a tuple with the value proposed and the commitment state.
+
+The commitment state can be either ``PENDING'', ``WRITEOK'' or ``ABORT''. The latter two flags an update as already decided by the coordinator, respectively, committed or discarded. The former indicates that an update is idle, waiting for a decision from the coordinator.
+
+The use of a matrix has been motivated, by the intuitive use of the update pair elements as indices of the structure. We could have used a map, however, it seemed an over-abstracted and over-complicated data structure compared to a matrix.
+
+\subsection{Timeuots manager}
+
+\texttt{it.unitn.disi.ds1.qtop.TimeOutManager.java}
+
+To manage many \textit{ACK}s and to detect a coordinator failure the various nodes have to use a series of countdowns and timeouts. 
+
+We utilised a map optimised for the use of \textit{enum} values as keys. Every value of the map is a tuples array, every tuple contains a \textit{Cancellable} and a natural number.
+
+The \textit{Cancellable} is a scheduled message that a node sends to itself to mimic a countdown and decrease the natural number. The natural number has as its initial value the number set by the user before starting the simulation, once it reaches zero it is considered to be expired, hence, its respective countdown is cancelled and the node self sends a \textit{TimeOut} message.
+
+The timeouts manager is used for many \textit{ACK}s, these messages invalidate the respective countdowns upon reception. The \textit{HeartBeat}s countdown has a different behaviour, once an \textit{HeartBeat} is received the countdown is reset to its initial value and starts again.
+
+\subsection{Voters map}
+
+\texttt{it.unitn.disi.ds1.qtop.VotersMap.java}
+
+To make a final decision, the coordinator had to keep track of all the votes cast for every update proposed.
+
+This structure is similar to the one used in~\ref{subsec:pairshostory}. Except this time the matrix holds, for every cell, a tuple containing a map with all the voters and the final decision imposed by the coordinator.
+
+Here too the epoch and the sequence are used as indices. In every cell beside the map, there is the final decision cast by the coordinator or a phoney value in case the node is still waiting for the decision to be cast. As in~\ref{subsec:pairshostory} the value of the decision can be either ``PENDING'', ``WRITEOK'' or ``ABORT''.

report/sections/crashes.tex

@@ -0,0 +1,30 @@
+\section{Crash system}
+
+Crashes can be induced at run-time, through the user interface, at specific points to observe how the system reacts and to ensure that it can recover or continue to operate despite failures. 
+
+The types of crashes that can be simulated include both node and coordinator crashes during different operational stages:
+\begin{itemize}
+    \item Normal node - Before receiving a new write request from a client
+    \item Normal node - After forwarding a new write request to a coordinator
+    \item Normal node - After receiving a vote request from the coordinator
+    \item Normal node - After casting the vote for a request
+    \item Normal node - Before the acknowledgement of an election message
+    \item  Normal node - After an election message is sent or forwarded
+    \item Coordinator node - During the multicast of a vote request
+    \item Coordinator node During the multicast of a decision response
+\end{itemize}
+
+
+To mimic a real crush, this system picks a client which will send the designated crush request to a random node. Then, if the node does not match the recipient it will forward the message to a compatible node. 
+\begin{center}
+    \begin{tabular}{|p{0.9\textwidth}|}
+        \hline
+        \textbf{E.g.}\\
+        If the user inserts a crush of type ``normal node'', and the client sends it to the coordinator, then the coordinator will forward it to a random node within the network.\\
+        \hline
+    \end{tabular} 
+\end{center}
+
+The node (or coordinator) that receives the crash message does not crash. Instead, it enters a virtual crash state where every message received is simply ignored; as by specification, a crashed node does not recover from its crashed state.
+
+The last two crush types are peculiar, they are probabilistic crushes. To create more realistic scenarios, and generate inconsistency among the nodes, the coordinator can crush only during the multicast of some messages. Every message that it sends during a multicast has a 20\% chance to make the coordinator crush.