Differenze

Queste sono le differenze tra la revisione selezionata e la versione attuale della pagina.

--- lpr-b:lpr-b-09:progetto [18/12/2009 alle 12:51 (15 anni fa)] – Andrea Corradini
+++ lpr-b:lpr-b-09:progetto [01/02/2010 alle 09:47 (15 anni fa)] (versione attuale) – Andrea Corradini
@@ Linea 1: / Linea 1: @@
 ====== Progetto ======
-**__Pagina provvisoria__**
+Questa pagina descrive il **I Progetto di LPR 2009/10 **.
+===== Descrizione del gioco =====
+^ Fiorellini & Formichine ^ Alieni & Astronavi ^
+|In un prato virtuale spuntano dei fiorellini a intervalli di tempo casuali e in posizioni casuali. Ogni giocatore ha a disposizione al massimo cinque formichine,  che può far muovere sul prato per raggiungere i fiorellini e raccoglierli. I giocatori operano simultaneamente e in concorrenza. Vince chi raccoglie più fiorellini in un tempo predeterminato.|Nello spazio profondo si è aperto un tunnel iperspaziale, tramite il quale una razza di alieni aggressivi piazza delle mine nel nostro territorio a intervalli di tempo casuali e in posizioni casuali. Ogni giocatore ha a disposizione al massimo cinque astronavi, che può far muovere nello spazio per raggiungere le mine e disinnescarle. I giocatori operano simultaneamente e in concorrenza. Vince chi disinnesca più mine in un tempo predeterminato.|
+|Il campo di gioco è rappresentato da una matrice quadrata di lato 512 unità (a coordinate intere) che è gestita da un server. Il giocatore deve definire un client, rappresentante una singola unità, che verrà lanciato in cinque istanze al momento del gioco. Il client interagisce con il server tramite TCP e tramite multicast, con il protocollo descritto di seguito. Inoltre le varie istanze del client possono interagire tra di loro, con modalità abitrarie, per realizzare strategie di cooperazione che consentano di ottenere una maggior efficienza.||
 ===== File eseguibili =====
@@ Linea 38: / Linea 46: @@
 ===== Documentazione del protocollo =====
-TBC
+Il protocollo di comunicazione è diviso in quattro parti: comunicazioni TCP dal client al server; comunicazioni TCP dal server al client; comunicazioni Multicast UDP dal server ai client; comunicazioni intra-client. Di queste, solo le prime due sono obbligatorie perché il client possa funzionare; le secondo due sono però utili per aumentarne l'efficienza e per implementare strategie di gioco più sofisticate. Ciascuna parte è descritta nel seguito.
-===== Modalità di consegna =====
+==== Convenzioni generali ====
+=== Formato ===
+Tutti i messaggi scambiati fra client e server seguono un formato uniforme, così composto: un byte di comando, seguito da due byte per la lunghezza dei dati, seguiti dai dati (se presenti). Tutti i valori numerici single-byte sono espressi come interi con segno su 8 bit; tutti i valori numerici multi-byte sono espressi come interi con segno su 16 bit in formato big-endian.
+Tutti i pacchetti scambiati sono di dimensioni assai minori della MTU tipica su reti TCP/IP (1460 byte); è quindi possibile assumere che non si avrà frammentazione dei pacchetti stessi.
+=== Temporizzazione ===
+Ciascun cliente **deve** inviare almeno un messaggio ogni 1000ms (altrimenti viene dichiarato //morto di sonno// e chiuso), e non più di un messaggio ogni 100ms (altrimenti viene dichiarato //spammer// e chiuso). È possibile usare il messaggio PING almeno una volta per secondo per segnalare che il cliente è ancora vivo, se non si ritiene più utile qualche altro messaggio.
+=== Fairness ===
+Tentativi di sabotare il server o il protocollo sono lodevoli, ma considerati illegali ai fini dell'esame. È possibile contattare il docente per verificare la "legalità" di una tecnica non ortodossa che si intende usare. È altresì considerato illegale usare nella propria implementazione classi del server o del client di esempio, estratte dal codice fornito.
+==== Messaggi TCP dal client al server ====
+| 1 byte || 2 byte | //Len// byte | | |
+^ Comando ^^ Len ^ Dati ^ Descrizione ^ Risposta ^
+^ Nome ^ Valore ^ ^ ^ ^ ^
+^ REGISTER | 7 | //n// | //n// byte (secondo l'encoding usato dalla classe String di Java), nome //squadra// | registra il client presso il server, iscrivendolo alla //squadra// indicata. Se la //squadra// non esiste viene creata; se alla squadra sono già iscritti il numero massimo di giocatori, la registrazione viene rifiutata (vedi il messaggio di risposta). Il cliente **deve** essere validamente registrato prima che possano essere inviati altri comandi. Una volta registrato, ulteriori comandi **REGISTER** sono invalidi. ^ YOURID |
+^ PING | 1 | 0 | | Segnala al server la propria presenza. ^ PONG |
+^ MOVE | 2 | 4 | //x//,//y// | Chiede al server si portare il giocatore alle coordinate //x//,//y//; il trasferimento può richiedere un tempo significativo, a seconda della distanza; durante tale tempo è possibile inviare altri comandi (inclusi altri MOVE). Giunto a destinazione, il giocatore si ferma automaticamente (fino a un successivo MOVE). ^ |
+^ GRAB | 3 | 0 | | Chiede al server di raccogliere gli eventuali target presenti alla posizione corrente del giocatore. ^ GRABRESULT |
+^ GETPOS | 4 | 0 | | Chiede al server di restituire la posizione corrente del giocatore. ^ LOC |
+^ LOOK | 5 | 0 | | Chiede al server l'elenco di tutti i target presenti al momento nel campo di gioco. ^ TARGETS |
+^ LOAD | 6 | 0 | | Chiede al server il carico corrente del giocatore (quanti target ha raccolto finora). ^ YOURLOAD |
+==== Messaggi TCP dal server al client ====
+| 1 byte || 2 byte | //Len// byte | |
+^ Comando ^^ Len ^ Dati ^ Descrizione |
+^ Nome ^ Valore ^ ^ ^ ^
+^ YOURID | 69 | 2 | //n// | //n// è il numero assegnato al giocatore registrato; valori legali sono 0-4, mentre -1 indica che la registrazione è stata rifiutata. |
+^ PONG | 64 | 0 | | Risposta al messaggio PING; non contiene dati, ma indica che è stato ricevuto il segnale di presenza. |
+^ LOC | 65 | 4 | //x//,//y// | Fornisce la posizione corrente del giocatore (coordinate //x//,//y// sul campo di gioco). |
+^ YOURLOAD | 66 | 2 | //n// | Fornisce il carico corrente del giocatore, ovvero quanti target ha raccolto dal momento della registrazione fino ad ora. |
+^ TARGETS | 67 | 4//n// | //x//_1,//y//_1 ... //x_n//,//y_n// | Fornisce le coordinate di tutti i target presenti sul campo di gioco. |
+^ GRABRESULT | 68 | 2 | //k// | Segnala che sono stati raccolti //k// target con l'ultimo GRAB (0=nessuno; è possibile che //k//>1 se esistevano più target alle stesse coordinate). |
+==== Messaggi Multicast UDP dal server al client ====
+| 1 byte || 2 byte | //Len// byte | |
+^ Comando ^^ Len ^ Dati ^ Descrizione ^
+^ Nome ^ Valore ^ ^ ^ ^
+^ TARGETS | 67 | 4 | //x//,//y// | Segnala che è comparso un nuovo target alle coordinate //x//,//y// sul campo di gioco. |
+Si noti che non esistono messaggi per avvisare della //scomparsa// di un target.
+==== Comunicazioni intra-client ====
+Il protocollo, i formati, e il tipo di comunicazione (tipicamente: TCP, UDP, Multicast o RMI) fra client sono interamente a discrezione dello studente, che dovrà darne documentazione nella relazione. In ogni caso, i vari clienti devono essere istanze dello stesso eseguibile, eseguite su JVM distinte e potenzialmente su macchine diverse. Non è ammessa la comunicazione fra client che utilizzi tecniche diverse dalla comunicazione via rete.
+==== Trattamento degli errori e terminazione ====
+Se il server riconosce un errore nel comportamento del client, la comunicazione viene interrotta (il giocatore rimane registrato ma viene "espulso" dal gioco). In caso di errori da parte di un client la squadra continua il gioco con i giocatori rimanenti.
+Il gioco non prevede la possibilità di de-registrare un giocatore, né un esplicito "fine partita"; ogni esecuzione del server corrisponde a una partita, che può essere interrotta in qualunque momento interrompendo il server (da tastiera con Ctrl-C o chiudendo la sua finestra).
+===== Requisiti generali e modalità di consegna =====
 Ogni studente che vuole sostenere l'esame di LPR deve consegnare il
 progetto svolto al docente del corso di appartenenza (Prof. Gervasi per il Corso A, Prof. Corradini per il Corso B).
-Il progetto deve essere consegnato individualmente, ma puo essere
+Il progetto deve essere sottomesso individualmente, ma può essere
-svolto da un gruppo di al massimo due studenti: in questo caso nel
+svolto da un gruppo di due studenti al massimo: in questo caso nel
-progetto va indicato esplicitamente il collega.
+progetto va indicato esplicitamente il collega con cui si è collaborato.
+L'esame orale del corso, che comprende la discussione del progetto, sarà individuale: ciascuno studente
+è responsabile dell'intero progetto consegnato.
+Per poter essere valutato, il codice del client sviluppato nel progetto deve essere in grado di
+interagire senza errori con il server pubblicato in questa pagina, in una o più istanze (fino a 5)
+eseguite su host diversi o anche sullo stesso host. Il progetto deve funzionare correttamente sulle
+macchine del CLI, dove verrà testato.
+Il codice del progetto deve essere ben commentato e deve essere accompagnato da una relazione
+di 3-5 pagine che descrive l'organizzazione del codice, le strategie realizzate per il funzionamento
+del singolo client e per la collaborazione tra più client, e le politiche di sincronizzazione tra thread
+utilizzate. Inoltre occorre produrre un breve manuale d'uso che descrive i comandi necessari per
+avviare le varie istanze del client, sia su uno stesso host che su host diversi.
+Codice, relazione e manuale d'uso devono essere inviati per posta elettronica al docente del
+corso **entro le ore 24 di domenica 31 gennaio 2010**. Progetti inviati dopo tale scadenza non
+verranno ammessi, e lo studente dovrà svolgere un nuovo progetto che verrà pubblicato successivamente.
+All'orale lo studente si dovrà presentare con una copia cartacea del codice e della relazione.
+I progetti sottomessi verranno testati durante un "torneo" pubblico (la cui data verrà pubblicata nel
+mese di gennaio 2010) durante il quale ogni studente lancerà cinque istanze del proprio client che competeranno
+con tutti gli altri (eventualmente, con un meccanismo a gironi) su di un unico server attivato dai docenti.
+Naturalmente il codice usato per la gara deve essere conforme a quello consegnato, pena la nullità della prova.
+===== Suggerimenti finali =====
+L'implementazione del cliente di esempio (che sarebbe già sufficiente ai fini dell'esame) consta di poco meno di 70 righe di codice Java; si consiglia agli studenti di iniziare con un'implementazione semplice, e poi eventualmente dedicarsi al miglioramento dell'efficienza e delle strategie. Si noti che ai fini della valutazione verranno considerati primariamente:
+  * la correttezza dell'uso delle tecniche di multithreading e di comunicazione di rete;
+  * il design e l'implementazione dell'eventuale protocollo inter-client;
+  * l'efficienza della soluzione (sia in termini di uso delle risorse che di efficacia della strategia di raccolta);
+  * la qualità complessiva di scrittura del codice e della relazione.
+Nella parte orale verranno invece verificate le conoscenze teoriche su tutti gli argomenti trattati nel corso.
+Si raccomanda di verificare in anticipo il funzionamento dei client sulle macchine del Centro di Calcolo (Laboratori H-Lab e M-Lab), su cui verrà svolto il "torneo" finale dopo la data di consegna. Si raccomanda altresì di contattare i docenti, a ricevimento o per email, **prima** della consegna in caso di dubbi sull'interpretazione del testo.
+===== FAQ =====
+Per una lista aggiornata delle risposte alle domande più frequenti, clicca
+[[lpr-a/progetto#FAQ|qui]].