Suunnitteludokumentti

Transkriptio

1 Suunnitteludokumentti Populous Helsinki Ohjelmistotuotantoprojekti HELSINGIN YLIOPISTO Tietojenkäsittelytieteen laitos

2 Kurssi Ohjelmistotuotantoprojekti (6 ov) Projektiryhmä Heli Borg Markus Heinonen Ville Luolajan-Mikkola Olli Orajärvi Asiakas Petteri Hintsanen Johtoryhmä Juha Taina Turjo Tuohiniemi Kotisivu Versiohistoria Versio Päiväys Tehdyt muutokset Ensimmäinen versio Toinen versio FTR-versio Lopullinen versio

3 Sisältö i 1 Johdanto Tuotteen tausta ja tarkoitus Dokumentin rakenne Terminologia Järjestelmän yleiskuvaus Toteutus- ja toimintaympäristö Ohjelmointikielet Rajaukset Ohjelmointikäytännöt C Java Arkkitehtuurikuvaus Komponenttien väliset suhteet Suorittava kerros Kontrollikerros Käyttöliittymäkerros Luokkien väliset suhteet Luokkakaavio Verkkokommunikaatio Palvelupyynnöt Viestien koodaus Ydin-komponentti Rajapinta Enumeraattorit ICore-rajapinta IStatusCallback-rajapinta Core-luokka CoreFactory-luokka Parameters-luokka Log-luokka

4 ii Globaalit määrittelyt Pedigree-komponentti Rajapinta Enumeraattorit IPedigree-rajapinta Pedigree-luokka PedigreeFactory-luokka FamilyTree-luokka RecombTree-luokka Segment-luokka Individual-luokka Marker-komponentti Rajapinta Enumeraattorit IMarker-rajapinta Marker-luokka MarkerFactory-luokka Tekstikäyttöliittymä-komponentti Rajapinta CursesUI-luokka Palvelinkomponentti Rajapinta Server-luokka ServerStub-luokka ServerJob-luokka ServerClient-luokka Asiakaskomponentti Rajapinta ClientFrame-luokka JobControl-luokka Job-luokka ServerInfo-luokka Hakemistorakenne

5 3.10 Tiedostoformaatit pedigree chrom param server.conf Käyttöliittymä Komentorivikäyttöliittymä Ncurses Graafinen käyttöliittymä (Java Swing) Käyttötapaus 1: Sokeritaudin periytymisen tutkiminen Käyttötapaus 2: Aineistoa artikkelia varten Käyttötapaus 3: Sokeritautigeenitutkimuksen uusiminen Käyttötapaus 4: Geeniparametrien toimivuuden testaus Käyttötapaus 5: Väärät tutkimustiedot Käyttötapaus 6: Ämmänsaaren väestön kehittyminen Käyttötapaus 7: Siirtolaisten vaikutus Ämmänsaaren geeniperimään iii

6 1 Johdanto 1 Tämä suunnitteludokumentti kuvaa toteutettavan Populous -populaatiosimulaatorin teknisen toteutuksen näkökulmasta. Suunnitteludokumentti toimii järjestelmätoteutuksen ohjeena ja siinä kuvataan yksityiskohtaisesti järjestelmän arkkitehtuuri, komponentit, tietosisältö sekä toteutettavat käyttöliittymät. Suunnitteludokumentin perustana käytetään Populous-projektin määrittelydokumenttia Tuotteen tausta ja tarkoitus Populous on syksyn 2004 aikana Helsingin yliopiston Tietojenkäsittelytieteen laitoksella Ohjelmistotuotantoprojekti -kurssin puitteissa toteutettava projekti. Projektissa tuotetaan populaation kehityksen simulointiin käytettävän ohjelmiston osa. Projektin pohjana on HIIT -perustutkimusyksikössä käytössä oleva populaatiosimulaattori. Nykyisen populaatiosimulaattorin toiminnassa ilmenneet ongelmat ovat lähtökohtana Populous-projektille. Simulaattori on tehty väitöskirjatyön pohjalta ja muokattu moneen kertaan. Nyt tämän ohjelmistotuotantoprojektin avulla halutaan selkeyttää käytössä olevaa ohjelmaa. Nykyisellään tuote koostuu neljästä erillisestä osasta: genped, chrom, simco ja markertool, sekä skripteistä, joilla niiden toiminta on yhdistetty. Tässä projektissa korvataan käytössä olevan ohjelmiston kaksi ensimmäistä osaa tavoitteena prosessin suoraviivaistaminen. Lisäksi laaditaan käyttöliittymä ohjelmiston käytön helpottamiseksi. Erilaisten geenikartoitusmenetelmien ja genomin rakenteen selvittämiseen tarkoitettujen menetelmien testaamisessa simuloidut aineistot ovat välttämättömiä. Simulointiprosessin lähtökohtana on tyypillisesti yksi populaatioisolaatti. Populaatio koostuu pienestä joukosta yksilöitä, joista populaatio kasvaa annettuun loppukokoon saakka. Simulaatio jäljittelee perusjoukon geenien periytymistä jälkeläisille ja sukupolvelta toiselle laajenemisprosessin kuluessa. 1.2 Dokumentin rakenne Luvussa kaksi kuvataan projektin yhteydessä toteutettavaa järjestelmää yleisesti. Yleiskuvaukseen sisältyy järjestelmän toteutus- ja toimintaympäristön selvittäminen, käytettävien ohjelmointikielten määritteleminen ja toteutettavan ohjelman rajaus. Luku kolme kuvaa toteutettavan järjestelmän arkkitehtuurin. Se sisältää yksityiskohtaisen kuvauksen kustakin järjestelmän komponentista ja niiden välisistä suhteista. Ensimmäinen aliluku käsittelee kamponenttien välisiä suhteita ja toinen luokkien välisiä suhteita. Aliluvut kuvaavat ydin, pedigree, marker, käyttöliittymä, palvelin ja asiakaskomponenttien rajapintoja ja luokkia. Luvussa 4 kuvataan projektin yhteydessä toteutettavat käyttöliittymät, joita on kolme: komentorivikäyttöliittymä, tekstipohjainen Ncurses -käyttöliittymä ja Javan Swing -pakkausta käyttäen toteutettava graafinen käyttöliittymä.

7 2 1.3 Terminologia Dokumentissa käytetyt termit ja lyhenteet: Alipopulaatio: Populaatio voi jakautua useisiin populaatioisolaatteihin. Alipopulaatioiden välillä pariutumistodennäköisyys on pienempi kuin alipopulaation sisällä. Emäspari: Kromosomeissa sijaitsevat toisiaan vastaavat dna:n rakenneosat. (engl. basepair). Genomi: Perimä eli eliön tai solun sisältämä perinnöllinen informaatio. HIIT -perustutkimusyksikkö: Tietojenkäsittelytieteen laitoksen yhteydessä toimiva Helsingin yliopiston ja Teknillisen korkeakoulun yhteisen Helsinki Institute for Information Technology -tutkimuslaitoksen (HIIT) perustutkimusyksikkö (BRU).Yksikön keskeisiä tutkimusalueita ovat data-analyysi, adaptiivinen laskenta ja laskennallinen neurotiede. Iterointi: Iteroidaan, eli ajetaan koko simulaatiotyö samoilla parametreilla useita kertoja. Alatapaus Marker-iterointi. Loppupopulaatio: Populaatiosimulaation lopussa olevan viimeisen sukupolven edustajat muodostavat loppupopulaation. Marker-iterointi: Iteroidaan simulaatiotyötä, mutta otetaan Pedigree- tiedostot valmiina, jolloin iteroidaan ainoastaan Simcoa ja Markertoolia, ts. sukupuu pysyy staattisena. Markkeri: Kromosomissa paikka, jossa esiintyy yksilöiden välistä vaihtelua. Markertool: Valmis itsenäinen binääri, joka ottaa otoksen markereita kromosomitiedosta käyttäen myös Simcon tulostetta apunaan. Erikoistapauksessa (vanhemmat mukaan otokseen -optio) tarvitaan syötteenä lisäksi viimeisen sukupolven sukupuu ja toiseksi viimeisen sukupolven kromosomitiedosto. Ncurses: Yleisesti käytössä oleva kirjasto tekstitilaisen terminaali-ikkunan sisällön ja toimintojen määrittelyyn. Tässä projektissa NCURSES:lla on tarkoitus toteuttaa yksinkertainen ikkunamainen käyttöliittymä, jolla voidaan suorittaa rinnakkaista ajoa lukuunottamatta samat käyttötapaukset kuin Javalla toteutettava käyttöliittymä. Pedigree: Ohjelman komponentti, jonka vastuulla on sukupuun ja sen yksilöiden genotyyppien generointi (rekombinoimalla), sekä sukupolven kromosomit. Perustajajäsen: Populaation ensimmäisen sukupolven edustaja, jonka perimästä simulaatio lähtee liikkeelle. Populaatio: Joukko saman lajin yksilöitä, jotka elävät samalla alueella. Populaatioisolaatti: Eristäytynyt populaatio, jossa ei geenivaihtoa ulkopuolelta.

8 Siirtolainen: Muualta populaatioon tuleva yksilö, jonka geeniperimä poikkeaa ko. populaatioisolaatin perimästä. Simco: Valmis itsenäinen binääri, joka generoi halutun määrän SNP- tai STR-markereita (kohtia geenissä, joita voidaan tarkastetella erojen varalta). Toimii itsenäisesti. SNP -mutaatio: Lajin sisäinen, nukleotidisekvenssin tietyssä kohdassa esiintyvä vaihtelu. Muutokset tapahtuvat ainoastaan yhdessä emäsparissa.(engl. SNP = Single Nucleotide Polymorphism). STR-markkerit: Lyhyellä peräkkäisellä kromosomijaksolla toistuvat markkerit. Vaihtelu muodostuu jakson toistojen lukumäärästä. (engl. STR = Short Tandem Repeat). Tekijäinvaihto: Kromosomien risteäminen jakautumisen yhteydessä. (engl. cross-over). Tree: Pelkkä sukupuu ilman perintöainesta. 3 2 Järjestelmän yleiskuvaus Tässä luvussa kuvataan toteutettava järjestelmää. Järjestelmän liittyminen nykyisin käytössä oleviin järjestelmän osiin on esitetty kuvassa 1. Ohjelma muodostuu sisäisestä osasta, sekä siihen liittyvistä käyttöliittymistä ja se käyttää simcoa ja markertoolia ulkoisina ohjelmina. Sisäinen osa vastaa sukupuu- ja geeniaineiston käsittelystä yhdessä ulkoisten komponenttien kanssa. Ohjelmaa voi käyttää kolmella eri tavalla. Komentorivikäyttöliittymällä yhdellä komennolla voidaan ajaa koko simulaatio läpi. Tekstipohjainen curses käyttöliittymä, joka pohjautuu tekstikenttiin ja valintalistoihin, tarjoaa komentoriviä helpomman mahdollisuuden ajaa ohjelmaa tekstipohjaisessa ympäristössä. Asiakasohjelman tarkoituksena on ohjata ja hallita yhdessä tai useammassa palvelimessa ajettavia simulaatioita ja koota tulokset asiakasohjelman koneelle. Asiakasohjelmassa on graafinen käyttöliittymä. Kaikki käyttöliittymät toteutetaan englanninkielisinä. 2.1 Toteutus- ja toimintaympäristö Koska järjestelmä suunnitellaan nimenomaan Tietojenkäsittelytieteen laitoksella toimivan HIIT-perustutkimusyksikön käyttöön, se suunnitellaan toimimaan laitoksen Linuxkäyttöympäristössä. Asiakkaan ja palvelimen välinen kommunikaatio tehdään TCP/IP:llä. Palvelimeen on asetettava IP-osoitteet, joista tulevien asiakkaiden sallitaan ottaa yhteys ja suorittaa töitä, ja samoin asiakaskomponenttiin on määriteltävä käytettävien palvelimien IP-osoitteet ja portit. Palvelimelle lähetetään palvelupyyntö, jonka se välittää palvelinkoneen ytimelle.

9 4 Kuva 1: Toteutettava järjestelmä. Asiakas kyselee prosessin edistymistä tietyin väliajoin ja päivittää saadun tiedon käyttöliittymäänsä. 2.2 Ohjelmointikielet Populous ohjelmoidaan Tietojenkäsittelytieteen laitoksen Linux-ympäristössä pääasiassa C++- kielellä käyttäen sen standardikirjastoja. Poikkeuksen tähän tekevät asiakasohjelma, joka kirjoitetaan Java versiolla ja tekstikäyttöliittymä, joka toteutetaan C-kielisellä NCurses- kirjastolla. 2.3 Rajaukset Uuden populous -komponentin tulosteen on oltava markertoolin ymmärtämässä muodossa, jotta näitä voidaan käyttää yhdessä. Toisaalta myös markertoolin tulosteen on sovelluttava uuden ohjelman syötteeksi. Tällä mahdollistetaan simulaation jatkaminen ottamalla tuloksesta uusi otos seuraavan ajon perustajajäseniksi.

10 5 2.4 Ohjelmointikäytännöt Yhteisesti sovituilla ohjelmakoodin tyylisäännöillä ja ohjelmointikäytännöillä pyritään ehkäisemään tavallisimpien virheiden syntymistä ja parantamaan koodin luettavuutta. Yhteiset kaikkia ohjelmiston osia koskevat tyylisäännöt on lueteltu tässä luvussa, eri ohjelmointikieliä koskevat erityissäännöt omissa aliluvuissaan. Sisennys Sisennyksessä käytetään sarkain-merkkiä. Sarkaimen kokoa välilyönteinä ei kiinnitetä, mutta ulkoasun on oltava siisti ja yhdenmukainen neljän merkin sarkainkoolla C++ Luokkien nimeäminen Luokkien nimessä jokainen sana alkaa isolla kirjaimella, loput kirjaimet ovat pieniä, esim. CoreFactory. Lisäksi rajapintaluokkien eteen lisätään iso kirjain I, esim. ICore. Metodien nimeäminen Metodit nimetään kuten luokat. Paikallisten muuttujien nimeäminen Kaikki muuttujan nimessä olevat sanat kirjoitetaan pienellä ja ne erotetaan toisistaan merkillä _. Luokan kenttien nimeäminen Julkiset luokan kentät nimetään kuten paikalliset muuttujat. Privaattien kenttien nimeen lisätään alkuun merkki _. Lähdekooditiedostot Luokan esittely tehdään otsikkotiedostossa, jonka nimen alkuosa on sama kuin luokan nimi, mutta pienillä kirjaimilla. Tiedoston pääte on.h, esim. corefactory.h. Luokan toteutustiedosto nimetään samalla tavalla, mutta tiedoston pääte on.cpp. Yleiset luokkiin kuulumattomien lähdekooditiedostojen nimet kirjoitetaan pienillä kirjaimilla ja pääte on joko.h tai cpp. Luokan määrittelyjärjestys Luokkaa määritellessä ensimmäisenä määritellään sen julkiset ominaisuudet, ensin metodit, sitten kentät ja lopuksi konstruktorit ja destruktori. Tämän jälkeen määritellään suojatut ja privaatit metodit, näissä samoin ensin metodit ja sitten kentät. Luokan pakolliset ominaisuudet Kaikkien luokkiin on sisällytettävä vähintäänkin oletuskonstruktori, kopiokonstruktori, virtuaalinen destruktori ja sijoitusoperaatio; rajapintaluokkiin riittää virtuaalisen destruktorin määrittely ja toteutus. Mikäli jokin ominaisuus halutaan estää, voidaan se toteuttaa privaattina.

11 Metodien const-määreet Kaikissa mahdollisissa metodien ja näiden parametrien määrityksissä käytetään const-määrettä aina kun se vain on mahdollista. Mikäli parametriin ei metodin sisällä tehdä muutoksia, se määritellään const-tyyppiseksi; samoin mikäli metodi ei muuta olion kenttien arvoja, se määritellään const-tyyppiseksi. Otsikkotiedostojen käyttö Jokaiseen tiedostoon sisällytetään ainoastaan ne otsikkotiedostot, joita siinä käytetään. Samoin kaikki siinä käytetyt otsikkotiedostot on sisällytettävä, esim. sisällytyksen delegoimista toiseen otsikkotiedostoon ei tehdä. Ohjelmistoon itseensä kuuluvat otsikkotiedostot sisällytetään ensin, vasta näiden jälkeen standardikirjastoon kuuluvat. Standardikirjaston käyttö Ohjelmiston toteutuksessa käytetään C++:n standardikirjastoa, jonka kaikki luokat ovat std-nimiavaruudessa. Kaikkiin luokkien nimiin kirjoitetaan näkyviin sen täydellinen nimi, eli esim. merkkijono on std::string. Nimiavaruus Populous Kaikki luokat ja metodit toteutetaan nimiavaruuden Populous alle main-metodia lukuunottamatta Java Ohjelmiston Javalla toteutettavissa osissa käytetään Sunin julkaisemaa Code Conventions for the Java Programmin Language -dokumentin mukaista tyyliä niiltä osin kuin ne eivät ole ristiriidassa tämän projektin yleisten ohjelmointikäytäntöjen kanssa.. Ohjeet löytyvät osoitteesta 3 Arkkitehtuurikuvaus Tässä kappaleessa kuvataan toteutettavan järjestelmän arkkitehtuuri. Järjestelmän komponentit ja niiden väliset suhteet on selvitetään omissa aliluvuissaan. Arkkitehtuurikaavio on esitetty kuvassa Komponenttien väliset suhteet Ohjelmisto on jaettu hyvin itsenäisiin komponentteihin, joiden väliset rajapinnat ovat mahdollisimman yksinkertaisia. Komponenttien välinen liikenne on minimoitu. Komponenttien kutsu- ja käyttöjärjestys on määrätty ja kukin komponentti on yhteydessä hierarkiassa ylempänä olevaan komponenttiin ainoastaan callback-rajapinnan kautta, jolloin ohjelmiston suoritus etenee puumaisesti.

12 7 Kuva 2: Toteutettavan järjestelmän arkkitehtuuri. Ohjelmisto voidaan jakaa kolmeen kerrokseen: suorittava kerros (Pedigree, Marker), kontrollikerros (Ydin) ja käyttöliittymäkerros (Tekstikäyttöliittymä, Asiakas-Palvelin). Aliluvuissa on kuvattu kunkin kerroksen tehtävä Suorittava kerros Suorittavassa kerroksessa olevat komponentit Pedigree ja Marker tekevät varsinaisen simulaation eri osavaiheet. Pedigree-komponentti luo sukupuun ja siihen mahdollisesti liitettävät kromosomitiedot, ja Marker luo niiden ja Marker-komponentin sisällä luotujen markkerien pohjalta simulaation lopullisen tuloksen. Marker-komponentti tarvitsee aina syötteekseen Pedigree-komponentin tuloksen, eli näitä komponentteja ei voida yhden simulaation aikana ajaa rinnakkain. Kerroksen komponentit saavat suorittamiseen tarvittavat tiedot parametrinaan. Komponentit tiedottavat työn etenemisestä niitä kutsunutta Ydin-komponenttia callback-rajapinnan kautta.

13 Kontrollikerros Kontrollikerros hallinnoi yhden työn suorituksen. Se ajaa suorittavan kerroksen komponentit järjestyksessä Pedigree, Marker, välittää tietoa työn etenemisestä ydintä kutsuneelle komponentille callback-rajapinnan kautta, ja työn päätyttyä huolehtii, että ylimääräiset työn ohessa luodut väliaikaistiedostot tuhotaan. Ydin saa parametrinaan kaikki työn suorittamiseen tarvittavat arvot, ja tiedon siitä minkä tyyppistä työtä ollaan suorittamassa: generoidaan ainoastaan sukupuu halutuin sukupolvin ilman kromosomeja (#1), generoidaa sukupuut ja siihen kromosomit (#2), suoritetaan simulaatio kokonaisuudessaan (#3) tai suoritetaan ainoastaan Marker parametrina annetulla sukupuulla ja kromosomidatalla, mahdollisesti iteroiden (#4). Yksinkertaisimmassa tapauksessa #1 suoritetaan ainoastaan Pedigree, ja tästäkin ainoastaan ensimmäinen puoli. Tuloksena saadaan pelkkä sukupuu ilman kromosomitietoja. Tapaus #2:ssa suoritetaan Pedigree kokonaisuudessaan. Tulokseksi saadaan sukupuu ja kromosomitiedot. Yleisimmässä tapauksessa #3 suoritetaan sekä Pedigree että Marker kertaalleen alusta loppuun. Tulokseksi saadaan markertool-ohjelman tuloste. Välituloksien säilytys määritellään parametreissa. Tapaus #4:ssä suoritetaan ainoastaan Marker-komponentti. Tällöin Pedigree-komponentin generoimat sukupuu- ja kromosomitiedostot annetaan parametrina, jolloin Pedigree-vaihe voidaan ohittaa. Myös iterointi on mahdolista, jolloin Marker suoritetaan samoilla parametreilla haluttu määrä kertoja, säilyttäen jokaisen ajokerran tulokset omassa tiedostossaan Käyttöliittymäkerros Ohjelmaan rakennetaan kolme käyttöliittymää: teksti-, komentorivi- sekä Javapohjainen Swing-käyttöliittymä. Komentorivikäyttöliittymä ei ole interaktiivinen ja on tarkoitettu ohjelman tehokkaaseen laajentamiseen ja käyttöön. Swing-käyttöliittymä on pääasiallinen käyttöliittymä, ja se mahdollistaa etäkäytön. Tekstikäyttöliittymä rakennetaan toissijaiseksi käyttöliittymäksi. Tekstikäyttöliittymästä tulee minimalistinen ja minimalistisen interaktiivinen. Ohjelmasta pystytään ainoastaan terminoimaan käynnissä oleva työ sekä päivittämään sen statustietoa näytölle, mutta ei muuta, ts. käyttöliittymä on lukkiutunut suorituksen aikana. Ajo terminoidaan control-c:llä, jolle rakennetaan erityinen käsittelijä, joka keskeyttää työn suorituksen siististi. Ohjelma ei siis tällöin kaadu tai sammu suoraan. Palvelinkomponenttia varten luodaan oma prosessi lyhyen vasteajan takaamiseksi. Palvelinprosessissa palvelin ottaa vastaan uusia yhteydenottopyyntöjä asiakkailta, ylläpitää töiden ja asiakkaiden listaa, ja käynnistää uusien töiden ajoja tarpeen mukaan. Palvelinja ydinprosessin välinen kommunikaatio tapahtuu putkilla, joilla ydin-prosessin päässä palvelinkomponenttiin kuuluva olio välittää palvelimelta tulleet viestit ytimen palvelupyynnöiksi ja ytimeltä tulevat tilatiedot palvelinprosessille. Ytimelle prosessiraja ei näy,

14 vaan sen kannalta rajapinta on sama kuin ytimen ja esim. tekstikäyttöliittymän rajapinta. Asiakkaan ja palvelimen välinen kommunikaatio tehdään TCP/IP-protokollaa käyttäen. Palvelimeen on asetettava IP-osoitteet, joista tulevien asiakkaiden sallitaan ottaa yhteys ja suorittaa töitä, ja samoin asiakaskomponenttiin on määriteltävä käytettävien palvelimien IP-osoitteet ja portit. Asiakas on komponenteista aina aktiivinen osapuoli, eikä palvelin lähetä asiakkaalle mitään ilman asiakkaan tekemää palvelupyyntöä Luokkien väliset suhteet Tässä luvussa kuvataan luokkien välisiä suhteita. Luokkakaaviossa esitetään kaikki toteutettavan järjestelmän luokat. Lisäksi kuvataan luokkien välistä verkkokommunikaatiota ja palvelupyyntöjä sekä viestien koodausta tarkemmin Luokkakaavio Koko järjestelmän luokkakaavio on esitetty kuvassa 3. Luokkakaaviossa ovat ainoastaan järjestelmän luokat, eli siitä puuttuvat globaalit main- ja sig_handler-funktiot ja globaali muuttuja process_state. Nämä kuuluvat loogisesti Ydin-komponenttiin, ja main-funktio voi kutsua joko Core-, CursesUI- tai Server-luokkaa Verkkokommunikaatio Asiakkaan ja palvelimen välinen yhteys toteutetaan TCP/IP-protokollaa käyttäen. Tässä luvussa listataan palvelimen asiakkailleen tarjoamat palvelut sekä kuvataan niiden suorittamiseen käytettävä protokolla. Asiakasohjelmaan määritellään käytettävien palvelimien IP-osoitteet ja portit. Samaa palvelinta voi yhtä aikaa käyttää useampikin asiakas, mutta töitä suoritetaan rinnakkain vain korkeintaan palvelimessa määritelty määrä. Suoritusta odottavat työt palvelin asettaa jonoon, josta niitä haetaan suoritettavaksi saapumisjärjestyksessä. Kaikissa palvelupyynnöissä lähettää asiakas palvelimelle viestin, johon palvelin vastaa välittömästi. Palvelupyyntöjen kuvaukset ovat muodossa, jossa ensimmäisenä on palvelun nimi, sen jälkeen palvelimelle lähetettävät parametrit ja kaksoispisteen jälkeen palvelimelta saadut tulokset Palvelupyynnöt QUEUELEN : <int> Tällä palvelupyynnöllä asiakas voi selvittää palvelimen kuormitusasteen. Palautettu arvo on jonossa tai suorituksessa olevien töiden lukumäärä. Mikäli jonossa ei ole paikkoja vapaana eikä enempiä töitä voide heti käynnistää suoritettavaksi, on paluuarvo -1.

15 10 Kuva 3: Toteutettavan järjestelmän luokkakaavio START <parametrit> : <ID> Työ luodaan tällä palvelupyynnöllä. Paluuarvona asiakas saa avaimen, jolla se voi viitata myöhemmissä palvelupyynnöissä oikeaan työhön. Työ käynnistetään heti kun palvelimella vapautuu paikka. Virhetilanteessa paluuarvo on negatiivinen. QUEUEPOS <ID> : <int> Mikäli parametrina annettu työ on ajossa, annetaan paluuarvona 0. Jos se on vielä jonossa odottamassa ajoa, annetaan työn sijainti jonossa. Mikäli työtä ei löydy, palautetaan -1. READY <ID> : <int> Tällä palvelupyynnöllä asiakkaan on aika ajoin tarkistettava työn edistyminen. Jos työtä ei olla vielä aloitettu, on paluuarvona 0. Valmiin työn kohdalla paluuarvo on 100, ja mikäli työn suoritus on vielä kesken, on paluuarvo jokin kokonaisluku välillä Virhetilanteessa paluuarvo on -1. Onnistuneen suorituksen aikana palautettava arvo ei ole koskaan pienempi kuin aikaisemmalla kerralla

16 saatu arvo. Paluuarvoa voidaan siten käyttää käyttöliittymässä suoraan prosenttiarvona työn suorituksen etenemisestä. RESULTS <ID> : <tulokset> Kun palvelupyyntö READY on palauttanut arvon 100, voidaan tällä palvelupyynnöllä hakea työn tulokset. Kun tulokset on toimitettu, poistetaan tulokset palvelimelta. Samoin asiakkaan ja palvelimen välisen yhteyden katkeaminen poistaa mahdolliset tulokset. KILL <ID> : <boolean> Työn voi keskeyttää tai perua tällä palvelupyynnöllä. Jos työtä ei ole vielä suoritettu, se joko keskeytetään ja kaikki sen väliaikaistiedot tuhotaan tai se poistetaan jonosta. Valmistuneen työn kohdalla tulokset poistetaan. STATUS : <tietoa> Palauttaa yleistä tilatietoa työn vaiheesta, käytetään ainoastaan virheiden etsimiseen. Palautettu arvo on kuvaava merkkijono, jonka varsinaista muotoa ei määritellä Viestien koodaus Palvelupyyntöjen viestit koodataan seuraavan määritelmän mukaan. Määritelmässä käytetyt symbolit on merkattu <> väliin. Jokaisen symbolin määritelmässä ::= oikealla puolella oleva arvo on symbolin sisältö, vaihtoehtoiset sisällöt on eritelty merkillä. Samantyyppisen symbolin moninkertaa merkitään merkillä *, jolloin sitä edeltävää symbolia voi mielivaltainen määrä. Jokainen symboli voidaan lukea auki siten, että kaikki sen määritelmässä olevat symbolit korvataan niiden määritelmällä, ja toistaen sama kaikille symboleille kunnes jäljellä on vain vakioita tai selkokielinen selitys sisällöstä. #-merkin jälkeen oleva teksti on vapaamuotoinen tekstiselitys, jolla tarkennetaan symbolin merkitystä ja luonnetta. Merkkivakiot on merkitty yksinkertaisten lainausmerkkien väliin ja ovat tyypiltään <char>. <request> ::= <req_queuelen> <req_start> <req_queuepos> <req_ready> <req_results> <req_kill> <req_status> <req_queuelen> ::= L <req_start> ::= S <params> <req_queuepos> ::= P <id> <req_ready> ::= R <id> <req_results> ::= G <id> <req_kill> ::= K <id> <req_status> ::= D <id> <reply> ::= <rep_queuelen> <rep_start> <rep_queuepos> <rep_ready> <rep_results> <req_kill> <req_status>

17 12 <rep_queuelen> ::= L <int32> <rep_start> ::= S <id> <rep_queuepos> ::= P <int32> <rep_ready> ::= R <int32> <rep_results> ::= G <results> <rep_kill> ::= K <boolean> <rep_status> ::= D <data> <params> ::= <data> # data sisältää parametrilistan parametritiedoston muodossa (kts ) <results> ::= <ldata> # data sisältää tiedostot koodattuna samoin kuin parametritiedostossa (kts ) <data> ::= <length> <char>* <length> ::= <uint32> <id> ::= <uint32> <int32> ::= 32-bittinen etumerkillinen kokonaisluku, big-endian-muodossa <uint32> ::= 32-bittinen etumerkitön kokonaisluku, big-endian-muodossa <char> ::= 8-bittinen merkki ASCII-merkistössä <boolean> ::= 8 bittiä; = true, = false Esimerkiksi palvelupyynnön READY ensimmäinen viesti olisi merkki R ja 32- bittinen etumerkitön kokonaisluku, jonka arvo on työn ID; yhteensä 40 bittiä. (Luetaan määritelmästä: <request> -> <req_ready> -> char- R <id> -> char- R <uint32> -> char- R 32-bittinen etumerkitön kokonaisluku, big-endian-muodossa.) Vastaava paluuviesti olisi merkki R ja 32-bittinen etumerkillinen kokonaisluku, jonka arvo on työn edistymistä kuvaava luku; samoin 40 bittiä. 3.3 Ydin-komponentti Ydin on koko ohjelman toimintaa koordinoiva ja ohjaava komponentti. Ydin saa viestejä joko suoraan käyttäjältä (komentorivikäyttöliittymä), tekstipohjaiselta käyttöliittymältä tai Palvelin-komponentilta, jota asiakasohjelma käyttää verkon yli.

18 13 Kuva 4: Ydin-komponentin luokat. Ydin toimii välikerroksena käyttäjän ja simulaation suorittavien komponenttien välissä. Ydin ohjaa Pedigree- ja Marker-komponentin käyttöä, sekä välittää tietoa käyttäjälle käyttöliittymän kautta ja poistaa väliaikaisia tiedostoja ja ylläpitää tiedon välitystä. Ydin-komponenttiin on myös sisällytetty globaalit luokat Parameters ja Log, sekä kaikki

19 mahdolliset globaalit funktiot ja muuttujat. Perusteena tälle on, että Ydin-komponentin katsotaan olevan keskeisin osa sovellusta. Ytimen luokat ja näiden väliset suhteet on esitetty kuvassa Rajapinta Ydin tarjoaa palveluita tekstikäyttöliittymälle ja palvelimelle. Ydin sisältää simulaation ajojen hallinnan, koordinoinnin, lokin, virhetilanteiden hallinnan ja delegoinnin ohjelman sisällä sekä tulosten ja tulosteiden ohjaamisen käyttäjälle. Ytimen on tarkoitus piilottaa mahdollisimman paljon populaatiosimulaatioteknisistä asioista ja tarjota keskitetysti esim. parametrien parseroinnin, validoinnin (Parameters-luokka) ja simulaatiokomponenttien kutsun (Core-luokka). Tyypillisessä simulaatiokäyttötapauksessa käyttäjä antaa käyttöliittymän kautta halutut parametrit. Käyttöliittymä syöttää parametrit Parameters-olioon, joka annetaan ytimelle. Parameters-luokka parsii syötteet ja tarkistaa niiden arvoalueet ja eheyden. Ydin määrittää parametrien pohjalta simulaatiotyön. Tämän takia ydin tarjoaa käyttöliittymille hyvin pelkistetyn rajapinnan, joka koostuu pääasiassa parametrien vastaanottamisesta. Näin käyttöliittymät voidaan erottaa simulaatiosta ja sen toteutuksesta mahdollisimman tehokkaasti. int RunSimulation(TSimType type, Parameters params) Luovutetaan parametrijoukko ytimelle suoritusta varten. Parametri type määrittelee minkä tyyppinen simulaatio halutaan suorittaa. Määritellään rajapinnassa ICore. int main(int argc, char *argv[]) Ohjelmiston globaali pääfunktio. Tätä kutsutaan ensimmäiseksi kun ohjelma käynnistetään komentoriviltä. Tunnistaa parametreista halutaanko ohjelmaa ajaa palvelimena, tekstikäyttöliittymänä vai suoraan suorittaa simulaatio, ja käynnistää sen mukaisen komponentin, josta ohjelman suoritus varsinaisesti alkaa. void Update(TStatus status) Callback-metodi, jolla Pedigree- ja Marker-komponentit lähettävät tietoa edistymisestään. Määritellään rajapinnassa IStatusCallback Enumeraattorit TStatus Kuvaa simulaatiotyön tilaa. Mahdolliset arvot ovat: INIT = työtä ei vielä aloitettu, TREE = sukupuu luotu, PEDIGREE = kromosomit luotu sukupuuhun, MARKER = markkerit luotu, READY = työ valmis

20 15 Koodi Selitys -1 Määrittelemätön virhe -2 Tiedoston lukuvirhe (käyttöoikeus) -3 Tiedoston lukuvirhe (muu) -4 Tiedoston kirjoitusvirhe (käyttöoikeus) -5 Tiedoston kirjoitusvirhe (muu) Taulukko 1: ICore::RunSimulation()-virhekoodit TProcessState Kuvaa prosessin tilaa. Mahdolliset arvot ovat: INIT = alkutila, FORK = prosessin haarautuminen käynnissä, SERVER = palvelinprosessi, NCURSES = tekstikäyttöliittymä, CORE = prosessi suorittaa simulaatiota TSimType Kuvaa simulaation tyyppiä. Mahdolliset arvot ovat: FULL = täysi ajo alusta loppuun, TREE = luodaan pelkkä sukupuu Pedigree-komponentissa, PEDIGREE = ajetaan vain Pedigree-komponentti, PROCESS = suoritetaan pelkkä Marker-komponentti valmiille sukupuulle ICore-rajapinta ICore on ydinkomponentin kutsurajapinta. Metodit public int RunSimulation(TSimType type, Parameters &params) Metodilla käynnistetään simulaation suoritus. Onnistuneen suorituksen yhteydessä paluuarvo on 0, virhetilanteessa negatiivinen. Virhekoodit on lueteltu taulukossa IStatusCallback-rajapinta IStatusCallback luo rajapinnan, jolla välitetään tietoa työn edistymisestä kutsuneelle taholle. Metodit public virtual void Update(TStatus status) Callback-metodilla, jolla kontrolli voidaan siirtää hetkeksi työn suorituksesta hierarkiassa ylemmälle kerrokselle. Parametri status on enumeraattorityyppiä TStatus.

21 Core-luokka Core on Ydin-komponentin pääluokka. Core hoitaa töiden koordinoinnin ja jakaa annettujen parametrien mukaan tehtävät Pedigree- ja Marker- komponenteille. Metodit public int RunSimulation(TSimType type, Parameters &params) Ajaa simulaation. Saa syötteenään valmiin ja tarkistetun Parameters- olion. Parametri type on enumeraattorityyppiä TSimType ja määrittelee simulaation tyypin. antaen CoreFactory-luokka CoreFactory on tehdasolio, jolla luodaan ICore-tyyppisiä olioita. Metodit public static ICore* Construct() Luo ICore-tyyppisen olion. Varsinaisen toteuttavan luokan valinta tehdään metodin sisällä. Virhetilanteessa palautetun osoittimen arvo on Parameters-luokka Parameters-luokka kapseloi ohjelman parametrit. Se luodaan ja täytetään käyttöliittymätasolla ja annetaan ytimelle simulaation suoritusta varten. Komentoriviltä käytettäessä käyttöliittymätaso on ydin itse, jolloin se kontruoidaan siellä. Se ei varsinaisesti kuulu Ydin-komponenttiin, vaan kulkee suorituksen mukana komponentista toiseen. Parameters-olion voi konstruoida joko käyttämällä kontruktoria, joka saa syötteenään char-merkkijonotaulukossa kaikki parametrit (komentoriviltä ja palvelimesta) tai attribuutit voi täyttää itse (tekstikäyttöliittymä). Luonnin jälkeen tulee kutsua Check-metodia, joka tarkistaa parametri-olion parametrit. Parameters-oliossa kaikilla kentillä on asetettuna arvo, jota käytetään. Oletusarvoja käytettäessä on Parameters-oliota luovan metodin tehtävä asettaa nämä arvot oikein. Metodit public int Check(TSimType type) Tarkistaa parametrina saamansa tyypin perusteella siihen liittyvien parametrien arvojen oikeellisuuden ja funktionaalisen eheyden. Metodin paluuarvo on onnistuneella suorituksella 0 ja virhetilanteessa negatiivinen. Virhekoodit on listattu taulukossa 2.

22 17 Koodi Selitys -1 Määrittelemätön virhe -2 Arvoaluevirhe jossakin parametrissa -3 Kaikkia vaadittuja parametreja ei asetettu -4 Ristiriita parametreissa Taulukko 2: Parameters::Check()-virhekoodit Metodin parametri type on enumeraattorityyppiä TSimType. public Parameters(char **argv) Konstruktori, jonka paramtrina saa ohjelmiston komentoriviparametrit ilman ensimmäistä, ohjelman ajotiedoston sisältävää kenttää. Konstruktori pyrkii löytämään merkkijonoista kaikki mahdolliset määritellyt parametrit ja asettamaan arvonsa sen mukaisesti. Virhetilanteissa osa arvoista jää asettamatta, ja oliota luovan onkin kutsuttava Check-metodia vielä tämän jälkeen varmistaakseen luonnin onnistumisen ja että kaikki tarvittavat parametrit oli määritelty. Attribuutit Parameters-luokan attribuutit on listattu taulukossa 3. Parametrit tarkistetaan Check-metdissa simulaatiomoodin mukaan. Moodit: 1 = TREE 2 = PEDIGREE 3 = FULL 4 = MARKER Kustakin parametrista on mainittu, tarkistetaanko se tietyssä moodissa. Vain yhden moodin parametrit tarkistetaan, muista ei välitetä Log-luokka Log on ohjelmiston lokitiedostoon kirjoittamiseen tarkoitettu luokka. Jokaisella lokirivillä on rivin tyyppi, jotka ovat vakavimmasta vähiten vakavaan Critical, Error, Info ja Debug, sekä vapaamuotoinen, mutta yksirivinen tekstiselitys. Lokitiedosto kirjoitetaan hakemistoon, josta ohjelmisto on suoritettu. Log on Singleton-tyyppinen olio, josta luodaan tasan yksi ilmentymä prosessia kohti. Metodit public static Log& GetInstance(bool debug = false) Palauttaa Log-olion. Luo tarvittaessa uuden Log-olion. Debug-tilan voi asettaa päälle ainoastaan ensimmäisellä kutsukerralla, eikä sitä voi kesken ohjelman suorituksen asettaa pois päältä.

23 18 Tyyppi Muuttuja (1,2,3,4 = Sallittu arvoalue Tarkistushuomioita pakollinen) bool savetrees bool savepedigrees string loadpedigree (4) Tarkistetaan, että tiedosto on olemassa. bool debug int founders (123) 2-n int lastgensize (123) 2-n int generations (123) 1-n int iterations 1-n Vakio-arvo 1. bool pedigreeonce Ei vaikutusta, jos iterations 1 vector<int> savegenerations 1-generations int subpops 1-n Vakio-arvo 1. Tulee antaa kaikki 3 subpop- parametria. vector<int> subpopsizes 2-founders Määrä täsmättävä edelliseen. double[][] subpopmigrations , sum=1.0 Sekä korkeus että leveys oltava subpops. Joka rivin summa 1.0. Ei korjata taulukkoa, jos siinä virheitä. double diseasemutfreq (34) double minminorallelefreq (34) double prevalence (34) double penetrance (34) int markers (34) 1-n int sampletype (34) 1-4 bool markermap string markermapfile Huomoidaan vain jos edellinen true. bool report string reportfile Huomioidaan vain jos edellinen true. string simcofile string chromfile bool parentsinresult string treefile string parpedigreefile bool allowsiblings Huomioimatta jos ei parents ei asetettu. int samplesize (34) 0-n int effectivepopsize 2-n (34) int chromlength (34) 2-n double recombrate (34) double snprate (34) Ei STR ja SNP:tä yhtäaikaa. Jos ovat molemmat -> virhe, ei korjata. string strfile Tarkistetaan olemassaolo. Taulukko 3: Parameters muuttujat

24 19 public void LogCritical(string msg) Lisää lokitiedostoon parametrina saadun viestin kriittinen-statuksella. public void LogError(string msg) Lisää lokitiedostoon parametrina saadun viestin virhe-statuksella. public void LogInfo(string msg) Lisää lokitiedostoon parametrina saadun viestin info-statuksella. public void LogDebug(string msg) Lisää lokitiedostoon parametrina saadun viestin debug-statuksella. Rivi lisätään vain mikäli attribuutti debug on asetettu arvoon true. Attribuutit private Log instance Sisäinen olio, jonka kaikki luokkaa käyttävät jakavat. Tuhotaan vasta ohjelman suorituksen päättyessä. private bool debug Määrittelee kirjoitetaanko debug-rivit tiedostoon. private string logfile Lokitiedosto, johon lokirivit kirjoitetaan Globaalit määrittelyt Globaalit funktiot ja muuttujat eivät kuulu mihinkään luokkaan, vaan näkyvät kaikille niitä käyttäville sellaisenaan. Funktiot int main(char* args[]) Main-metodi. Metodi ajetaan ensimmäisenä kun ohjelma käynnistetään komentoriviltä. Metodissa tehdään yksinkertaistettu parametrien tarkistus, jonka pohjalta se joko käynnistää palvelimen (parametri start-server), käynnistää tekstikäyttöliittymän (ei parametreja) tai aloittaa simulaation suorituksen (kaikissa muissa tapauksissa). Lopullinen simulaation parametrien tarkistus tehdään Parameters-luokan sisäisessä metodissa Check. Parametrien konstruointiin tarjotaan Parameters-luokan konstruktoria. void sig_handler(int sig) Signaalinkäsittelijä, jossa määritellään mitä tehdään kun prosessi saa UNIX- signaalin. Käyttäytyminen riippuu suurelta osin globaalista muuttujasta process_state.

25 20 Muuttujat TProcessState process_state Muuttujalla määritellään missä tilassa ja minkä tyyppinen senhetkinen prosessi on. Tällä kontrolloidaan lähinnä signaalinkäsittelijän toimintaa, koska esim. palvelimen, käynnissä olevan työn ja tekstikäyttöliittymän yhteydessä samakin signaali pitää voida tulkita eri tavalla. Muuttuja on enumeraattori-tyyppiä TProcessState. 3.4 Pedigree-komponentti Kuva 5: Pedigree-komponentin luokat. Pedigree korvaa ja yhdistää vanhan järjestelmän genpedin ja chromin. Pedigree tuottaa halutut sukupuutiedostot (iteration_pedigree_generation) ja kromosomitiedostot sukupolvittain (iteration_chrom_generation). Vakiona mitään pedigree-komponentin tulosteita ei säilytetä simulaation ajon jälkeen, eli sitten kun markertool on käynyt ne läpi. Tulosteiden poistoa ei toteuteta Pedigreehen vaan

26 21 Koodi Selitys -1 Määrittelemätön virhe -2 Tiedoston lukuvirhe (käyttöoikeus) -3 Tiedoston lukuvirhe (muu) -4 Tiedoston kirjoitusvirhe (käyttöoikeus) -5 Tiedoston lukuvirhe (muu) Taulukko 4: IPedigree::GeneratePedigree()-virhekoodit se tapahtuu muualla. Option takana on mahdollisuus tallettaa käytetyt sukupuu- ja kromosomitiedostot, sekä mahdollisuus generoida ja säilyttää ylimääräisiä sukupolvitiedostoja. Pedigree-komponentin luokat ja näiden väliset suhteet on esitetty kuvassa Rajapinta Pedigree-komponentin rajapinta tarjoaa yhden metodin sukupuun ja kromosomien luomista varten. Se mitä kullakin suorituskerralla luodaan määräytyy parametreista. int GeneratePedigree(TPedigreeType type, Parameters& params) Generoidaan parametreissä määritellyt asiat. Ensimmäisellä parametrilla voidaan jättää kromosomit generoimatta. TPedigreeType on enumeraattori, joka kertoo suorituksen tyypin Enumeraattorit TPedigreeType Kuvaa Pedigree-komponentin suorituksen tyypin. Mahdolliset arvot ovat: FULL = täysi ajo, TREE = vain sukupuu IPedigree-rajapinta IPedigree on Pedigree-luokan rajapinta ytimelle. Metodit virtual int GeneratePedigree(TPedigreeType, Parameters&) Core-luokalle näkyvä rajapintametodi. Toteutus aliluokassa. Palauttaa onnistuessaan arvon 0, virhetilanteessa negatiivisen arvon. Virhekoodit on listattu taulukossa 4.

27 Pedigree-luokka Pedigree luo sukupuut ja vastaa niiden tallennuksesta. Metodit public int GeneratePedigree(TPedigreeType, Parameters&) GeneratePedigree on implementaatio rajapintaluokan metodille. Metodi ottaa parametriksi TPedigreeType-enumin ja Parameters-luokan, jotka kertovat missä moodissa ohjelmaa ajetaan ja sisältävät tarvittavat parametrit ajoa varten. Metodi luo luokan sisäiset oliot, FamilyTree ja RecombTree, joissa tapahtuu varsinainen sukupuun ja kromosomien prosessointi. Töiden välillä metodi palauttaa tilatietoa IStatusCallbackluokan Update(...)-metodin kautta. Attribuutit private FamilyTree thefamilytree Pelkkä sukupuu private RecombTree therecombtree Rekombinaatiot sisältävä luokka PedigreeFactory-luokka PedigreeFactory on staattinen tehdasluokka, joka luo instanssin Pedigree- luokasta ja palauttaa osoittimen siihen. Metodit public static IPedigree* Construct() Metodi luo Pedigree-instanssin ja palauttaa sen osoittimen kutsujalle FamilyTree-luokka FamilyTree on sukupuun sisältävä luokka. Kaikki sukupuun prosessointi, tallennus ja tulostus tapahtuu tässä luokassa. Metodit public int Create(Parameters&) Luo parametreissa määritellyn kaltaisen sukupuun.

28 23 public int WriteToDisk() Kirjoittaa sukupuun sisällön tiedostoon sukupolvi kerrallaan. public int WriteToScreen() Tulostaa sukupuun tiedot ruudulle. Attribuutit private vector<individual> treedata Tietorakenne sukupuuta varten RecombTree-luokka RecombTree on luokka, joka sisältää tiedot kromosomeista ja rekombinaatioista. Metodit public int Create(FamilyTree&, Parameters&) Luo kromosomidatan sukupuun ja parametrien perusteella. public int WriteToDisk() Kirjoittaa kromosomidatan tiedostoon. public int WriteToScreen() Tulostaa kromosomidatan ruudulle. Attribuutit private vector<segment> recombdata Tietorakenne rekombinaatiotietoa varten Segment-luokka Segment on säiliöluokka kromosomidatalle. Luokka on RecombTree-luokan apuluokka. Attribuutit Attribuutit kiinnitetään toteutusvaiheessa.

29 Individual-luokka Individual on säiliöluokka yksilötiedolle. Luokka on FamilyTree-luokan apuluokka. Attribuutit Attribuutit kiinnitetään toteutusvaiheessa. 3.5 Marker-komponentti Kuva 6: Marker-komponentin luokat. Marker on yhteinen rajapintakomponentti markertoolille ja simcolle. Marker toimii em. ohjelmien ajurina, joka virtaviivaistaa niiden käyttöä ytimelle ja mahdollistaa ohjelman laajennettavuuden. Marker-komponentin luokat ja näiden väliset suhteet on esitetty kuvassa Rajapinta Marker-komponentin rajapinta sisältää yhden metodin, jonka kautta käytetään simco- ja markertool-komponentteja. Yksityiskohdat sisältyvät parametreihin.

30 25 Koodi Selitys -1 Määrittelemätön virhe -2 Tiedoston lukuvirhe (käyttöoikeus) -3 Tiedoston lukuvirhe (muu) -4 Tiedoston kirjoitusvirhe (käyttöoikeus) -5 Tiedoston lukuvirhe (muu) Taulukko 5: IMarker::Process()-virhekoodit int Process(TMarkerType type, Parameters params&) Ajetaan Simco ja Markertool halutuin parametrein Enumeraattorit TMarkerType Kuvaa Marker-komponentin suorituksen tyypin. Mahdolliset arvot ovat: MARKER_NORMAL = normaali ajo, MARKER_WPAR = vanhemmat mukana otoksessa IMarker-rajapinta IMarker on Marker-luokan rajapinta ytimelle. Metodit public int Process(TMarkerType type, Parameters &params) Core-luokalle näkyvä rajapintametodi. Toteutus aliluokassa. Onnistuessaan metodi palauttaa arvon 0, virhetilanteessa negatiivisen arvon. Virhekoodit on lueteltu taulukossa Marker-luokka Marker-luokka toimii rajapintana Ytimen ja Simcon sekä Markertoolin välillä. Metodit public int Process(TMarkerType type, Parameters &params) Luokan ainoa metodi. TMarkerType-enumeraattori määrittelee ajotavan, Parametersluokka sisältää parametrit simcolle ja markertoolille. Ensin ajetaan Simco ja sen jälkeen Markertool, molemmat ajetaan aina. Metodi käynnistää ulkoiset ohjelmat uuteen prosessiin ja jää odottamaan lopetussignaalia. Parametrit on validoitu jo ennen

31 ulkoisten ohjelmien ajamista, mutta jos virhetilanne kuitenkin syntyy, palautetaan negatiivinen arvo. Onnistuessaan metodi palauttaa arvon 0. Töiden välillä metodi palauttaa tilatietoa IStatusCallback-luokan Update(...)- metodin kautta MarkerFactory-luokka MarkerFactory on staattinen tehdasluokka, joka luo instanssin Marker- luokasta ja palauttaa osoittimen siihen. Metodit public static IMarker* Construct() Metodi luo Marker-instanssin ja palauttaa sen osoittimen kutsujalle. 3.6 Tekstikäyttöliittymä-komponentti Kuva 7: Tekstikäyttöliittymäkomponentin luokat. Tekstikäyttöliittymä pohjautuu ncurses-kirjastoon. Käyttäjä määrittelee parametrit, joiden perusteella komponentti kutsuu ydintä. Ydin tarjoaa tietoa simulaation etenemisestä, joka näytetään käyttäjälle. Lopputuloksia ei visualisoida, ainoastaan talletetaan annettuun tai vakiohakemistoon. Tekstikäyttöliittymäkomponentin luokat on esitetty kuvassa Rajapinta void Update(TStatus status) Metodi, jonka avulla päivitetään ruudulle tilatietoa ohjelman edistymisestä aina jonkin osasuorituksen valmistuttua.

32 27 void StartUI() Käynnistää tekstikäyttöliittymän CursesUI-luokka CursesUI on luokka, joka vastaa kaikista tekstikäyttöliittymän toiminnoista. Käyttöliittymä rakennetaan käyttäen ncurses-kirjaston tarjoamia toimintoja. Simulaation käynnistyttyä tilatietoa päivitetään IStatusCallbackin Update(...)-metodin kautta. Koska käyttöliittymälle ei luoda omaa prosessia, simulaation aikana käyttäjälle ei tarjota muita toimintoja kuin simulaation keskeyttäminen. Metodit void Update(TStatus status) Ytimelle tarjottava metodi, jolla voidaan päivittää käyttöliittymää laskennan kuluessa tarjoamalla käyttöliittymälle kontrolli pieneksi hetkeksi. Määritellään rajapinnassa IStatusCallback. void StartUI() Käynnistää tekstikäyttöliittymän. Ydin kutsuu tätä metodia main-metodistaan, jos ohjelmisto käynnistetään ilman komentoriviparametreja. Attribuutit Kiinnitetään toteutusvaiheessa 3.7 Palvelinkomponentti Komentoriviltä käynnistettävä palvelin ottaa vastaan palvelupyyntöjä asetetusta portista. Lisäksi palvelimelle määritellään IP-osoitteet, joista palvelupyynnöt tulee sallia; muualta tulleet palvelupyynnöt hylätään. Palvelin pitää kirjaa asiakkaista ja suorittaa saatuja töitä ytimellä. Useampi kuin yksi asiakas voi olla yhtäaikaa yhteydessä palvelimeen, jolloin ruuhkautumisen välttämiseksi palvelimen on osattava tarvittaessa laittaa töitä jonoon odottamaan suoritusvuoroaan. Palvelimeen asetetaan kerrallaan suorituksessa olevien töiden suurin sallittu lukumäärä. Palvelin ei kommunikoi aktiivisesti asiakkaan suuntaan, vaan ainoastaan vastaa palvelupyyntöihin. Sen sijaan ytimen suuntaan palvelinkomponentti on aktiivinen osapuoli. Mikäli palvelin sammutetaan tai siellä tapahtuu muu kriittinen virhe, joka aiheuttaa sen sammuttamisen, suljetaan asiakkaan ja palvelimen välinen yhteys. Erillistä virheilmoitusta asiakkaalle ei lähetetä. Palvelinkomponentin luokat on esitetty kuvassa 8.

33 28 Kuva 8: Palvelinkomponentin luokat Rajapinta void StartServer() Ytimelle tarjottava metodi, joka käynnistää palvelimen. Portin voi asettaa asetustiedostossa, samoin hyväksyttävät verkko-osoitteet Server-luokka Server on palvelinkomponentin pääluokka. Luokassa hallitaan töiden suoritusta ja käsitellään asiakkaiden tekemät palvelupyynnöt. Luokassa on sisäiset tietovarastot töiden ja asiakkaiden tietoja varten. Metodit public void StartServer() Käynnistää palvelimen. Lukee asetuksensa palvelimen asetustiedostosta, siirtää prosessin tausta-ajoksi ja ryhtyy ottamaan vastaan palvelupyyntöjä asiakkailta. Metodin suoritus päättyy kun palvelin sammutetaan. private int LoadConfig() Lataa palvelimen asetukset asetustiedostosta. Palauttaa onnistuessaan arvon 0, virhetilanteissa -1. Attribuutit private int serverfd Putki, lähetetään viestejä ydinprosessille.

34 29 private int stubfd Putki, jolla vastaanotetaan viestejä ydinprosessilta ServerStub-luokka ServerStub on apuluokka, jonka kautta palvelinkomponentti kommunikoi ytimen kanssa. Ydin suoritetaan aina omassa prosessissaan, jolloin palvelimen ja ytimen välinen kommunikaatio hoidetaan putken avulla. ServerStub-luokka peittää ytimeltä tämän ja tarjoaa suoran oliorajapinnan. Luokka toteuttaa Ydinkomponentin rajapinnan IStatusCallback. Metodit void Update(TStatus status) Ytimelle tarjottava metodi, jolla työn tilasta voidaan lähettää välitietoa palvelimelle ja sitä kautta asiakkaalle. Saatu tilatieto lähetetään eteenpäin putkea pitkin palvelimelle, jonka jälkeen ohjelman kontrolli palaa metodin kutsujalle. Attribuutit private int serverfd Putki, vastaanotetaan viestejä palvelinprosessilta private int stubfd Putki, jolla lähetetään viestejä palvelinprosessille ServerJob-luokka ServerJob-luokka kuvaa yhden työn tilan. Metodit public TStatus GetStatus() Palauttaa työn tilan. public void SetStatus(TStatus status) Asettaan työn tilan. Attribuutit private TStatus status Työn senhetkinen tila. Alkuarvo INIT.

35 ServerClient-luokka ServerClient-luokka kuvaa asiakkaan. Jokaista asiakasta kohden luodaan yksi luokan ilmentymä, johon tallennetaan asiakkaan pistoke. Metodit public int GetSockFD() Palauttaa asiakkaan pistokkeen kahvan. public void SetSockFD(int sockfd) Asettaa asiakkaan pistokkeen kahvan. Attribuutit private int sockfd Asiakkaan pistokkeen kahva. 3.8 Asiakaskomponentti Kuva 9: Asiakaskomponentin luokat.

36 Asiakasohjelma käyttää verkon yli mahdollisesti toisessa koneessa käynnissä olevaa Populouspalvelinta. Kommunikaatio tapahtuu TCP/IP-protokollaa käyttäen. (kts ). Syöttötiedot asetetaan asiakasohjelmassa, joka välittää palvelupyynnöllä työn suoritettavaksi jollekin palvelimelle. Työn tilasta näytetään tietoa, ja sen valmistuttua asiakaskomponentti hakee tulokset ja tallentaa ne käyttäjän valitsemaan paikkaan. Asiakaskomponentilla voi luoda useampia yhtäaikaa käynnissä olevia töitä, joita asiakaskomponentti osaa tarvittaessa jakaa useammille palvelimille rinnakkain suoritettaviksi. Myös samalle palvelimelle voi lähettää useampia töitä vaikka aikaisemmat eivät olisikaan vielä valmistuneet. Yhteyden palvelimeen katketessa keskeytyvät myös siellä suorituksessa olevat työt. Yksittäistä palvelimelle lähetettyä työtä ei voida jatkaa, mutta asiakkaan hoitamaa iteroitua suoritusta voidaan jatkaa aloittamalla keskeytyneen iteraation alusta uudestaan, aikaisempien iteraatioiden tulokset ovat säilyneet. Asiakaskomponentin luokat on esitetty kuvassa Rajapinta Asiakas kommunikoi muun ohjelmiston kanssa ainoastaan pistokkeilla TCP/IP-yhteyden yli, eikä tarjoa mitään palvelupyyntörajapintaa ClientFrame-luokka ClientFrame-luokka on asiakaskomponentin käyttöliittymäpuolen pääluokka, jossa määritellään asiakasohjelmiston ulkoasu ja käyttäytyminen. Metodit Java Swingin luokasta javax.swing.jframe perittyjen käyttöliittymän piirtämiseen ja hallintaan liittyvien metodien lisäksi toteutettavat metodit kiinnitetään toteutusvaiheessa. Attribuutit Kiinnitetään toteutusvaiheessa JobControl-luokka JobControl-luokka hallinnoi simulaatiotöiden suoritusta. Käyttöliittymältä saatu työ otetaan ensin paikalliseen jonoon, josta se edelleen lähetetään palvelimelle suoritettavaksi. Palvelimilla suorituksia olevia töitä seurataan ja niiden edistymisestä pidetään kirjaa. Metodit public Job[] GetJobs()