ˇ Cesk e vysok e uˇ cen ı technick e v Praze Fakulta stavebn ı Bakal aˇ rsk a pr ace Praha 2011 V aclav Petr aˇs

ˇ ´ vysoke ´ uc ˇen´ı technicke ´ v Praze Cesk e Fakulta stavebn´ı

´r ˇska ´ pra ´ ce Bakala

Praha 2011

Václav Petráˇs

ˇ ´ vysoke ´ uc ˇen´ı technicke ´ v Praze Cesk e Fakulta stavebn´ı Obor geoinformatika

´r ˇska ´ pra ´ ce Bakala ´ ze SQLite Podpora databa pro program gama-local Support of SQLite database in program gama-local

ˇ Vedouc´ı práce: prof. Ing. Aleˇs Cepek, CSc. Katedra mapován´ı a kartografie Praha 2011

Václav Petráˇs

ČESKÉ VYSOKÉ UČENÍ TECHNICKÉ V PRAZE Fakulta stavební Thákurova 7, 166 29 Praha 6

ZADÁNÍ

BAKALÁŘSKÉ

studijní program:

Geodézie a kartografie

studijní obor:

Geoinformatika

akademický rok:

2010/2011

PRÁCE

Jméno a příjmení studenta: Václav Petráš Zadávající katedra:

Katedra mapování a kartografie

Vedoucí bakalářské práce:

prof. Ing. Aleš Čepek, CSc.

Název bakalářské práce: Název bakalářské práce v anglickém jazyce

Podpora databáze SQLite pro program gama-local Support of SQLite database in program gama-local

Rámcový obsah bakalářské práce: Navrhněte a implementujte podporu databáze SQLite pro program gama-local pro vyrovnání geodetických sítí projektu GNU Gama. Pro komunikaci s databází použijte nativní C/C++ rozhraní databáze. Pro implementaci použijte techniku callback funkcí. Datum zadání bakalářské práce:

Termín odevzdání:

13. 5. 2011 (vyplňte poslední den výuky příslušného semestru)

Pokud student neodevzdal bakalářskou práci v určeném termínu, tuto skutečnost předem písemně zdůvodnil a omluva byla děkanem uznána, stanoví děkan studentovi náhradní termín odevzdání bakalářské práce. Pokud se však student řádně neomluvil nebo omluva nebyla děkanem uznána, může si student zapsat bakalářskou práci podruhé. Studentovi, který při opakovaném zápisu bakalářskou práci neodevzdal v určeném termínu a tuto skutečnost řádně neomluvil nebo omluva nebyla děkanem uznána, se ukončuje studium podle § 56 zákona o VŠ č. 111/1998. (SZŘ ČVUT čl. 21, odst. 4) Student bere na vědomí, že je povinen vypracovat bakalářskou práci samostatně, bez cizí pomoci, s výjimkou poskytnutých konzultací. Seznam použité literatury, jiných pramenů a jmen konzultantů je třeba uvést v bakalářské práci. ....................................................... vedoucí bakalářské práce

....................................................... vedoucí katedry

ˇ ORIGINALN ´ Í ZADAN ´ Í ZDE VLO ZIT Zadání bakalářské práce převzal dne: ....................................................... student

Formulář nutno vyhotovit ve 3 výtiscích – 1x katedra, 1x student, 1x studijní odd. (zašle katedra) Nejpozději do konce 2. týdne výuky v semestru odešle katedra 1 kopii zadání BP na studijní oddělení a provede zápis údajů týkajících se BP do databáze KOS. BP zadává katedra nejpozději 1. týden semestru, v němž má student BP zapsanou. (Směrnice děkana pro realizaci studijních programů a SZZ na FSv ČVUT čl. 5, odst. 7)

Abstrakt Program gama-local je souˇcást´ı projektu GNU Gama a umoˇzn ˇuje vyrovn´ an´ı lok´ aln´ıch geodetick´ ych s´ıt´ı. C´ılem této bakaláˇrské práce je návrh a implementace podpory souborové databáze SQLite v programu gama-local. V souˇcasné dobˇe program gama-local podporuje jedin´ y vstupn´ı formát, a to XML. D´ıky této pr´ aci z´ıská moˇznost ˇc´ıst vstupn´ı data i z databáze SQLite. Pr´ ace se zab´ yv´ a specifiky pouˇzit´ı callback funkc´ı v C++ pˇri uˇzit´ı nativn´ıho rozhran´ı datab´ aze SQLite, které je oznaˇcováno jako SQLite C/C++ API. Souˇc´ ast´ı pr´ ace jsou i testy novˇe vytvoˇrené verze programu gama-local. Kl´ıˇ cov´ a slova: GNU Gama, vyrovnán´ı geodetick´ ych s´ıt´ı, programován´ı, C, C++, datab´ aze, SQLite

Abstract The program gama-local is a part of GNU Gama project and allows adjustment of local geodetic networks. The aim of this bachelor thesis is to design and implement support for the SQLite database in the program gama-local. Currently, the program gama-local supports only XML as an input. Thanks to this thesis program can read input data from the SQLite database. The thesis deals with the specifics of the use of callback functions in C++ using the native SQLite C/C++ Application Programming Interface. Tests of newly developed version of gama-local are also part of this thesis. Keywords: GNU Gama, adjustment of geodetic networks, programming, C, C++, databases, SQLite

Prohláˇsen´ı Prohlaˇsuji, ˇze bakaláˇrskou práci na téma Podpora databáze SQLite pro pro” gram gama-local“ jsem vypracoval samostatnˇe. Pouˇzitou literaturu a podkladové materiály uvád´ım v seznamu zdroj˚ u. V Praze dne .................

.................................. (podpis autora)

Podˇekován´ı Dˇekuji své rodinˇe a bl´ızk´ ym, jenˇz mi jsou oporou po celou dobu studia. Na tomto m´ıstˇe vˇsak pˇredevˇs´ım dˇekuji vedouc´ımu mé bakaláˇrské práce prof. Ing. Aleˇsovi ˇ Cepkovi, CSc. za pomoc, inspiraci a hlavnˇe za spolupráci, bez n´ıˇz by nebylo moˇzné plnohodnotné dokonˇcen´ı mé práce.

Obsah ´ Uvod

9

1 Program gama-local

11

1.1

Podporované formáty . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.2

Pouˇz´ıván´ı . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.3

Rozˇs´ıˇren´ı o podporu SQLite databáze . . . . . . . . . . . . . . . . . . 13

1.4

Databázové schéma . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2 SQLite C/C++ API

14

2.1

Klasické rozhran´ı . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.2

Rozhran´ı s callback funkcemi

3 Propojen´ı C a C++

. . . . . . . . . . . . . . . . . . . . . . 17 20

3.1

Funkce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.2

Ukazatele na funkce . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.3

Viditelnost funkc´ı . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.3.1

Deklarace extern "C" a prostor jmen . . . . . . . . . . . . . . 24

3.3.2

Deklerace extern "C" a viditelnost . . . . . . . . . . . . . . . 25

3.3.3

Pouˇzit´ı pˇri implementaci tˇr´ıdy SqliteReader . . . . . . . . . 27

3.4

Pˇredáván´ı objekt˚ u . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3.5

Zpracován´ı v´ yjimek . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3.6

Komplexn´ı ˇreˇsen´ı pomoc´ı ˇsablon a maker . . . . . . . . . . . . . . . . 31

4 Soukrom´ a implementace

34

5 Polymorfn´ı pr´ ace s v´ yjimkami

36

5.1

Klonován´ı . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

5.2

Ukládán´ı a vyvoláván´ı v´ yjimek . . . . . . . . . . . . . . . . . . . . . 38

5.3

Implementace ve tˇr´ıdˇe SqliteReader . . . . . . . . . . . . . . . . . . 41

6 Tˇ r´ıda SqliteReader a jej´ı implementace

45

6.1

Rozhran´ı . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

6.2

Implementace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

6.3

Integrace do gama-local . . . . . . . . . . . . . . . . . . . . . . . . . . 48

7 Testov´ an´ı

49

7.1

Kontroly pomoc´ı kompilátoru GCC . . . . . . . . . . . . . . . . . . . 50

7.2

Testován´ı pomoc´ı programu diff . . . . . . . . . . . . . . . . . . . . . 51

7.3

Testován´ı pomoc´ı programu gama-local-cmp . . . . . . . . . . . . . . 53

Z´ avˇ er

56

Pouˇ zit´ e zdroje

57

Seznam pouˇ zit´ ych zkratek

58

Seznam pˇ r´ıloh

59

A Datab´ azov´ e sch´ ema gama-local-schema.sql

60

B Dokumentace tˇ r´ıdy SqliteReader

63

C Pouˇ zit´ a nastaven´ı kompil´ atoru GCC

75

ˇ CVUT Praha

´ UVOD

´ Uvod Velká ˇcást geodézie se zab´ yvá zpracován´ım namˇeˇren´ ych hodnot, jako jsou napˇr´ıklad délky a u ´hly. V´ ysledkem jsou vˇetˇsinou souˇradnice bod˚ u na povrchu Zemˇe. Zpracován´ı je tvoˇreno v´ ypoˇcty, které dnes vˇsechny m˚ uˇzeme zahrnout pod pojem vyrovnán´ı lokáln´ı geodetické s´ıtˇe. Lokáln´ı s´ıt´ı se m´ın´ı s´ıt’ vyrovnávaná v kartézské soustavˇe souˇradnic. Vyrovnán´ı geodetick´ ych s´ıt´ı umoˇzn ˇuje program gama-local , kter´ y je souˇca´st´ı projektu GNU Gama. Zdrojové kódy projektu GNU Gama jsou volnˇe dostupné pod licenc´ı GNU GPL. Vstupem i v´ ystupem programu gama-local jsou v souˇcasné dobˇe soubory ve znaˇckovac´ım jazyce XML (Extensible Markup Language). Vstupn´ı soubor obsahuje hodnoty mˇeˇren´ ych veliˇcin a v´ ystupn´ı soubor obsahuje vypoˇctené (tj. vyrovnané) hodnoty neznám´ ych veliˇcin. Program se ovládá z pˇr´ıkazové ˇra´dky. C´ılem této bakaláˇrské práce je umoˇznit programu gama-local ˇc´ıst data z databáze SQLite verze 3. Databáze SQLite je souborová databáze, coˇz znamená, ˇze data nejsou spravována databázov´ ym serverem, ale jsou uloˇzena v jednom souboru. Formát souboru je nezávisl´ y na poˇc´ıtaˇcové platformˇe, coˇz z databáze SQLite ˇcin´ı vhodn´ y nástroj pro správu a pˇrenos strukturovan´ ych dat mezi r˚ uzn´ ymi systémy a programy (nejen v oboru geodézie). K tomuto souboru je moˇzné pˇristoupit pomoc´ı SQLite C/C++ API, coˇz je rozhran´ı, které umoˇzn ˇuje programovat aplikace vyuˇz´ıvaj´ıc´ı databázi SQLite. Program gama-local je napsán v jazyce C++, a tak je moˇzné toto rozhran´ı, urˇcené pro jazyky C a C++, pouˇz´ıt. Tv˚ urci databáze SQLite C/C++ API poskytuj´ı SQLite volnˇe k libovolnému pouˇzit´ı. Podpora databáze v programu gama-local bude velmi v´ yhodná z hlediska spolupráce s pˇripravovan´ ym programem QGama, kter´ y nab´ız´ı stejnou funkcionalitu jako program gama-local . Program QGama nen´ı pro pˇr´ıkazovou ˇra´dku, ale poskytuje grafické uˇzivatelské rozhran´ı. V souˇcasné dobˇe je program QGama ve stádiu v´ yvoje. V programu gama-local bude spolupráci s databáz´ı SQLite zajiˇst’ovat nová tˇr´ıda SqliteReader. Tato práce se zab´ yvá implementac´ı této tˇr´ıdy a také funkcemi, které tˇr´ıda pouˇz´ıvá. Pˇri implementaci je tˇreba dbát na omezen´ı, která jsou zp˚ usobena t´ım, ˇze SQLite C/C++ API je primárnˇe urˇceno pro jazyk C, zat´ımco program gama-local je v jazyce C++. 9

ˇ CVUT Praha

´ UVOD

Novou funkcionalitu je nutné po zaˇclenˇen´ı do programu gama-local náleˇzitˇe otestovat. Projekt GNU Gama obsahuje mnoˇzstv´ı pˇr´ıklad˚ u geodetick´ ych s´ıt´ı, které je moˇzné pouˇz´ıt jako vstupn´ı data pˇri testován´ı. V´ yvoj projektu GNU Gama prob´ıhá na systémech z rodiny GNU/Linux . K testován´ı je tedy moˇzné pouˇz´ıt ˇradu volnˇe dostupn´ ych program˚ u, takzvan´ ych unixov´ ych utilit. Dále je pro testován´ı moˇzné pouˇz´ıt nov´ y program gama-local-cmp. Ten doplˇ nuje projekt GNU Gama o moˇznost porovnat v´ ystupy z programu gama-local . Program gama-local-cmp vylouˇc´ı náhodné rozd´ıly v´ ysledk˚ u vznikaj´ıc´ı pˇri v´ ypoˇctu na poˇc´ıtaˇci (numerick´ y ˇsum) a je vhodn´ y pro testován´ı nov´ ych verz´ı programu gama-local .

10

ˇ CVUT Praha

1

1 PROGRAM GAMA-LOCAL

Program gama-local

Program gama-local je souˇcást´ı projektu GNU Gama [14], kter´ y je zamˇeˇren na vyrovnán´ı geodetick´ ych s´ıt´ı. Projekt GNU Gama je ˇs´ıˇren pod licenc´ı GNU GPL [7]. Program gama-local je programem pro pˇr´ıkazovou ˇrádku. Je s n´ım moˇzné vyrovnávat geodetické s´ıtˇe, které obsahuj´ı r˚ uzné typy mˇeˇren´ı jako napˇr´ıklad délky, u ´hly ˇci v´ yˇskové rozd´ıly. V této souvislosti se hod´ı zm´ınit, ˇze se v souˇcasné dobˇe pro projekt GNU Gama také vyv´ıj´ı multiplatformn´ı grafické uˇzivatelské rozhran´ı QGama [15]. Projekt QGama je vyv´ıjen na platformˇe Qt [13]. Zdrojové kódy projektu GNU Gama lze z´ıskat stejnˇe jako dokumentaci prostˇrednictv´ım internetové stránky projektu: http://www.gnu.org/software/gama/ Samotné zdrojové kódy jsou dostupné pˇr´ımo ze stránky: http://ftpmirror.gnu.org/gama Projekt GNU Gama pouˇz´ıvá pro správu verz´ı systém Git1 . Nejlepˇs´ı moˇznost´ı, jak z´ıskat aktuáln´ı verzi, je proto pˇr´ıkaz, kter´ y vytvoˇr´ı lokáln´ı kopii Git repozitáˇre.2 $ git clone git://git.sv.gnu.org/gama.git Aktuáln´ı verze programu gama-local , kterou je moˇzné z´ıskat z v´ yˇse uveden´ ych m´ıst, jiˇz obsahuje i zdrojové kódy, které jsou v´ ysledkem této bakaláˇrské práce. Na systémech GNU/Linux vypadá kompilace a pˇr´ıpadnˇe i instalace projektu následovnˇe: $ cd gama $ ./autogen.sh $ ./configure $ make $ make install 1 2

Ofici´ aln´ı str´ any systému Git jsou na http://git-scm.com/ Pro z´ısk´ an´ı zdrojov´ ych k´ od˚ u z Git repozitáˇre lze téˇz pouˇz´ıt odkaz http://git.savannah.gnu.

org/cgit/gama.git/snapshot/gama-master.tar.gz.

11

ˇ CVUT Praha


Po vykonán´ı pˇr´ıkazu make by se v adresáˇri gama/bin mˇelo objevit nˇekolik spustiteln´ ych soubor˚ u, mezi nimi i program gama-local .

1.1

Podporovan´ e form´ aty

Vstupem pro program gama-local bylo doposud jen XML [8]. Jak soubor vypadá, je popsáno v dokumentaci projektu GNU Gama [9, str. 7 aˇz 20]. Souboru se obvykle dává pˇr´ıpona .gkf (vznikla ze slov gama konfigurace“). ” V´ ystupem je bud’ prost´ y formátovan´ y text, nebo opˇet XML. Soubor ve formátu prostého textu je vhodn´ y pro rychlé zjiˇstˇen´ı v´ ysledk˚ u. XML soubor je moˇzné s v´ yhodou pouˇz´ıt pro dalˇs´ı zpracován´ı.3 Je napˇr´ıklad moˇzné v´ ysledky pˇrevést do jiného formátu.

1.2

Pouˇ z´ıv´ an´ı

Pouˇz´ıván´ı gama-local vyˇzaduje od uˇzivatele základn´ı znalost práce s pˇr´ıkazovou ˇra´dkou a dále základn´ı znalost XML. Obecnˇe se pˇredpokládá, ˇze vstupn´ı XML soubor uˇzivatel vytvoˇr´ı nˇejak´ ym programem. Je vˇsak také moˇzné vyj´ıt z nˇekterého z pˇr´ıklad˚ u dostupn´ ych ze stránek projektu GNU Gama [14] a pˇri malém objemu dat hodnoty do souboru zapsat ruˇcnˇe. Na mém poˇc´ıtaˇci s operaˇcn´ım systémem Ubuntu4 m˚ uˇze vypadat spuˇstˇen´ı programu gama-local následovnˇe. $ ./ gama - local input . gkf -- language cz -- txt output . txt

Pˇredpokládám, ˇze jsem právˇe v adresáˇri, kde mám pˇr´ısluˇsn´ y spustiteln´ y soubor, a ˇze mám vytvoˇren´ y soubor input.gkf, kde jsou pˇr´ısluˇsné vstupn´ı hodnoty. Kromˇe jazyka lze z pˇr´ıkazové ˇra´dky nastavit napˇr´ıklad také algoritmus ˇci kódován´ı soubor˚ u. Dalˇs´ı informace k pouˇz´ıván´ı lze nalézt v nápovˇedˇe programu ˇci v dokumentaci [9]. 3

Pro ˇcten´ı v´ ysledk˚ u z XML je v projektu GNU Gama pˇripravena tˇr´ıda, jej´ıˇz popis lze nalézt

na http://geo.fsv.cvut.cz/gwiki/GNU_Gama_LocalNetworkAdjustmentResults. 4 Ubuntu je jedna z distribuc´ı operaˇcn´ıho systému GNU/Linux. Distribuce je podporována spoleˇcnost´ı Canonical Ltd. a je dostupná z http://www.ubuntu.com/

12

ˇ CVUT Praha

1.3


Rozˇ s´ıˇ ren´ı o podporu SQLite datab´ aze

Mnoho aplikac´ı dnes nˇejak´ ym zp˚ usobem vyuˇz´ıvá databázi SQLite, coˇz je souborová databáze, která pouˇz´ıvá jazyk SQL. Práce s SQL databáz´ı má mnohé v´ yhody, mezi které pˇrirozenˇe patˇr´ı pohodlné formulován´ı dotaz˚ u. Jak jiˇz bylo ˇreˇceno, jedná se o souborovou databázi, coˇz znamená, ˇze nen´ı potˇreba, aby nˇekde bˇeˇzel databázov´ y server. Rozhran´ı mezi souborem a daty uloˇzen´ ymi v databázi obvykle zajiˇst’uje knihovna. K SQLite autoˇri dodávaj´ı SQLite C/C++ API (viz ˇca´st 2). Mnoho tv˚ urc˚ u knihoven pro r˚ uzné programovac´ı jazyky vˇsak poskytuje vlastn´ı rozhran´ı ˇ k databázi SQLite. Sirok´ a podpora a dostupnost ˇcin´ı z databáze SQLite ideáln´ı v´ ymˇenn´ y formát. Podpora SQLite databáze by mˇela usnadnit spolupráci mezi gama-local a dalˇs´ımi programy. Projekt QGama poˇc´ıtá s podporou r˚ uzn´ ych databáz´ı d´ıky platformˇe Qt. Mezi nimi je i databáze SQLite. Pro zv´ yˇsen´ı vzájemné kompatibility je vhodné, aby i program gama-local podporoval databázi SQLite. V projektu GNU Gama se na rozd´ıl od projektu QGama Qt nevyuˇz´ıvá. Pro komunikaci s databáz´ı SQLite program gama-local vyuˇz´ıvá nativn´ı SQLite C/C++ API. Databázové schéma, které pouˇz´ıvá QGama, lze pouˇz´ıt i pro gama-local , ˇc´ımˇz je dalˇs´ı pˇredpoklad vzájemné kompatibility splnˇen.

1.4

Datab´ azov´ e sch´ ema

Pro projekt QGama jiˇz bylo vyvinuto databázové schéma. Toto schéma obsahuje popis databázov´ ych tabulek, do kter´ ych je moˇzné uloˇzit záznam lokáln´ı geodetické s´ıtˇe. Tento záznam odpov´ıdá jednomu vstupn´ımu XML souboru a pouˇz´ıvá se pro nˇej oznaˇcen´ı konfigurace (configuration). Kromˇe informac´ı, které lze uloˇzit ve vstupn´ım XML souboru, obsahuje záznam také nˇekteré parametry pˇr´ıkazového ˇra´dku, se kter´ ymi se spouˇst´ı program gama-local . Databázové schéma bylo vyvinuto s ohledem na to, ˇze QGama by mˇela umoˇznit propojen´ı s r˚ uzn´ ymi SQL databázemi. V databázovém schématu byly pouˇzity jen takové konstrukce, které funguj´ı ve vˇsech podporovan´ ych databáz´ıch. Schéma je pouˇzitelné nebo alespoˇ n ˇcásteˇcnˇe pouˇzitelné pro tyto databáze: PostreSQL, MySQL, 13

ˇ CVUT Praha

2 SQLITE C/C++ API

Oracle Database, SQLite. Databázové schéma bylo jiˇz zaˇclenˇeno do projektu GNU Gama a je v souboru xml/gama-local-schema.sql v adresáˇri zdrojov´ ych kód˚ u GNU Gama. Kompletn´ı databázové schéma je v pˇr´ıloze A. Pro pˇrevod vstupn´ıho XML souboru do SQL pˇr´ıkaz˚ u (INSERT) slouˇz´ı program gama-local-xml2sql. Program je souˇcást´ı projektu GNU Gama. Program generuje SQL pˇr´ıkazy, tyto pˇr´ıkazy by (teoreticky) mˇely b´ yt nezávislé na konkrétn´ı databázi. Pouze pro u ´ˇcely testován´ı databázového schématu byl téˇz napsán program, kter´ y u ´daje (jednu konfiguraci) z SQLite databáze pˇrevede do vstupn´ıho XML souboru. Pouˇz´ıvá se pro databázi vytvoˇrenou pomoc´ı zmiˇ novaného schématu a naplnˇenou dávkou z programu gama-local-xml2sql.

2

SQLite C/C++ API

Databáze SQLite verze 3 a vˇse, co k n´ı patˇr´ı, je ˇs´ıˇreno pod Public Domain. To plat´ı i pro nativn´ı SQLite C/C++ API. Projekt GNU Gama se snaˇz´ı b´ yt co nejménˇe závisl´ y na jin´ ych knihovnách. V souˇcasnosti je závisl´ y pouze na knihovnˇe Expat a ta je dodávána spolu s ostatn´ımi zdrojov´ ymi kódy.5 Vzhledem k této snaze bylo nativn´ı SQLite C/C++ API jasnou volbou, protoˇze s sebou nepˇrináˇs´ı závislost na ˇza´dné rozsáhlé knihovnˇe.6 SQLite C/C++ API [11] je aplikaˇcn´ı programátorské rozhran´ı pro jazyk C a je uzp˚ usobeno k tomu, aby mohlo b´ yt pouˇzito i v jazyce C++. Nicménˇe na práci v jazyce C++ má toto jisté dopady a to pˇredevˇs´ım pˇri pouˇzit´ı rozhran´ı popsaného v ˇca´sti 2.2. Tyto dopady jsou zevrubnˇe rozebrány v ˇcásti 3.

2.1

Klasick´ e rozhran´ı

Rozhran´ı tvoˇr´ı funkce sqlite3 open, která pˇreb´ırá ukazatel na ukazatel na objekt sqlite3. Funkce otevˇre databázi a uloˇz´ı do promˇenné na n´ıˇz ji byl pˇredán ukaza5

Expat je knihovna pro ˇcten´ı XML. Projekt GNU Gama je standardnˇe sestavován se systémovou

knihovnou Expat. V pˇr´ıpadˇe, ˇze je knihovna nedostupná, je moˇzné pro sestaven´ı pouˇz´ıt dodané zdrojové k´ ody. 6 Nav´ıc je moˇzné sestavit projekt GNU Gama bez podpory SQLite databáze (v´ıce viz 6.3).

14

ˇ CVUT Praha

2 SQLITE C/C++ API

tel hodnotu ukazatele na nov´ y databázov´ y objekt typu sqlite3. Jedná se vlastnˇe o konstruktor objektu sqlite3, coˇz je objekt reprezentuj´ıc´ı spojen´ı s databáz´ı. Páteˇr´ı tohoto rozhran´ı jsou funkce sqlite3 prepare v2 a sqlite3 step. Funkci sqlite3 prepare v2 se pˇredává ukazatel na databázov´ y objekt, SQL pˇr´ıkaz, kter´ y se má vykonat, ukazatel na ukazatel na objekt typu sqlite3 stmt a jeˇstˇe dalˇs´ı parametry, které vˇsak nejsou d˚ uleˇzité (viz [11]). Jej´ı zavolán´ı zp˚ usob´ı vytvoˇren´ı objektu typu sqlite3 stmt a lze o n´ı uvaˇzovat jako o konstruktoru. Objekt sqlite3 stmt reprezentuje jeden SQL pˇr´ıkaz. Funkce sqlite3 step pracuje jen s objektem sqlite3 stmt a je nutné ji zavolat, aby se pˇr´ıkaz vykonal, nebot’ funkce sqlite3 prepare v2 jej pouze pˇriprav´ı. Pokud byl vykonan´ y pˇr´ıkaz SELECT, tak kaˇzdé zavolán´ı funkce sqlite3 step nás posune na dalˇs´ı ˇra´dek v´ ysledku pˇr´ıkazu. Jednotlivé hodnoty atribut˚ u se pak z´ıskávaj´ı volán´ım funkc´ı ze skupiny sqlite3 column... v závislosti na tom, jak´ y typ hodnoty chceme obdrˇzet. V pˇr´ıkladu, kter´ y bude následovat jsou pouˇzity funkce sqlite3 column int a sqlite3 column text. To jestli jeˇstˇe zb´ yvaj´ı nˇejaké nezpracované ˇrádky se zjiˇst’uje z návratového kódu. Pokud vykonan´ y pˇr´ıkaz nevrac´ı ˇza´dn´ y v´ ysledek, staˇc´ı volat funkci sqlite3 step jen jednou. Po volán´ı témˇeˇr kaˇzdé z v´ yˇse jmenovan´ ych funkc´ı je nutné provádˇet kontrolu návratového kódu. Jen tak je moˇzné urˇcit, ˇze nastala chyba. Posledn´ı chybovou zprávu lze z´ıskat zavolán´ım funkce sqlite3 errmsg, která pˇreb´ırá ukazatel na objekt sqlite3. Po zpracován´ı v´ ysledk˚ u SQL pˇr´ıkazu je tˇreba uvolnit pamˇet’ pˇridˇelenou objektu sqlite3 stmt. To zajist´ı funkce sqlite3 finalize (je to vlastnˇe destruktor objektu sqlite3 stmt). Kontrolu návratového kódu funkce sqlite3 finalize nen´ı nutné provádˇet. Ve vˇetˇsinˇe pˇr´ıpad˚ u zcela postaˇcuje zkontrolovat návratov´ y kód funkce sqlite3 step. Po ukonˇcen´ı práce je tˇreba zavolat funkci sqlite3 close. Kontrola návratového kódu funkce sqlite3 close m˚ uˇze upozornit mimo jiné na aktivn´ı objekty typu sqlite3 stmt (coˇz znamená, ˇze nebylo zavoláno sqlite3 finalize). Následuje pˇr´ıklad, kter´ y ukazuje pouˇzit´ı v´ yˇse uveden´ ych funkc´ı. Pro zjednoduˇsen´ı pˇr´ıklad pˇredpokládá jiˇz vytvoˇrenou a naplnˇenou databázi. 1

sqlite3 * db ;

15

ˇ CVUT Praha

2 SQLITE C/C++ API

2

sqlite3_stmt * stmt ;

3

int rc = sqlite3_open ( " test . sqlite " , & db ) ;

4

if ( rc )

5 6

std :: cerr << " database error \ n " ; else { rc = s ql it e3 _p re pa re _v 2 ( db ,

7 8

" SELECT id , name FROM people " ,

9

-1 , & stmt , 0) ; if ( rc )

10

std :: cerr <<

11

" error : "

<< sqlite3_errmsg ( db ) << std :: endl ;

12

else {

13

while (( rc = sqlite3_step ( stmt ) ) == SQLITE_ROW ) {

14 15

const int id = sq li te 3_ co lu mn _i nt ( stmt , 0) ;

16

const char * name = ( const char *) s q li t e 3 _c o l um n _ te x t ( stmt , 1) ;

17

std :: cout << id << " " << name << std :: endl ;

18

}

19

if ( rc != SQLITE_DONE )

20

std :: cerr << " error : "

21

<< sqlite3_errmsg ( db ) << std :: endl ;

22

sqlite3_finalize ( stmt ) ;

23

}

24

sqlite3_close ( db ) ;

25 26

}

Pouˇzit´ı prob´ıraného rozhran´ı vyˇzaduje hodnˇe práce a kódu, vzhledem k tomu, ˇze je stále potˇreba kontrolovat návratové kódy, zpracovávat pˇr´ıpadné chyby a zajiˇst’ovat volán´ı funkc´ı, které pln´ı u ´lohu konstruktor˚ u a destruktor˚ u. Moˇzn´ ym ˇreˇsen´ım je zabalit tyto funkce do nˇekolika objekt˚ u, a t´ım automatizovat urˇcité akce. Dalˇs´ı moˇznost´ı je pouˇzit´ı rozhran´ı popsaného v následuj´ıc´ı ˇcásti. Zb´ yvá dodat, ˇze zde bylo popsáno pouze základn´ı rozhran´ı. SQLite C/C++ API nab´ız´ı velké mnoˇzstv´ı funkc´ı, jejichˇz popis pˇresahuje rámec této práce. Pˇr´ıkladem m˚ uˇze b´ yt skupina funkc´ı sqlite3 bind..., které se vyuˇzij´ı pˇredevˇs´ım ve spojitosti s pˇr´ıkazem INSERT.

16

ˇ CVUT Praha

2.2

2 SQLITE C/C++ API

Rozhran´ı s callback funkcemi

SQLite C/C++ API poskytuje jeˇstˇe dalˇs´ı rozhran´ı, které je vlastnˇe pouhou obálkou nad rozhran´ım popsan´ ym v ˇcásti 2.1. Ostatnˇe to prav´ı i dokumentace [10, ˇca´st 2.0]. It is important to realize that neither sqlite3 exec nor sqlite3 get table do anything that cannot be accomplished using the core routines. In fact, these wrappers are implemented purely in terms of the core routines. Zmiˇ novaná funkce sqlite3 get table funguje podobnˇe jako sqlite3 exec avˇsak je oznaˇcena jako legacy interface a je doporuˇceno ji nepouˇz´ıvat [11]. To je d˚ uvod, proˇc zde nen´ı toto rozhran´ı rozebráno. ˇuje vykonat SQL pˇr´ıkaz jedn´ım Funkce sqlite3 exec je rozhran´ım, které umoˇzn jedin´ ym volán´ım. Po zavolán´ı sqlite3 exec je nutné zkontrolovat návratov´ y kód a pˇr´ıpadnˇe uvolnit pamˇet’ pˇridˇelenou pro chybovou zprávu. Pˇri pouˇz´ıván´ı jsme osvobozeni od provádˇen´ı mnoh´ ych kontrol návratov´ ych kód˚ u (kontroluje se jen jeden). Pˇred zavolán´ım funkce sqlite3 exec je samozˇrejmˇe nutné provést jiˇz popsané otevˇren´ı databáze a po ukonˇcen´ı práce je nutné databázi zase uzavˇr´ıt. Odpadá vˇsak povinnost volat pro kaˇzd´ y pˇr´ıkaz trojici funkc´ı sqlite3 prepare v2, sqlite3 step a sqlite3 finalize. V tomto rozhran´ı se pouˇz´ıvaj´ı callback funkce ˇcili zpˇetná volán´ı. Jiˇz zmiˇ nované funkci sqlite3 exec se pˇredá ukazatel na funkci, kterou bude následnˇe volat pro kaˇzd´ y ˇra´dek v´ ysledku dotazu do databáze. Tato callback funkce se zpravidla p´ıˇse pro zpracovan´ı jednoho pˇr´ıkazu. Pokud bude SQL pˇr´ıkaz pˇredan´ y funkci sqlite3 exec pˇr´ıkazem, kter´ y nevrac´ı ˇza´dn´ y v´ ysledek, nebude callback funkce zavolána. V tomto pˇr´ıpadˇe je vhodné pˇredat jako hodnotu ukazatele na callback funkci nulov´ y ukazatel (NULL, 0). Pro vykonáván´ı pˇr´ıkaz˚ u, jako jsou napˇr´ıkad INSERT ˇci UPDATE, nen´ı tˇreba psát ˇza´dnou callback funkci. Vzhledem k tomu, ˇze kód callback funkce je jinde neˇz kód, kter´ y zavolal funkci sqlite3 exec, a volaj´ıc´ı kód zˇrejmˇe oˇcekává nˇejaké v´ ysledky, je nutné pˇredat callback funkci objekt, kter´ y bude moci pro uloˇzen´ı v´ ysledk˚ u pouˇz´ıt. Tento objekt se pˇredá funkci sqlite3 exec, která ho následnˇe pˇredá callback funkci. Pro pˇredáván´ı

17

ˇ CVUT Praha

2 SQLITE C/C++ API

objektu je pouˇzit ukazatel na void, je tedy moˇzné pˇredat ukazatel na libovoln´ y objekt. Aby mohl b´ yt objekt pouˇzit, je nutné void* pˇretypovat na pˇr´ısluˇsn´ y ukazatel (viz téˇz ˇca´st 3.4). Funkce sqlite3 exec pˇreb´ırá pˇet parametr˚ u. Vˇsechny parametry jsou ukazatele. Prvn´ı dva je nutné zadávat vˇzdy. Jako tˇret´ı, ˇctvrt´ y a pát´ y parametr lze pˇredat nulov´ y ukazatel (NULL). Parametry jsou uvedeny v následuj´ıc´ım seznamu. 1.

sqlite3*

2.

const char*

3.

int (*)(void*, int, char**, char**)

4.

void*

5.

char**

ukazatel na databázi C ˇretˇezec s SQL pˇr´ıkazem ukazatel na callback funkci ukazatel pˇredávan´ y callback funkci ukazatel na chybovou zprávu

Jak jiˇz bylo naznaˇceno, callback funkce obsahuje kód, kter´ y zpracovává jednotlivé ˇra´dky v´ ysledku SQL pˇr´ıkazu. Callback funkce zná obsah vˇzdy jen jednoho ˇra´dku. Následuje seznam parametr˚ u callback funkce. 1.

void*

ukazatel pˇredan´ y funkci sqlite3 exec

2.

int

3.

char**

ukazatel na pole atribut˚ u

4.

char**

ukazatel na pole jmen atribut˚ u

poˇcet atribut˚ u

Následuje v´ ypis, kter´ y ukazuje základn´ı pouˇzit´ı rozhran´ı tvoˇreného pˇredevˇs´ım funkc´ı sqlite3 exec. Nejprve je otevˇrena databáze (kontrola návratového kódu je pro zjednoduˇsen´ı vynechána) a inicializován C ˇretˇezec pro chybovou zprávu. Poté zavolána funkce sqlite3 exec. Funkci je pˇredán jako prvn´ı parametr ukazatel na databázov´ y objekt typu sqlite3, a jako druh´ y parametr SQL pˇr´ıkaz, kter´ y chceme vykonat. Jako tˇret´ı je pˇredán ukazatel na callback funkci7 , kterou chceme pouˇz´ıt ke zpracován´ı v´ ysledku. Jako ˇctvrt´ y parametr je pˇredán ukazatel na objekt, se kter´ ym bude callback funkce pracovat. V tomto pˇr´ıpadˇe je to standardn´ı v´ ystupn´ı proud. A jako pát´ y parametr je pˇredán ukazatel na ˇretˇezec s chybovou zprávou. 1

extern " C " int readPeople ( void * data , int argc ,

2

char ** argv , char **) ;

3

void test () { 7

Ukazatel na funkci v C++ z´ısk´ ame tak, ˇze nap´ıˇseme jméno dané funkce.

18

ˇ CVUT Praha

2 SQLITE C/C++ API

4

sqlite3 * db ;

5

int rc = sqlite3_open ( " test . sqlite " , & db ) ;

6

// ... check rc

7

char * errorMsg = 0;

8

rc = sqlite3_exec ( db , " SELECT id , name FROM people " , readPeople , & std :: cout , & errorMsg ) ;

9

if ( rc != SQLITE_OK ) {

10 11

std :: cerr << " error : " ;

12

if ( errorMsg ) {

13

std :: cerr << errorMsg ;

14

sqlite3_free ( errorMsg ) ; }

15

std :: cerr << std :: endl ;

16

}

17

sqlite3_close ( db ) ;

18 19

}

Po zavolán´ı funkce sqlite3 exec se provede kontrola návratového kódu (ˇra´dek 10) a pokud signalizuje chybu pokraˇcuje se v´ ypisem chybové zprávy. Zde je d˚ uleˇzité, ˇze funkce sqlite3 exec alokuje pamˇet’ pro chybovou zprávu jen v pˇr´ıpadˇe, ˇze doˇslo k chybˇe. Hodnotu ukazatele na vytvoˇrenou chybovou zprávu pak uloˇz´ı do promˇenné definované na ˇra´dku 7. To m˚ uˇze provést d´ıky tomu, ˇze j´ı byl pˇredán ukazatel na tuto promˇenou jako pát´ y parametr. Alokovanou pamˇet’ je tˇreba uvolnit (ˇrádek 14). Nakonec je zavˇre databáze funkc´ı sqlite3 close. V pˇredcházej´ıc´ım v´ ypisu byla callback funkce pouze deklarována. Vzhledem k tomu, ˇze je callback funkci potˇreba napsat vˇzdy, kdyˇz chceme z´ıskat v´ ysledek SQL pˇr´ıkazu, uvedu zde i jej´ı definici. Na prvn´ım ˇrádku funkce (ˇra´dek 3 v´ ypisu) je pˇretypován´ı ukazatele na void na ukazatel na std::ostream pomoc´ı operátoru static cast. Situace je zde m´ırnˇe zesloˇzitˇena t´ım, ˇze pˇretypovan´ y ukazatel je pouˇzit jeˇstˇe k z´ıskán´ı reference na objekt typu std::ostream. Poté je vˇsak moˇzno s objektem pracovat, jak je pro nˇej bˇeˇzné. V pˇr´ıpadˇe v´ ystupn´ıho proudu je to vloˇzen´ı dat z´ıskan´ ych z databáze. Tˇret´ı parametr je ukazatel pole C ˇretˇezc˚ u s atributy, proto je pouˇzit operátor indexován´ı pro pˇr´ıstup k jednotliv´ ym atribut˚ um. V pˇr´ıkazu SELECT v pˇredcházej´ıc´ım v´ ypise se vyb´ıraly dva atributy, proto je jasné, ˇze lze pouˇz´ıt indexy 0 a 1. Poˇcet atribut˚ u uloˇzen´ y ve druhém parametru nebyl vyuˇzit stejnˇe jako ˇctvrt´ y 19

ˇ CVUT Praha

3 PROPOJENÍ C A C++

parametr. 1

extern " C " int readPeople ( void * data , int argc , char ** argv , char **) {

2 3

std :: ostream & out = * static_cast < std :: ostream * >( data ) ;

4

out << argv [0] << " " << argv [1] << std :: endl ;

5

return 0;

6

}

3

Propojen´ı C a C++

Tato ˇca´st uvád´ı, co je tˇreba dodrˇzet pˇri propojován´ı kódu napsaného v C a v C++. Tˇechto zásad se mus´ı drˇzet i implementace tˇr´ıdy SqliteReader, protoˇze pracuje s SQLite C/C++ API. V této ˇca´sti pˇredpokládám základn´ı znalosti programovac´ıho jazyka C++, které lze z´ıskat napˇr´ıklad z [5].

3.1

Funkce

Jak jiˇz bylo naznaˇceno, pˇri souˇcasném pouˇz´ıván´ı jazyk˚ u C a C++ existuj´ı jistá pravidla, která je nutné respektovat. A to se t´ yká i funkc´ı. Funkce v jazyce C maj´ı jiné linkovac´ı konvence (linkage conventions)8 neˇz funkce v jazyce C++. Pokud chceme volat C funkci v C++ kódu je nutné specifikovat, ˇze funkce má C linkován´ı (C linkage). Specifikace linkován´ı lze dosáhnout t´ım, ˇze se pˇred deklaraci funkce pˇridá kl´ıˇcové slovo extern následované ˇretˇezcov´ ym literálem oznaˇcuj´ıc´ım jazyk, v pˇr´ıpadˇe jazyka C tedy extern "C". Poznamenejme, ˇze dle standardu [2, 7.5.3] by kaˇzdá implementace C++ mˇela poskytnout linkován´ı pro C funkce ("C") a pro C++ funkce ("C++"), které je implicitn´ı. Podpora ostatn´ıch jazyk˚ u je závislá na implementaci. Stejnˇe jako ˇretˇezcové literály, jenˇz je oznaˇcuj´ı. Linkován´ı je moˇzné urˇcit pro jednu funkci. extern " C " int fun ( int ) ;

Nebo je také moˇzné vloˇzit deklaraci do bloku extern "C". 8

V ˇceské literatuˇre se ˇcasto pracuje s pojmem zacházen´ı se jmény funkc´ı.

20

ˇ CVUT Praha


extern " C " { int fun ( int ) ; }

Aby mohl b´ yt jeden hlaviˇckov´ y soubor pouˇzit pro C i C++, je nutné, aby funkce mˇely C linkovnán´ı. Toho se dosáhne pomoc´ı bloku extern "C" a direktiv preprocesoru. // mylib . h : # ifdef __cplusplus extern " C " { # endif void f ( int ) ; # ifdef __cplusplus } # endif

Tento postup ˇcasto pouˇz´ıvaj´ı knihovny pro C pro své hlaviˇckové soubory, aby mohly b´ yt pouˇzity s C++. Uvedené plat´ı to i pro SQLite C/C++ API (hlaviˇckov´ y soubor <sqlite3.h>).

3.2

Ukazatele na funkce

R˚ uzné druhy linkován´ı se t´ ykaj´ı i ukazatel˚ u na funkce a to jak typ˚ u deklarovan´ ych pomoc´ı typedef, tak i parametr˚ u, které jsou ukazateli na funkce. Jak se urˇc´ı linkován´ı je ukázáno na pˇr´ıkladech. 1

// mixing C and C ++ function pointers :

2

typedef void (* pf_cpp ) () ; // pf_cpp is a pointer to a C ++ function ( has C ++ linkage )

3

void f_cpp () {} // f_cpp is a C ++ function ( has C ++ linkage )

4

extern " C " {

5

typedef void (* pf_c ) () ; // pf_c is a pointer to a C function ( has C linkage )

6 7

void f_c () {} // f_c is a C function ( has C linkage ) } // end of extern " C " block

8 9

void fun1 ( pf_cpp pf ) { // fun1 takes one parameter of type pointer to C ++ function

21

ˇ CVUT Praha

pf () ;

10 11


}

12 13

void fun2 ( pf_c pf ) { // fun2 takes one parameter of type pointer to C function pf () ;

14 15

}

16 17

void test_fun12 () {

18

fun1 ( f_cpp ) ; // ok

19

fun2 ( f_c ) ;

// ok

20

fun1 ( f_c ) ;

// error

21

fun2 ( f_cpp ) ; // error

22

}

Kdyˇz pˇredáme funkci, oˇcekávaj´ıc´ı ukazatel na C++ funkci, ukazatel na C funkci (ˇrádek 20), nebo naopak pˇredáme m´ısto ukazatele na C funkci ukazatel na C++ funkci (ˇra´dek 21), mˇelo by doj´ıt k chybˇe pˇri kompilaci. To odpov´ıdá tomu, co je uvedeno ve standardu [2, 7.1.5]: Two function types with different language linkages are distinct types even if they are otherwise identical. Na druhou stranu B. Stroustrup uvád´ı, ˇze pokud to implementace umoˇzn ˇuje, je moˇzné, aby ukazatel na C funkci stál na m´ıstˇe ukazatele na C++ funkci a obrácenˇe, tedy aby tyto konverze byly rozˇs´ıˇren´ım jazyka [1, str. 208]. Kompilátor GCC 9 v´ yˇse uvedené opravdu umoˇzn ˇuje. Je tedy moˇzné ukazatele libovolnˇe zamˇen ˇovat. Dokonce lze do promˇenné typu ukazatel na C funkci pˇriˇradit ukazatel na statickou metodu tˇr´ıdy. Vzhledem k tomu, ˇze toto chován´ı nen´ı pˇrenositelné, bylo by dobré, aby GCC poskytlo pˇri kompilaci nˇejaké varován´ı. Bohuˇzel tomu tak nen´ı, protoˇze GCC pro typy r˚ uzná linkován´ı nerozliˇsuje.10 Ze stejného d˚ uvodu nen´ı 9

N´ azev GCC (GNU Compilers Collection) oznaˇcuje celou sadu kompilátor˚ u. Kompilátor pro C++ z této sady se jmenuje g++. Nadále vˇsak budu pouˇz´ıvat souhrnn´ y název GCC , nebot’ je to bˇeˇzn´ a praxe. 10 To, ˇze GCC nerozliˇsuje typy s r˚ uzn´ ym linkován´ım, je povaˇzováno za chybu, viz GCC Bugzilla – Bug 2316 http://gcc.gnu.org/bugzilla/show_bug.cgi?id=2316

22

ˇ CVUT Praha


napˇr´ıklad moˇzné pˇretˇeˇzovat funkce na základˇe typ˚ u, které se liˇs´ı pouze v linkován´ı.

3.3

Viditelnost funkc´ı

Definice funkc´ı maj´ı v C i C++ globáln´ı viditelnost. Deklarace funkce je vˇsak viditelná jen v dané pˇrekladové jednotce (ve zdrojovém souboru s vloˇzen´ ymi hlaviˇckov´ ymi soubory). Funkci proto m˚ uˇzeme pouˇz´ıt pouze v n´ı. Pokud chceme pouˇz´ıt funkci v jiné pˇrekladové jednotce, neˇz ve které je funkce definována, mus´ıme do zdrojového kódu vloˇzit jej´ı deklaraci. To se zpravidla uˇcin´ı vloˇzen´ım pˇr´ısluˇsného hlaviˇckového souboru. V následuj´ıc´ıch pˇr´ıkladech je vˇsak pouˇzita moˇznost pˇr´ımého napsán´ı deklarace funkce, tj. bez pouˇzit´ı hlaviˇckového souboru. Nˇekdy je vˇsak v´ yhodné znemoˇznit pouˇzit´ı funkce mimo pˇrekladovou jednotku, kde je definována, napˇr´ıklad kv˚ uli skryt´ı implementace ˇci prostému zabránˇen´ı konfliktu jmen. Skryt´ı funkce se v jazyce C++ provede tak, ˇze se funkce um´ıst´ı do bezejmenného (nepojmenovaného, anonymn´ıho) prostoru jmen, jak je vidˇet na ˇrádku 6 následuj´ıc´ıho v´ ypisu (v´ ypis pˇredstavuje dva soubory). Funkci pak nen´ı moˇzné pouˇz´ıt, ani kdyˇz poskytneme pˇr´ısluˇsnou deklaraci. Pˇrekladaˇc ji totiˇz povaˇzuje za jinou funkci. R˚ uzné moˇznosti pˇr´ıstupu k funkc´ım jsou ukázány na následuj´ıc´ım v´ ypisu. Na ˇra´dku 2 je definice funkce a v jiném souboru je jej´ı odpov´ıdaj´ıc´ı deklarace (ve v´ ypisu ˇra´dek 10). Pokud se pokus´ıme pouˇz´ıt funkci, kterou jsme nedeklarovali, pˇrekladaˇc ohlás´ı chybu. Chyba nastane také v pˇr´ıpadˇe, ˇze se pokus´ıme poskytnout deklaraci funkce z bezejmeného prostoru jmen (ˇrádek 12). Deklarovali jsme totiˇz novou funkci, jej´ıˇz definice nen´ı známa. 1

// a . cpp :

2

int function_k ( int a ) { return a ; }

3

int function_l ( int a ) { return a ; }

4

int function_m ( int a ) { return a ; }

5

namespace { int function_n ( int a ) { return a ; }

6 7

}

8 9 10

// b . cpp : int function_k ( int ) ;

23

ˇ CVUT Praha

11


int function_m ( int b ) { return b ; } // error : multiple definition of function_m ( int ) 11

12

int function_n ( int ) ;

13 14

void test_kln () {

15

function_k (0) ;

16

function_l (1) ; // error : function_l was not declared in scope function_n (2) ; // error : undefined reference to

17

function_n ( int ) 18

}

V jazyce C se skryt´ı funkce provede tak, ˇze se do deklarace funkce dopln´ı kl´ıˇcové slovo static. static void function_a ( int ) { }

Viditelnost definice pak bude omezena pouze na danou pˇrekladovou jednotku. Funguje to tedy analogicky jako bezejmen´ y prostor jmen v C++. Nutno poznamenat, ˇze nemá smysl vkládat funkce v bezejmenn´ y prostoru jmen do hlaviˇckov´ ych soubor˚ u. To samé plat´ı i pro funkce deklarované jako static. 3.3.1

Deklarace extern "C" a prostor jmen

Pokud funkci deklarujeme jako extern "C" uvnitˇr nˇejakého prostoru jmen, mus´ıme se na ni odvolávat pomoc´ı prostoru jmen, i kdyˇz má C linkován´ı (to je vidˇet na ˇra´dc´ıch 4, 12 a 18 následuj´ıc´ıho v´ ypisu). Funkci nelze pouˇz´ıt bez specifikace prostoru jmen (ˇrádek 19). Je vˇsak moˇzné poskytnout deklaraci bez specifikace prostoru jmen a to i pˇresto, ˇze funkce byla p˚ uvodnˇe deklarována v prostoru jmen. Funkce se pak pouˇz´ıvá bez specifikace prostoru jmen. Tento postup ukazuj´ı ˇra´dky 5, 14 a 20. Tento postup na funkce s C++ linkován´ım pouˇz´ıt nelze. Pokud se o to pokus´ıme, deklarujeme novou funkci. 1

// a . cpp :

2

namespace foo { 11

Chybové hl´ aˇsky poch´ az´ı z kompilátoru GCC . Stejnˇe je tomu i v následuj´ıc´ım textu.

24

ˇ CVUT Praha


extern " C " {

3 4

int bar () { return 1; }

5

int bar_d ( double ) { return 1; }

6

}

7

void bar_cpp () {}

8

}

9 10

// b . cpp :

11

namespace foo { extern " C " int bar () ;

12 13

}

14

extern " C " int bar_d ( double ) ;

15

void bar_cpp () ; // not namespace foo { void bar_cpp () ; }

16 17

void test_foo_bars () {

18

foo :: bar () ; // ok

19

bar () ;

// error : bar was not declared in this scope

20

bar_d (3) ;

// ok

21

bar_cpp () ;

// error : undefined reference to bar_cpp ()

22

}

Kdybychom v deklaraci na ˇra´dku 14 vynechali extern "C", deklarovali bychom novou funkci (s C++ likován´ım), ke které by chybˇela definice. 3.3.2

Deklerace extern "C" a viditelnost

V C++ se deklarace extern "C" ˇcasto pouˇz´ıvá pro práci s rozhran´ım a spoleˇcn´ ymi hlaviˇckov´ ymi soubory pro C i C++ (viz ˇca´st 3.1). Pokud se deklarace extern "C" pouˇz´ıvá kv˚ uli pˇredáván´ı ukazatel˚ u na funkce nˇejaké C knihovnˇe, m˚ uˇzeme cht´ıt, aby definice funkce nebyla pˇr´ıstupná mimo danou pˇrekladovou jednotku. V C++ se pro omezen´ı pˇr´ıstupu pouˇzije bezejmenn´ y prostor jmen (viz ˇca´st 3.3). Funkce deklarované jako extern "C" vˇsak mohou b´ yt pouˇzity i bez specifikace prostoru jmen (viz ˇca´st 3.3.1). Následuj´ıc´ı v´ ypis ukazuje, jak extern "C" funguje s bezejmenn´ ym prostorem jmen. 1

// a . cpp :

25

ˇ CVUT Praha

2

namespace { extern " C " int bar_i ( int ) { return 1; }

3 4


}

5 6

extern " C " double bar_d ( double ) { return 1; }

7 8

// b . cpp :

9

extern " C " {

10

int bar_i ( int ) ;

11

double bar_d ( double ) ;

12

}

13 14

void test_bars () {

15

bar_i (1) ;

16

bar_d (1.0) ; // ok

17

// ok ?

}

Na ˇrádku 3 je deklarována a definována funkce uvnitˇr bezejmenného prostoru jmen. Pokud by se jednalo pouze o C++ nebylo by moˇzné ji pouˇz´ıt v jiné pˇrekladové jednotce. Avˇsak funkce se ˇr´ıd´ı pravidly jazyka C, a proto je bezejmenn´ y prostor jmen ignorován. Na ˇra´dku 10 poskytneme deklaraci funkce a na ˇrádku 15 ji pouˇzijeme. Kód se sice pˇreloˇz´ı, ale v˚ ubec to nen´ı to, ˇceho jsme chtˇeli dosáhnout, tedy skryt´ı funkce v pˇrekladové jednotce. Funkce deklarovaná v bezejmenném prostoru jmen jako extern "C" se chová stejnˇe, jako kdyby byla deklarována mimo bezejmenn´ y prostor jmen. Vzhledem k tomu, ˇze se jedná o C funkci, nab´ız´ı se ˇreˇsen´ı pomoc´ı kl´ıˇcového slova static (viz ˇcást 3.3). To je ukázáno na následuj´ıc´ım v´ ypisu. Pˇri pˇrekladu dojde k chybˇe (ˇrádek 10), protoˇze definice funkce je nedostupná, a to je pˇresnˇe to, co jsme zam´ yˇsleli. 1

// a . cpp :

2

extern " C " { static void bar_c ( char ) { }

3 4

}

5 6

// b . cpp :

7

extern " C " int bar_c ( char ) ;

26

ˇ CVUT Praha


8 9

void test_bar_c () { bar_c ( ’a ’) ;

10 11

// error : undefined reference to bar_c

}

3.3.3

Pouˇ zit´ı pˇ ri implementaci tˇ r´ıdy SqliteReader

Callback funkce pouˇz´ıvané v SQLite C/C++ API (2.2) je nutné deklarovat jako extern "C", protoˇze SQLite C/C++ API oˇcekává C funkci (viz 3.1). By bylo vhodné skr´ yt callback funkce v pˇrekladové jednotce (viz v´ yˇse). Nelze vˇsak pouˇz´ıt bezejmenn´ y prostor jmen, protoˇze se jedná o C funkce. Pro nˇe je moˇzné pouˇz´ıt deklaraci static. Bohuˇzel se nepodaˇrilo ovˇeˇrit, zda ˇreˇsen´ı, které kombinuje deklarace extern "C" a static, je pˇrenositelné. V GCC daná kombinace funguje pˇresnˇe tak, jak to bylo uvedeno v pˇredcházej´ıc´ıch ˇca´stech. V GCC je implementace C a C++ velmi tˇesnˇe propojena a to je nejsp´ıˇse d˚ uvod, proˇc deklarace extern "C" a static funguj´ı dohromady. Nelze vˇsak spoléhat na to, ˇze s jin´ ymi kompilátory tato kombinace bude také fungovat, a proto bylo pˇri implementaci tˇr´ıdy SqliteReader pouˇzito ˇreˇsen´ı bez pouˇzit´ı kl´ıˇcového slova static. Callback funkce, jejichˇz platnost by bylo dobré omezit jen na danou pˇrekladovou jednotku, jsou dostupné v celém programu. Konfliktu jmen je bránˇeno prefixem yˇce rizika ˇspatného pouˇzit´ı, spoléhá se na dissqlite db v názvu funkc´ı. Co se t´ cipl´ınu programátora. Funkce vlastnˇe nen´ı moˇzné k niˇcemu pouˇz´ıt, protoˇze pracuj´ı s objektem ReaderData, kter´ y je jim nutné pˇredat. Jeho deklarace vˇsak nen´ı mimo implementaci tˇr´ıdy SqliteReader dostupná.

3.4

Pˇ red´ av´ an´ı objekt˚ u

Pˇri práci se SQLite C/C++ API za pouˇzit´ı callback funkc´ı je nutné pˇredávat ukazatel na objekt, se kter´ ym pracujeme a potˇrebujeme ho v callback funkci. Pˇredán´ı se dˇeje pomoc´ı ukazatele na void (viz ˇca´st 2.2). Ukazatel na void m˚ uˇze v C a C++ ukazovat na libovoln´ y typ. Konverze libovolného ukazatele na typ void* je v obou

27

ˇ CVUT Praha


jazyc´ıch implicitn´ı. Konverze z typu void* na jin´ y ukazatel se v C++ provede pomoc´ı operátoru static cast, v C je konverze implicitn´ı. V C se ukazatel na void pouˇz´ıvá tam, kde je tˇreba pˇredávat r˚ uzné typy objekt˚ u. Pˇredán´ı parametru callback funkci tak, jak je tomu v SQLite C/C++ API, je typick´ ym pˇr´ıkladem. Následnˇe je nutné pˇretypovat void* zpˇet na ukazatel na poˇzadovan´ y typ. V C++ se tˇemto konstrukc´ım snaˇz´ıme vyhnout. Avˇsak pˇri práci s knihovnou v C se jim vyhnout nem˚ uˇzeme. Jako pˇr´ıklad dobˇre poslouˇz´ı pouˇzit´ı SQLite C/C++ API (viz 2.2). Zavolán´ı funkce sqlite exec, která volá callback funkci vypadá v pˇr´ıpadˇe funkce následovnˇe. sqlite3_exec ( sqlite3Handle , queryString , readPoints , readerData , & errorMsg ) ;

Pouˇzitá callback funkce readPoints pak m˚ uˇze vypadat tˇreba takto. extern " C " int readPoints ( void * data , int argc , char ** argv , char **) { ReaderData * d = static_cast < ReaderData * >( data ) ; // ... callback ’s code }

Vzhledem k tomu, ˇze funkce pracuje pˇredevˇs´ım s objektem ReaderData, mohla by se tato práce provést v nˇejaké metodˇe tˇr´ıdy (struktury) ReaderData. Callback funkce by pak pouze provedla pˇretypován´ı a zavolala pˇr´ısluˇsnou metodu. Takové funkci se ˇcasto ˇr´ıká trampol´ınová a pokud se budeme ˇr´ıdit t´ım, co je uvedeno v ˇcástech 3.1 a 3.5, stane se C obálkou nad metodou daného objektu. extern " C " int readPoints ( void * data , int argc , char ** argv , char **) { ReaderData * d = static_cast < ReaderData * >( data ) ; d - > readPoints ( argc , argv ) ; }

Poznamenejme, ˇze naˇse C funkce m˚ uˇze zavolat metodu objektu, jen pokud je veˇrejná, nebo pokud je C funkce deklarovaná jako pˇr´ıtel (friend)12 tˇr´ıdy daného 12

V jazyce C++ mohou pˇr´ atelé tˇr´ıd pˇristupovat k jejich soukrom´ ym ˇclen˚ um.

28

ˇ CVUT Praha


objektu. Pˇri deklaraci pˇra´telské funkce s C linkován´ım mus´ıme nejprve deklarovat funkci jako extern "C" a poté ji teprve deklarovat jako pˇr´ıtele tˇr´ıdy. Obˇe deklarace nelze spojit do jedné a je nutné je provést právˇe v tomto poˇrad´ı. extern " C " int readPoints ( void * , int , char ** , char **) ; class ReaderData { // ... friend int readPoints ( void * , int , char ** , char **) ; // ... }

Pˇri implementaci tˇr´ıdy SqliteReader (pˇresnˇeji pˇri implementaci pomocné struktury ReaderData) byla pouˇzita prvn´ı uvedená moˇznost. Zmiˇ novaná C funkce se tedy neomezuje na pouhé zavolán´ı metody pˇr´ısluˇsného objektu, ale vykonává vˇsechny ˇ ast 4 pojednává o tom, jak funkce pˇristupuje k datov´ potˇrebné ˇcinnosti. C´ ym sloˇzkám objektu.

3.5

Zpracov´ an´ı v´ yjimek

Jazyk C++ poskytuje pro zpracován´ı chybov´ ych stav˚ u mechanismus v´ yjimek. Mezi jeho v´ yhody patˇr´ı lepˇs´ı oddˇelen´ı kódu, kter´ y oˇsetˇruje chybov´ y stav, od kódu, kter´ y zajiˇst’uje normáln´ı fungován´ı programu. Dalˇs´ı v´ yhodou v´ yjimek oproti jin´ ym zp˚ usob˚ um práce s chybov´ ymi stavy je to, ˇze nut´ı programátora je oˇsetˇrit (návratov´ y kód lze ignorovat, zat´ımco nezachycená v´ yjimka zp˚ usob´ı pád programu). Jazyk C vˇsak mechanismus v´ yjimek nemá a pro ohlaˇsován´ı a zjiˇst’ován´ı chybov´ ych stav˚ u pouˇz´ıvá jiné metody.13 Pokud v C++ pouˇz´ıváme knihovnu, která je urˇcená pro jazyk C, mus´ıme se s rozd´ıln´ ym pˇr´ıstupem k chybov´ ym stav˚ um vyrovnat. Je totiˇz moˇzné, ˇze námi napsaná funkce bude volána v rámci C knihovny. A to je právˇe pˇr´ıpad callback funkc´ı, kdy ukazatel na naˇsi funkci pˇredáme nˇejaké C funkci, která ji pak pomoc´ı ukazatele zavolá. Pokud by v naˇs´ı funkci doˇslo k vyvolán´ı v´ yjimky a ona v´ yjimka by opustila tˇelo naˇs´ı funkce, zp˚ usobilo by to pád programu z d˚ uvodu nezachycené v´ yjimky. 13

V jazyce C sice existuj´ı rozˇs´ıˇren´ı, která umoˇzn ˇuj´ı práci s v´ yjimkami, ale tato ˇreˇsen´ı rozhodnˇe

nejsou pˇrenositeln´ a.

29

ˇ CVUT Praha


Moˇzn´ y v´ ystup programu pˇreloˇzeném pomoc´ı GCC je na následuj´ıc´ım v´ ypisu. terminate called after throwing an instance of ’ std :: runtime_error ’ what () :

some error message

Z uvedeného vypl´ yvá, ˇze callback funkce mus´ı vˇsechny v´ yjimky, které v n´ı byly vyvolány, zachytit. Kód v tˇele callback funkce, kter´ y m˚ uˇze vyvolat v´ yjimku, mus´ı b´ yt obalen blokem try-catch. Bloky catch mus´ı zachytit kaˇzdou v´ yjimku vyvolanou v bloku try, takˇze posledn´ım catch blokem mus´ı b´ yt catch blok s v´ ypustkou. Jednoduchá ukázka je na následuj´ıc´ım v´ ypisu. 1

int someCallback ( int a ) {

2

// can not throw exception

3

try { // can throw exception

4 5

}

6

catch ( std :: exception & e ) { // handle exception

7 8

}

9

catch (...) { // handle unknown exception

10

}

11 12

}

Stále ovˇsem zb´ yvá vyˇreˇsit, jak nahlásit, ˇze doˇslo k v´ yjimce. Nahláˇsen´ı je nutné provést ve stylu jazyka C. Knihovna, se kterou pracujeme, by mˇela m´ıt definovan´ y nˇejak´ y zp˚ usob, jak callback funkce ohlaˇsuj´ı, ˇze doˇslo k chybˇe. V pˇr´ıpadˇe SQLite C/C++ API je to návratov´ y kód (viz 2.2). Toto ˇreˇsen´ı vˇsak neobsahuje zp˚ usob, jak zjistit, ke které v´ yjimce doˇslo. I kdyˇz v pˇr´ıpadˇe návratového kódu lze napˇr´ıklad pˇriˇradit r˚ uzn´ ym v´ yjimkám r˚ uzné návratové kódy. To ovˇsem nen´ı moc pohodlné ˇreˇsen´ı a jeˇstˇe nen´ı zaruˇceno, ˇze nám knihovn´ı funkce návratov´ y kód callback funkce sdˇel´ı. Zcela jinou moˇznost´ı, jak se zbavit problém˚ u s v´ yjimkami pˇri práci s C knihovnou, je v´ yjimky v˚ ubec nepouˇz´ıvat. T´ım bychom se ovˇsem pˇripravili o v´ yhody pouˇz´ıvan´ı v´ yjimek. A v pˇr´ıpadˇe, ˇze pouˇz´ıváme kód, kter´ y nem˚ uˇzeme zmˇenit a v´ yjimky vyvolávat m˚ uˇze (napˇr´ıklad standardn´ı knihovnu C++), nemáme jinou moˇznost neˇz 30

ˇ CVUT Praha


v´ yjimky zachytávat (alespoˇ n pomoc´ı catch s v´ ypustkou). Jak se v´ yjimky oˇsetˇruj´ı v implementaci tˇr´ıdy SqliteReader a jak lze zabránit ztrátˇe informace o tom, jaká v´ yjimka byla vyvolána, pojednává ˇcást 5.

3.6

Komplexn´ı ˇ reˇ sen´ı pomoc´ı ˇ sablon a maker

Pouˇzit´ı SQLite C/C++ API (viz 2.2) s callback funkcemi vede k tomu, ˇze je tˇreba napsat nˇekolik podobn´ ych funkc´ı. Funkce jsou podobné v tom, ˇze tˇelo kaˇzdé funkce mus´ı obsahovat tent´ yˇz kód. Jedná se pˇredevˇs´ım o kód, kter´ y zajist´ı odchytáván´ı v´ yjimek a kter´ y nemus´ı b´ yt triviáln´ı (viz ˇca´st 5). D˚ uvody, proˇc tomu tak mus´ı b´ yt, jsou uvedeny v ˇca´stech 3.4 a 3.5. Kód callback funkc´ı lze tedy rozdˇelit na spoleˇcn´ y kód a kód, kter´ y vykonává operace t´ ykaj´ıc´ı se pˇr´ımo u ´ˇcelu dané funkce. Spoleˇcn´ y kód je tedy moˇzné pˇresunout do jedné funkce. Vzhledem k tomu, ˇze kód chceme pˇridat jiˇz bˇehem kompilace, je ideáln´ım ˇreˇsen´ım pouˇzit´ı ˇsablonové funkce. Jej´ım parametrem bude ukazatel na konkrétn´ı funkci, kterou chceme obalit kódem, kter´ y odchytává vˇsechny v´ yjimky. Nejprve uved’me dva typy ukazatel˚ u na funkce. Jak bylo uvedeno v ˇca´sti 3.2, jedná se o rozd´ılné typy. 1

extern " C " typedef int (* CCallbackType ) ( void * , int , char ** , char **) ;

2 3

typedef int (* CppCallbackType ) ( void * , int , char ** , char **) ;

4

Následuje kód ˇsablonové funkce, která zajist´ı odchycen´ı v´ yjimek. Kód je znaˇcnˇe zjednoduˇsen a ponechávám také stranou, zda je ˇsablonov´ ym parametrem hodnota typu CCallbackType ˇci CppCallbackType. 1

template < CallbackType callback > int Data :: sa ve Ca llb ac kC al le r ( void * data , int argc ,

2 3

char ** argv ,

4

char ** cnames )

5

{

6

Data * p = static_cast < Data * >( data ) ;

7

try {

8

return callback (p , argc , argv , cnames ) ;

31

ˇ CVUT Praha


}

9

catch ( Exception & e ) {

10

// ... store an exception in p

11

}

12

catch (...) {

13

// ... store an exception in p

14

}

15

return 1;

16

}

17

V callback funkci lze bez jak´ ychkoli okolk˚ u vyvolávat v´ yjimky. D´ıky tomu, ˇze je obalena uvedenou ˇsablonovou funkc´ı, nedojde k pádu programu. Jak m˚ uˇze vypadat základ callback funkce je uvedeno na následuj´ıc´ım v´ ypisu. 1

int Data :: readPoints ( void * data , int argc , char ** argv , char ** cnames ) {

2 3

// ... do something

4

// can throw exception

5

return 0; }

6

Pokud funkce sqlite3 exec pomoc´ı návratového kódu nahlás´ı, ˇze doˇslo k chybˇe, je nutné zpracovat informace o uloˇzené v´ yjimce. Vzhledem k tomu, bylo by vhodné obalit i funkci sqlite3 exec funkc´ı, které se o zpracován´ı postará. Tato obálka m˚ uˇze zajistit napˇr´ıklad znovu vyvolán´ı v´ yjimky ˇci vyvolán´ı v´ yjimky v pˇr´ıpadˇe chyby databáze. Ve v´ ypisu funkce exec (obálky funkce sqlite3 exec) ponechávám jen kód t´ ykaj´ıc´ı se pˇredáván´ı ukazatele na callback funkci (kód, kter´ y zpracovává v´ yjimky lze naj´ıt v ˇcásti 5.3). 1

void Data :: exec ( sqlite3 * sqlite3Handle ,

2

const std :: string & query ,

3

CCallbackType callback , void * data )

4

{

5

// ...

6

int rc = sqlite3_exec ( sqlite3Handle , query . c_str () , callback , data , & errorMsg ) ;

7

// ...

8 9

}

32

ˇ CVUT Praha


Kdybychom zapomnˇeli, ˇze CCallbackType a CppCallbackType jsou jiné datové typy, mohli bychom funkci exec pouˇz´ıvat následovnˇe. exec ( sqlite3Handle , query , saveCallbackCaller < readPoints > , this ) ;

Dokonce bychom mohli zmˇenit i funkci exec na ˇsablonovou. Jako parametr ˇsablony by samozˇrejmˇe mˇela hodnotu ukazatele na callback funkci. Nic z toho vˇsak nen´ı ˇ moˇzné kv˚ uli rozd´ılnosti typ˚ u CCallbackType a CppCallbackType. Sablonov´ e funkce mus´ı m´ıt nutnˇe C++ linkován´ı, a proto ukazatel na nˇe nelze pouˇz´ıt jako ukazatel na C funkci. Pro pouˇzit´ı s C je nutné kaˇzdou instanci ˇsablonové funkce obalit do funkce, které je deklarována jako extern "C". 1

extern " C " { int c_readPoints ( void * data , int argc ,

2

char ** argv , char ** cnames ) {

3

return Data :: saveCallbackCaller < Data :: readPoints >

4

( data , argc , argv , cnames ) ;

5

}

6 7

}

Uvedené obalen´ı nelze ze zˇrejm´ ych d˚ uvod˚ u automatizovat pomoc´ı ˇsablon. Lze vˇsak pouˇz´ıt makro. 1

# define I M P L E M E N T _ C _ C A L L B A C K ( FUNCTION_NAME ) int c_ \

2

# # FUNCTION_NAME \

3

( void * data , int argc , char ** argv , char ** cnames ) { return Data :: saveCallbackCaller < Data ::\

4

FUNCTION_NAME \

5

>( data , argc , argv , cnames ) ; }

Makro vytvoˇr´ı funkci s C linkován´ım, která zavolá funkci, jenˇz je instanc´ı ˇsablony zajiˇst’uj´ıc´ı, ˇze ˇzádná v´ yjimka neopust´ı tˇelo dané funkce. Pouˇzit´ı makra je jednoduché (volán´ı makra nen´ı ukonˇceno stˇredn´ıkem vzhledem k tomu, ˇze definice funkce stˇredn´ıkem nekonˇc´ı). Parametrem je název funkce, kterou potˇrebujeme obalit. IMPLE M E N T _ C _ C A L L B A C K ( c a l l b a c k _ r e a d C l u s t e r s )

Pouˇzit´ı funkce, které je v´ ysledkem práce makra je oˇcekávané. 33

ˇ CVUT Praha

´ IMPLEMENTACE 4 SOUKROMA

exec ( sqlite3Handle , query , c_callback_readPoints , this ) ;

Nutno ˇr´ıci, ˇze vzhledem k tomu, ˇze bylo stejnˇe pouˇzito makro, by bylo moˇzné nepouˇz´ıt ˇsablonovou funkci v˚ ubec a nahradit ji makrem. To by ale makro velmi prodlouˇzilo. Pouˇzit´ı ˇsablony je bezpeˇcnˇejˇs´ı a obecnˇe doporuˇcované ˇreˇsen´ı problému tohoto typu. V´ yjimku zachycenou v tˇele callback funkce je vhodné nˇejak´ ym zp˚ usobem uloˇzit a pˇr´ıpadnˇe ji ve vhodn´ y okamˇzik zase vyvolat. O tom, jak to provést, pojednává ˇca´st 5. Toto ˇreˇsen´ı nebylo v koneˇcné implementaci tˇr´ıdy SqliteReader pouˇzito. D˚ uvodem je jeho obt´ıˇzná pochopitelnost pro ˇctenáˇre kódu.

4

Soukrom´ a implementace

V C++ je pravidlem, které se vˇetˇsinou dodrˇzuje, ˇze datové ˇcleny tˇr´ıd se deklaruj´ı jako soukromé. Tyto soukromé ˇcleny jsou sice nedostupné, ale jsou stále viditelné. Pokud je chceme opravdu skr´ yt m˚ uˇzeme pouˇz´ıt soukromou implementaci. Soukromá imlementace (Private Implementation, Pimpl ) b´ yvá nˇekdy zaˇrazována mezi návrhové vzory. Tˇr´ıda SqliteReader má v objektu soukromé implementace vˇsechny datové ˇcleny. Avˇsak obecnˇe lze do soukromé implementace um´ıstit i vˇsechny soukromé metody. Tˇr´ıda SqliteReader obsahuje ukazatel na strukturu typu ReaderData, kter´ y je implementaˇcn´ım objektem. Pˇri deklaraci tˇr´ıdy se soukromou implementac´ı, lze vyuˇz´ıt dopˇredné deklarace (forward declaration). Pouˇzit´ı pak vypadá následovnˇe. 1

// sqlitereader . h :

2

struct ReaderData ; // forward declaration

3 4

class SqliteReader

5

{

6

public :

7

// ...

8

private :

9

// ...

34

ˇ CVUT Praha

ReaderData * readerData ; // pointer to private data

10 11

´ IMPLEMENTACE 4 SOUKROMA

};

D´ıky dopˇredné deklaraci je moˇzné pouˇz´ıt ukazatel na strukturu ReaderData, avˇsak to, jak skuteˇcnˇe struktura vypadá, z˚ ustává skryto. Deklarace struktury je aˇz v implementaˇcn´ım souboru. Pˇr´ıstup k jej´ım ˇclen˚ um je proto moˇzn´ y jen tam. Obecnˇe b´ yvá v´ yhodné deklarovat strukturu v privátn´ı ˇca´sti tˇr´ıdy. Pro SqliteReader tomu tak ale nen´ı. Je totiˇz nutné, aby ke struktuˇre a jej´ım ˇclen˚ um mˇeli pˇr´ıstup callback funkce, které nejsou a nem˚ uˇzou b´ yt jej´ımi metodami. Implementaˇcn´ı objekt je deklarován skuteˇcnˇe jako struktura (struct) se vˇsemi ˇcleny veˇrejn´ ymi. Mimo jiné právˇe kv˚ uli callback funkc´ım. Pokud bychom strukturu ReaderData deklarovali jako soukromou a vnoˇrenou ve tˇr´ıdˇe SqliteReader a ve struktuˇre ReaderData zavedli soukromou ˇca´st, callback funkce bychom museli deklarovat jako pˇra´telské. Pˇrátelstv´ı bychom museli deklarovat jak ve tˇr´ıdˇe SqliteReader, kv˚ uli pˇr´ıstupu k soukromé struktuˇre ReaderData, tak i ve struktuˇre ReaderData, kv˚ uli pˇr´ıstupu k jej´ım soukrom´ ym ˇclen˚ um. Alternativnˇe bychom mohli vybavit strukturu ReaderData sadou pˇr´ıstupov´ ych funkc´ı. To vˇse je vˇsak zbyteˇcná komplikace. Callback funkce vlastnˇe hraj´ı roli metod struktury ReaderData, a proto k n´ı maj´ı pˇr´ıstup. Ze stejného d˚ uvodu maj´ı pˇr´ıstup i k jej´ım soukrom´ ym sloˇzkám. Pˇri pouˇzit´ı soukromé implementace je nutné vyˇreˇsit kop´ırován´ı a pˇriˇrazen´ı, aby se nestalo to, ˇze dva objekty budou sd´ılet stejn´ y implementaˇcn´ı objekt (to obvykle totiˇz nen´ı naˇs´ım c´ılem). Tˇr´ıda SqliteReader má zakázan´ y kop´ırovac´ı konstruktor a operátor pˇriˇrazen´ı. Kop´ırován´ı nedává v jej´ım pˇr´ıpadˇe smysl, protoˇze reprezentuje jeden zdroj (jeden databázov´ y soubor a spojen´ı s n´ım). Kop´ırován´ı implementaˇcn´ıho objektu je t´ımto pro tˇr´ıdu SqliteReader vyˇreˇseno. Mezi v´ yhody soukromé implementace patˇr´ı velik´ y stupeˇ n oddˇelen´ı rozhran´ı od implementace. D´ıky pouˇzit´ı dopˇredné deklarace nen´ı nutné, aby hlaviˇckov´ y soubor vkládal jiné hlaviˇckové soubory kv˚ uli tomu, aby mohl m´ıt datové sloˇzky dan´ ych typ˚ u. Tyto hlaviˇckové soubory se vkládaj´ı aˇz do implementaˇcn´ıho souboru. Dalˇs´ı ˇcasto uvádˇenou v´ yhodou je rychlejˇs´ı kompilace. Tato v´ yhoda se vˇsak projev´ı jen u vˇetˇs´ıch tˇr´ıd a projekt˚ u. Nev´ yhodou soukromé implementace je pˇredevˇs´ım vˇetˇs´ı sloˇzitost kódu.

35

ˇ CVUT Praha

´ ´ 5 POLYMORFNÍ PRACE S VYJIMKAMI

Pouˇzité soukromé implementace se podobá vytvoˇren´ı obálky kolem jiné tˇr´ıdy. Soukromá impleplementace b´ yvá také oznaˇcována jako Pointer to Implementation ˇci Private Class Data. Souvis´ı také s návrhov´ ym vzorem Most (Bridge). Pˇri implementaci tˇr´ıdy SqliteReader byla vˇsak pouˇzita v´ yˇse popsaná základn´ı podoba soukromé implementace.

5

Polymorfn´ı pr´ ace s v´ yjimkami

Základem pro polymorfn´ı práci s v´ yjimkami je klonován´ı (cloning). Informace o nˇem lze z´ıskat napˇr´ıkad z [1, str. 424]

5.1

Klonov´ an´ı

V pˇr´ıpadˇe, ˇze potˇrebujeme kop´ırovat objekt, jehoˇz pˇresn´ y typ neznáme (máme jen referenci ˇci ukazatel), nem˚ uˇzeme pouˇz´ıt kop´ırovac´ı konstruktor. Ten totiˇz nen´ı a nem˚ uˇze b´ yt virtuáln´ı a to nám zabraˇ nuje pracovat polymorfnˇe. Jeho pouˇzit´ı, vˇedomé ˇci nevˇedomé, m˚ uˇze vést k oˇrezán´ı (dˇelen´ı) objektu (slicing). Následuj´ıc´ı v´ ypis ukazuje, jak snadno dojde k oˇrezán´ı objektu, tj. zavolá se kop´ırovac´ı konstruktor základn´ı tˇr´ıdy, i kdyˇz pracujeme s odvozenou. K zavolán´ı kop´ırovac´ıho konstruktoru dojde, kdyˇz objekt pˇredáváme hodnotou. Nov´ y objekt bude vˇzdy objektem základn´ı tˇr´ıdy nehledˇe na to, jak´ ym byl ten p˚ uvodn´ı. Pˇriprav´ıme se tak o polymorfn´ı chován´ı. Jak je také vidˇet, pˇredáváme-li objekt referenc´ı, ke kop´ırován´ı nedojde, a tak nedojde ani k oˇrezán´ı. 1

class Base {

2

public :

3

virtual ~ Base () { }

4

virtual std :: string name () { return " Base " ; }

5

};

6

class Derived : public Base {

7

public : virtual std :: string name () { return " Derived " ; }

8 9

};

10

36

ˇ CVUT Praha

11

void print_val ( Base b ) { std :: cout << " name is " << b . name () << std :: endl ;

12 13 14

} void print_ref ( Base & b ) { std :: cout << " name is " << b . name () << std :: endl ;

15 16


}

17 18

void test () {

19

Derived d ;

20

print_val ( d ) ; // prints : name is Base

21

print_ref ( d ) ; // prints : name is Derived

22

}

M˚ uˇze se vˇsak stát, ˇze objekt mus´ıme korektnˇe zkop´ırovat, i kdyˇz nev´ıme jeho pˇresn´ y typ. A tak tomu také je, kdyˇz chceme ukládat v´ yjimky (viz téˇz 3.5). M´ısto kop´ırován´ı je v tomto pˇr´ıpadˇe nutné pouˇz´ıt klonován´ı (cloning). Pˇri klonovan´ı voláme m´ısto kop´ırovac´ıho konstruktoru virtuáln´ı funkci, která volá kop´ırovac´ı konstruktor nového objektu. Virtuáln´ı funkce zná skuteˇcn´ y typ objektu a zavolá tedy správn´ y kop´ırovac´ı konstruktor. Klonovac´ı funkce zpravidla vytváˇr´ı nov´ y objekt pomoc´ı new a vrac´ı ukazatel na nov´ y objekt (pˇridˇelenou pamˇet’ uvolˇ nuje volaj´ıc´ı). Pˇredchoz´ı pˇr´ıklad je v následuj´ıc´ım v´ ypisu pˇrepsan´ y tak, aby funkce pouˇzitá na ˇra´dku 23 (následuj´ıc´ıho v´ ypisu) mˇela vlastn´ı kopii objektu. D´ıky klonován´ı ji má a zároveˇ n se jedná objekt správného typu (tedy opravdu o kopii p˚ uvodn´ıho objektu). 1

class Base {

2

public :

3


4

virtual Base * clone () { return new Base (* this ) ; }

5


6

};

7


8

public : virtual Derived * clone () { return new Derived (* this ) ; }

9

virtual std :: string name () { return " Derived " ; }

10 11

};

12

37

ˇ CVUT Praha

13

void print_val ( Base * b ) { std :: cout << " name is " << b - > name () << std :: endl ;

14 15 16

} void print_ref ( Base & b ) { std :: cout << " name is " << b . name () << std :: endl ;

17 18


}

19 20

void test () {

21

Derived d ;

22

Base * b = d . clone () ;

23

print_val ( b ) ; // prints : name is Derived

24

print_ref ( d ) ; // prints : name is Derived

25

delete b ;

26

}

Pokud zároveˇ n v základn´ı tˇr´ıdˇe oznaˇc´ıme kop´ırovac´ı konstruktor za chránˇen´ y, znemoˇzn´ıme t´ım okol´ı kop´ırovat objekty a d´ıky tomu také nem˚ uˇze doj´ıt k nechtˇenému oˇrezán´ı objektu. Kaˇzd´ y potomek základn´ı tˇr´ıdy mus´ı definovat klonovac´ı metodu. Vzhledem k tomu, ˇze základn´ı tˇr´ıda bude nejsp´ıˇse tˇr´ıdou abstraktn´ı nic nebrán´ı tomu, aby klonovac´ı metoda byla ˇcistˇe virtuáln´ı. D´ıky tomu kaˇzd´ y pˇr´ım´ y potomek naˇs´ı základn´ı tˇr´ıdy bude muset definovat vlastn´ı klonovac´ı metodu.14 Obdobn´ ym postupem, jak´ y se pouˇzije pˇri klonován´ı, je moˇzné tvoˇrit nové objekty obecnˇe, nikoli jen kopie (klony). Dokonce tak lze ˇreˇsit i u ´plnˇe jiné vˇeci, jako je napˇr´ıklad vyvoláván´ı v´ yjimek (viz následuj´ıc´ı ˇca´st).

5.2

Ukl´ ad´ an´ı a vyvol´ av´ an´ı v´ yjimek

Standardn´ı zpracován´ı v´ yjimek vypadá následovnˇe. Nˇekde uvnitˇr bloku try se vyvolá v´ yjimka, napˇr´ıklad uvnitˇr volán´ı nˇejaké funkce. Samotného vyvolán´ı se dosáhne pˇr´ıkazem throw. V´ yjimka poté putuje tak dlouho neˇz se dostane k pˇr´ısluˇsnému bloku catch, kter´ y ji zachyt´ı. D˚ uleˇzité pˇritom je, ˇze v´ yjimky by se mˇely vyvolávat hodnotou a zachytávat odkazem. 14

Jak vidno, nen´ı zajiˇstˇeno, ˇze nepˇr´ım´ y potomek definuje svou vlastn´ı klonovac´ı metodu. Jak

zajistit s vyuˇzit´ım nevirtu´ aln´ıho rozhran´ı, ˇze potomci své vlastn´ı klonovac´ı metody definuj´ı, je pops´ ano v [4, typy 39 a 54].

38

ˇ CVUT Praha


Následuje v´ ypis, kde jsou dvˇe tˇr´ıdy, které budu pouˇz´ıvat v dalˇs´ıch pˇr´ıkladech. Budu je pouˇz´ıvat jako tˇr´ıdy v´ yjimek. Obsahuj´ı metody pro klonován´ı a pro snadné zjiˇstˇen´ı typu. 1

class Base {

2

public :

3


4

virtual Base * clone () { return new Base (* this ) ; }

5


6

};

7


8

public : virtual Derived * clone () { return new Derived (* this ) ; }

9

virtual std :: string name () { return " Derived " ; }

10 11

};

Obˇe uvedené tˇr´ıdy maj´ı veˇrejn´ y kop´ırovac´ı konstruktor (dopln´ı jej pˇrekladaˇc). Veˇrejn´ y kop´ırovac´ı konstruktor je nutn´ y k tomu, aby v´ yjimka mohla b´ yt vyvolána pomoc´ı throw. Jak vypadá standardn´ı zpracován´ı v´ yjimek, je uvedeno na následuj´ıc´ım jednoduchém v´ ypise. Poznamenejme, ˇze na poˇrad´ı blok˚ u catch záleˇz´ı. 1

try { throw Derived () ;

2 3 4

} catch ( Derived & e ) { std :: cout << " Derived exception " << std :: endl ;

5 6 7

} catch ( Base & e ) { std :: cout << " Base exception " << std :: endl ;

8 9

}

Ted’ ovˇsem uvaˇzme moˇznost, uvedenou v ˇcásti 3.5. Totiˇz tu, kdy potˇrebujeme vˇsechny v´ yjimky zachytit a jeˇstˇe pˇredat informaci o tom, jaká v´ yjimka byla zachycena. Ideáln´ım ˇreˇsen´ım je vytvoˇrit kopii zachycené v´ yjimky, nˇekam si ji uloˇzit (napˇr´ıklad do objektu, se kter´ ym právˇe pracujeme) a posléze (aˇz bude kontrola nad bˇehem programu zase v naˇsich rukou) si ji odtud zase vyzvednout. Kopii vˇsak nem˚ uˇzeme vytvoˇrit kop´ırovac´ım konstruktorem, protoˇze neznáme pˇresn´ y typ 39

ˇ CVUT Praha


v´ yjimky. Ten bychom znali, jen kdyˇz bychom mˇeli blok catch pro kaˇzd´ y typ v´ yjimky. To ale nen´ı dobré ˇreˇsen´ı. Mus´ıme znát vˇsechny typy v´ yjimek a nav´ıc vˇzdy, kdyˇz se do hierarchie v´ yjimek pˇridá nová, mus´ıme ji pˇridat i sem. Klonován´ı je ˇreˇsen´ım naˇseho problému. Aniˇz bychom museli zjiˇst’ovat pˇresn´ y typ v´ yjimky z´ıskáme jej´ı pˇresnou kopii (viz téˇz ˇca´st 5.1). Následuj´ıc´ı v´ ypis demonstruje naklonován´ı v´ yjimky. 1

Base * a = 0;

2


3 4 5

} catch ( Base & e ) { a = e . clone () ;

6 7 8

} if ( a ) { std :: cout << a - > name () << std :: endl ; // prints : Derived

9

delete a ;

10 11

}

Nicménˇe, to, ˇze v´ yjimku ukládáme a dokáˇzeme z n´ı pˇreˇc´ıst u ´daje, jeˇstˇe nemus´ı staˇcit. Je totiˇz moˇzné, ˇze v´ yjimku budeme muset znovu vyvolat, a to proto, ˇze nen´ı jasné, jak s n´ı naloˇzit. Napˇr´ıklad v pˇr´ıpadˇe tˇr´ıdy SqliteReader nen´ı jasné, jak hlásit chybu uˇzivateli programu. Pokus o vyvolán´ı pomoc´ı pˇr´ımo pomoc´ı throw se vˇsak nesetká s u ´spˇechem. Následuj´ıc´ı v´ ypis vycház´ı z pˇredchoz´ıho. Pˇridává jeˇstˇe dalˇs´ı blok try-catch. Ten pˇredstavuje klientsk´ y kód. P˚ uvodn´ı, vnitˇrn´ı blok try-catch pˇredstavuje kód, ze kterého nem˚ uˇzeme vyvolat v´ yjimku, avˇsak chceme ji zaznamenat. 1

try {

2

Base * a = 0;

3


4 5 6

} catch ( Base & e ) { a = e . clone () ;

7 8 9 10

} if ( a ) { throw * a ;

40

ˇ CVUT Praha

delete a ;

11

}

12 13 14

} catch ( Derived & e ) { std :: cout << " Derived exception \ n " ; // unused

15 16 17


} catch ( Base & e ) { std :: cout << " Base exception \ n " ; // prints : Base

18

exception 19

}

D˚ uvodem proˇc byla zachycena základn´ı v´ yjimka a ne odvozená je ten, ˇze pˇr´ıkaz throw zp˚ usob´ı volán´ı kop´ırovac´ıho konstruktoru. Pˇrekladaˇc vˇsak nezná skuteˇcn´ y typ objektu a pouˇzije kop´ırovac´ı konstruktor základn´ı tˇr´ıdy. Dojde tedy k oˇrezán´ı objektu (viz 5.1). Je tedy nutné v´ yjimku nejen polymorfnˇe zkop´ırovat, ale i vyvolat. Kv˚ uli tomu je potˇreba zavést dalˇs´ı virtuáln´ı metodu. Ta je v mnohém podobná klonovac´ı metodˇe. Vhodné jméno je raise. Mus´ı ji implementovat kaˇzdá tˇr´ıda z hierarchie v´ yjimek. Implementace je pro kaˇzdou tˇr´ıdu stejná. virtual void raise () const { throw * this ; }

Pro opˇetovné vyvolán´ı v´ yjimky pak pouˇzijeme nam´ısto pˇr´ıkazu throw metodu raise. ˇ adek ˇc´ıslo 10 v´ R´ ypisu, kter´ y demonstroval opˇetovné vyvoláván´ı v´ yjimek, se zmˇen´ı, jak je ukázáno na následuj´ıc´ım ˇra´dku kódu. a - > raise () ;

V´ yjimka, která bude vyvolána, bude m´ıt správn´ y typ, tj. typ kter´ y odpov´ıdá p˚ uvodn´ı, dˇr´ıve zachycené a uloˇzené v´ yjimce.

5.3

Implementace ve tˇ r´ıdˇ e SqliteReader

V gama-local je jedna základn´ı tˇr´ıda, ze které se odvozuj´ı vˇsechny ostatn´ı tˇr´ıdy v´ yjimek15 . Tou tˇr´ıdou je GNU gama::Exception::base. Identifikátory GNU gama a 15

Stejn´ a tˇr´ıda je z´ akladn´ı i pro v´ yjimky knihovny Matvec

41

ˇ CVUT Praha


Exception oznaˇcuj´ı prostory jmen16 . Tato tˇr´ıda dˇed´ı z tˇr´ıdy std::exception, základn´ı tˇr´ıdy v´ yjimek ve standardn´ı knihovnˇe. To znamená, ˇze stejnˇe jako std::exception má virtuáln´ı destruktor a virtuáln´ı metodu what a je tedy polymorfn´ı tˇr´ıdou. Dále deklaruje dalˇs´ı dvˇe virtuáln´ı metody, metodu clone a metodu raise. Obˇe metody jsou ˇcistˇe virtuáln´ı a tˇr´ıda Exception::base je tedy abstraktn´ı tˇr´ıdou. D´ıky tomu, ˇze je tˇr´ıda Exception::base odvozena z std::exception, je moˇzné (pokud vyvstane potˇreba) odchytávat vˇsechny v´ yjimky, tj. v´ yjimky ze standardn´ı knihovny i knihovny GNU Gama, jedin´ ym blokem catch. A zároveˇ n bude dostupná metoda what a tedy i odpov´ıdaj´ıc´ı chybová zpráva. Tˇr´ıda v´ yjimek, kterou pouˇz´ıvá tˇr´ıda SqliteReader a jej´ı implementace, se jmenuje Exception::sqlitexc. Tˇr´ıda Exception::sqlitexc nedˇed´ı pˇr´ımo z abstaktn´ı tˇr´ıdy Exception::base, ale je potomkem tˇr´ıdy Exception::string, která pˇridává datov´ y ˇclen obsahuj´ıc´ı pˇredávanou zprávu ve formˇe ˇretˇezce a dále implementuje funkci what tak, aby vrátila tento ˇretˇezec. 1

// inderr . h :

2

namespace GNU_gama { namespace Exception {

3

class base : public std :: exception

4

{

5

public :

6

virtual base * clone () const = 0;

7

virtual void };

8 9

raise () const = 0;

}}

10 11

// exception . h :

12


13

class string : public base {

14

public :

15

const std :: string

16

string ( const std :: string & s ) : str ( s ) { } 16

str ;

Prostor jmen GNU gama nebudu dále uvádˇet, prostor jmen Exception vˇsak ano.

42

ˇ CVUT Praha


17

~ string () throw () {}

18

string *

clone () const { return new string (* this ) ; }

19

void

raise () const { throw * this ; }

20

const char * what ()

const throw () { return

str . c_str () ; } };

21 22

}}

23 24

// sqlitereader . h :

25


26

class sqlitexc : public GNU_gama :: Exception :: string

27

{

28

public : sqlitexc ( const std :: string & message )

29 30

: string ( message )

31

{ }

32

sqlitexc * clone () const { return new sqlitexc (* this ) ; }

33

void };

34 35

raise () const { throw * this ; }

}}

Základn´ı kód callback funkce je na následuj´ıc´ım v´ ypisu. Pokud dojde k vyvolán´ı v´ yjimky, v´ yjimka bude zachycena jedn´ım ze tˇr´ı blok˚ u catch. V´ yjimky odvozené od Exception::base budou zachyceny prvn´ım blokem, kter´ y provede klonován´ı a uloˇz´ı ukazatel na novou v´ yjimku do dat tˇr´ıdy SqliteReader (pˇresnˇeji do struktury ReaderData). Pokud v´ yjimka nen´ı odvozena od Exception::base, ale je odvozena od std::exception (jej´ı rozhran´ı neumoˇzn ˇuje klonován´ı), bude m´ısto n´ı uloˇzena v´ yjimka typu Exception::string. Jako ˇretˇezec obsahuj´ıc´ı zprávu j´ı bude nastavena zpráva poskytnutá metodou what. Blok catch s v´ ypustkou pak zachyt´ı vˇsechny ostatn´ı chyby. Uloˇzena bude opˇet v´ yjimka typu Exception::string. Jako zpráva ji bude nastaven ˇretˇezec udávaj´ıc´ı, ˇze doˇslo k neznámé (neoˇcekávané) v´ yjimce v callback funkci. 1

int readSomething ( void * data , int argc , char ** argv , char **)

2

{

3

ReaderData * d = static_cast < ReaderData * >( data ) ;

43

ˇ CVUT Praha


try {

4 5

// ... callback ’s code

6

return 0; }

7

catch ( GNU_gama :: Exception :: base & e ) {

8

d - > exception = e . clone () ;

9

}

10

catch ( std :: exception & e ) {

11

d - > exception =

12

new GNU_gama :: Exception :: string ( e . what () ) ;

13

}

14

catch (...) {

15

d - > exception =

16

new GNU_gama :: Exception :: string ( " unknown " ) ;

17

}

18

return 1;

19 20

}

Funkce exec z implementace tˇr´ıdy SqliteReader, která obaluje volán´ı knihovn´ı yjimky. Ve v´ ypisu je vyfunkce sqlite3 exec, zajist´ı opˇetovné vyvolán´ı uloˇzené v´ nechán kód, kter´ y se net´ yká opˇetovného vyvolán´ı v´ yjimky. 1

void exec ( sqlite3 * sqlite3Handle , const std :: string & query ,

2

S q l i t e R e a d e r C a l l b a c k T y p e callback ,

3

ReaderData * readerData )

4

{

5

char * errorMsg = 0;

6

int rc = sqlite3_exec ( sqlite3Handle , query . c_str () , callback , readerData , & errorMsg ) ;

7

if ( rc != SQLITE_OK ) {

8

if ( readerData - > exception != 0) {

9

readerData - > exception - > raise () ;

10

}

11

// ...

12

}

13 14

}

44

ˇ CVUT Praha

6

ˇ ÍDA SQLITEREADER A JEJÍ IMPLEMENTACE 6 TR

Tˇ r´ıda SqliteReader a jej´ı implementace

Tˇr´ıda SqliteReader zajiˇst’uje ˇcten´ı dat z databáze SQLite v programu gama-local . Tˇr´ıda je um´ıstˇena v prostoru jmen sqlite db, kter´ y je souˇca´st´ı prostoru jmen GNU gama::local. V prostoru jmen local, kter´ y je souˇcást´ı prostoru jmen GNU gama, je um´ıstˇena vˇetˇsina tˇr´ıd a funkc´ı, které se t´ ykaj´ı programu gama-local . Definice tˇr´ıdy je v hlaviˇckovém souboru sqlitereader.h. Jej´ı implementace je ve zdrojovém souboru sqlitereader.cpp. Oba soubory lze z´ıskat spoleˇcnˇe s ostatn´ımy zdrojov´ ymi kódy projektu GNU Gama (viz 1), nebo samostatnˇe z následuj´ıc´ı adresy. http://git.savannah.gnu.org/cgit/gama.git/tree/lib/gnu_gama/local/ Dokumentace tˇr´ıdy SqliteReader a jej´ı implementace je v dokumentaˇcn´ıch komentáˇr´ıch, které jsou souˇca´st´ı zdrojov´ ych kód˚ u. Dokumentace je v anglickém jazyce. Pro vytvoˇren´ı dokumentace ve formˇe HTML stránek a PDF dokumentu byl pouˇzit program Doxygen. Zkrácená verze PDF dokumentu je v pˇr´ıloze B.

6.1

Rozhran´ı

Rozhran´ı tˇr´ıdy tvoˇr´ı konstruktor, kter´ y pˇreb´ırá jeden parametr typu std::string reprezentuj´ıc´ı název databázového souboru, a metoda retrieve. Metoda retrieve naˇcte konfiguraci uloˇzenou v databázi do objektu typu LocalNetwork. Metoda pˇreb´ırá jako parametr referenci na ukazatel na objekt typu LocalNetwork. Dalˇs´ı parametr je typu std::string a reprezentuje jméno konfigurace, která je uloˇzena v databázi. To, ˇze je prvn´ı parametr (nekonstantn´ı) reference, umoˇzn ˇuje metodˇe zmˇenit hodnotu ukazatele. K tomu dojde ve chv´ıli, kdy je metodˇe pˇredán nulov´ y ukazatel (NULL). V tomto pˇr´ıpadˇe bude vytvoˇren nov´ y objekt tˇr´ıdy LocalNetwork na základˇe algoritmu, kter´ y je uloˇzen v databázi.17 T´ım je programu gama-local umoˇznˇeno, aby pokud uˇzivatel nezadá algoritmus, pouˇzil ten, kter´ y je uloˇzen v databázi, nam´ısto toho, aby pouˇzil implicitn´ı algoritmus. Hlaviˇcky konstruktoru a metody retrieve ukazuje následuj´ıc´ı v´ ypis. SqliteReader ( const std :: string & fileName ) ; 17

Tˇr´ıda LocalNetwork je abstraktn´ı. Konkrétn´ı tˇr´ıdy se liˇs´ı podle pouˇzitého algoritmu, takˇze je

moˇzné je vytv´ aˇret, jen pokud ho zn´ ame.

45

ˇ CVUT Praha


void retrieve ( LocalNetwork *& lnet , const std :: string & configuration ) ;

Jako tˇr´ıda v´ yjimek pro hláˇsen´ı chyb vznikl´ ych pˇri ˇcten´ı z databáze slouˇz´ı tˇr´ıda Exception::sqlitexc.

6.2

Implementace

Ve tˇr´ıdˇe je vyuˇzita technika soukromé implementace, popsaná v ˇca´sti 4, proto má pouze jeden datov´ y ˇclen, kter´ y je soukrom´ y. Tento datov´ y ˇclen je typu ReaderData. Tˇr´ıda ReaderData je definována v souboru sqlitereader.cpp a je souˇcás´ı prostoru jmen sqlite db. Soubor sqlitereader.h obsahuje pouze dopˇrednou deklaraci tˇr´ıdy ReaderData. Tˇr´ıda SqliteReader nemá ˇza´dné soukromé metody. Do implementace tˇr´ıdy patˇr´ı kromˇe tˇr´ıdy ReaderData také funkce v bezejmenném prostoru jmen (v souboru sqlitereader.cpp) a pˇredevˇs´ım callback funkce, pomoc´ı kter´ ych prob´ıhá ˇcten´ı z databáze. Tˇr´ıda SqliteReader zajiˇst’uje spojen´ı s databáz´ı. Pˇritom vyuˇz´ıvá techniku RAII (resource acquisition is initialization) popsanou napˇr´ıklad v [1, str. 366]. Technika spoˇc´ıvá v tom, ˇze se zdroj alokuje pˇri inicializaci objektu a uvoln´ı se pˇri jeho destrukci. V naˇsem pˇr´ıpadˇe to znamená, ˇze konstruktor tˇr´ıdy ReaderData otev´ırá databázi (funkc´ı sqlite3 open) a destruktor databázi uzav´ırá (funkc´ı sqlite3 close). A vzhledem k tomu, ˇze konstruktor v pˇr´ıpadˇe ne´ uspˇeˇsného pokusu o otevˇren´ı databáze vyvolá v´ yjimku, nem˚ uˇze se stát, ˇze bychom nevˇedomky pracovali s neotevˇrenou databáz´ı. Podobnˇe d´ıky tomu, ˇze uzavˇren´ı databáze probˇehne automaticky v destruktoru, nem˚ uˇze se stát, ˇze bychom databázi nezavˇreli. K uzavˇren´ı dojde i v pˇr´ıpadˇe, ˇze byla vyvolána v´ yjimka. Destruktor bude zavolán automaticky a d´ıky nˇemu i funkce sqlite3 close. Ukazatel na databázov´ y objekt obsahuje samozˇrejmˇe tˇr´ıda ReaderData. Protoˇze je ke komunikaci s databáz´ı pouˇzito SQLite C/C++ API (rozhran´ı s callback funkcemi), bylo tˇreba dbát na správné propojen´ı jazyk˚ u C a C++, kter´ ym se zab´ yvá ˇcást 3. Konkrétn´ı implementace pro tˇr´ıdy SqliteReader a ReaderData je podrobnˇeji rozebrána v ˇcásti 3.3.3. Názvy callback funkc´ı zaˇc´ınaj´ı sqlite db , aby se zabránilo konfliktu jmen a 46

ˇ CVUT Praha


pˇr´ıpadnˇe ˇspatnému poˇzit´ı. Prefix sqlite db je odvozen z názvu prostoru jmen, ve kterém jsou um´ıstˇeny tˇr´ıdy SqliteReader a ReaderData.

18

Obecné informace o callback funkc´ıch pouˇz´ıvan´ ych v SQLite C/C++ API jsou uvedeny v ˇca´sti 2.2. Oˇsetˇren´ı v´ yjimek vznikl´ ych v callback funkc´ıch je udˇeláno tak, jak popisuje ˇca´st 5.3. V´ yjimky zachycené v callback funkc´ıch jsou ukládány ve tˇr´ıdˇe ReaderData a znovu vyvolávány ve funkci exec. Ta je obálkou kolem funkce sqlite3 exec. Vˇsechny callback funkce v implementaci tˇr´ıdy SqliteReader oˇcekávaj´ı, ˇze jim pomoc´ı ukazatele na void bude pˇredán objekt typu ReaderData. Kaˇzdá callback funkce vˇsak oˇcekává objekt ReaderData v jiném stavu. Podle toho lze callback funkce rozdˇelit do dvou skupin. V prvn´ı skupinˇe jsou následuj´ıc´ı funkce (uveden je jen název – návratovou hodnotu a parametry maj´ı vˇsechny callback funkce stejné). sqlite db readConfigurationInfo sqlite db readConfigurationText sqlite db readPoints sqlite db readClusters Funkce zapisuj´ı r˚ uzné hodnoty do objektu tˇr´ıdy LocalNetwork, na kter´ y je ve tˇr´ıdˇe ReaderData ukazatel. Funkce proto oˇcekávaj´ı, ˇze tento ukazatel je platn´ y. Ve druhé skupinˇe jsou funkce, které zapisuj´ı u ´daje do urˇcit´ ych objekt˚ u v objektu tˇr´ıdy LocalNetwork. Pˇr´ıkladem takov´ ych objekt˚ u m˚ uˇzou b´ yt objekty typu StandPoint ˇci CovMat. Callback funkce samy o sobˇe vˇsak nev´ı, do jakého objektu maj´ı zapisovat. Proto je nutné pˇredat jim tuto informaci. K tomu dobˇre poslouˇz´ı ukazatel uloˇzen´ y v objektu tˇr´ıdy ReaderData, kter´ y se callback funkc´ım pˇredává. Tento ukazatel mus´ı nastavit volaj´ıc´ı funkce exec (kter´ y je vlastnˇe nepˇr´ım´ ym volaj´ıc´ım callback funkce). Nab´ız´ı se otázka, proˇc nepˇredávat do callback funkc´ı pomoc´ı ukazatele na void pˇr´ımo ukazatel na zpracovávan´ y objekt. Odpovˇed’ je prostá. Nebylo by totiˇz moˇzné v callback funkci ukládat v´ yjimky, protoˇze by nebylo by kam. Následuje seznam callback funkc´ı, které jsou v popsané skupinˇe. 18

Callback funkce, které jsou pouˇz´ıvané v SQLite C/C++ API a maj´ı tedy C linkován´ı, sice

mohou b´ yt um´ıstˇeny v prostoru jmen, ale nezabrán´ı to pˇr´ıpadnému konfliktu jmen.

47

ˇ CVUT Praha


sqlite db readObservations sqlite db readVectors sqlite db readCoordinates sqlite db readHeightDifferences sqlite db readCovarianceMatrix

6.3

Integrace do gama-local

Aby mohla b´ yt tˇr´ıda SqliteReader zaˇclenˇena do projektu GNU Gama konkrétnˇe v programu gama-local , bylo nutné provést provést urˇcité u ´pravy ve stávaj´ıc´ım kódu. V prvn´ı ˇradˇe musela b´ yt vylepˇsena hierarchie v´ yjimek. Pˇredevˇs´ım byly pˇridány metody clone a raise, pro umoˇznˇen´ı polymorfn´ı práce s v´ yjimkami. Jak vypadá ta ˇca´st hierarchie v´ yjimek, která se t´ yká tˇr´ıdy SqliteReader, je uvedeno v ˇca´sti 5.3. Musela b´ yt také zmˇena funkce main programu gama-local , která se nacház´ı v souboru bin/gama-local.cpp. Byl pˇridán kód, kter´ y na základˇe parametr˚ u pˇredan´ ych programu v pˇr´ıkazové ˇrádce naˇcte u ´daje z databáze pomoc´ı tˇr´ıdy SqliteReader, nebo naˇcte u ´daje z XML souboru, tak jako tomu bylo v dˇr´ıvˇejˇs´ıch verz´ıch. Do projektu byla také pˇridána jednoduchá továrn´ı metoda, chcete-li funkce, newLocalNetwork. Ta na základˇe názvu algoritmu vytvoˇr´ı nov´ y objekt, kter´ y je instanc´ı jedné ze tˇr´ıd odvozen´ ych ze tˇr´ıdy LocalNetwork. Právˇe na základˇe názvu algoritmu je rozhodnuto, jaká konkrétn´ı tˇr´ıda bude pouˇzita. K zaveden´ı továrn´ı metody vedl fakt, ˇze v nˇekter´ ych pˇr´ıpadech mus´ı b´ yt nov´ y objekt vytvoˇren ve funkci main programu gama-local a jindy mus´ı b´ yt vytvoˇren v jedné z metod tˇr´ıdy SqliteReader. Deklarace továrn´ı metody newLocalNetwork následuje. LocalNetwork * newLocalNetwork ( std :: string algorithm = " " ) ;

Parametrem je název algoritmu. Názvy se shoduj´ı s názvy, které jsou pouˇzity v parametrech pˇr´ıkazové ˇrádky. Pokud je ˇretˇezec prázdn´ y nebo je název neplatn´ y, je ˇretˇezec nahrazen ˇretˇezcem "gso". Deklarace továrn´ı metody newLocalNetwork je v souboru newnetwork.h a je um´ıstˇena do prostoru jmen GNU gama::local. Definice je v souboru newnetwork.cpp. V´ yhodou tohoto ˇreˇsen´ı je, ˇze pro vytváˇren´ı objekt˚ u tˇr´ıd odvozen´ ych ze tˇr´ıdy LocalNetwork jiˇz nen´ı potˇreba vkládat definice vˇsech tˇechto tˇr´ıd. Dalˇs´ı v´ yhodou je to, ˇze kód, kter´ y rozhoduje o vytvoˇren´ı konkrétn´ı tˇr´ıdy na základˇe názvu algoritmu, je na jednom m´ıstˇe a zároveˇ n m˚ uˇze b´ yt zavolán 48

ˇ CVUT Praha

´ Í 7 TESTOVAN

z v´ıce funkc´ı. Toto byl vlastnˇe d˚ uvod zaveden´ı jednoduché továrn´ı metody. Nutno jeˇstˇe poznamenat, ˇze volaj´ıc´ı kód nemus´ı znát deklarace konkrétn´ıch tˇr´ıd, protoˇze pouˇz´ıvá továrn´ı metodu. Jak jiˇz bylo uvedeno v ˇcásti 2, projekt GNU Gama se snaˇz´ı o minimáln´ı závislost na jin´ ych knihovnách. Projekt GNU Gama pouˇz´ıvá pro sestaven´ı na operaˇcn´ıch systémech Unixového typu sestavovac´ı systém GNU Autotools 19 . Tento systém umoˇzn ˇuje sestavit projekt GNU Gama i v pˇr´ıpadˇe, ˇze knihovna SQLite nen´ı na daném poˇc´ıtaˇci nainstalována. Pˇri samotném sestavován´ı zdrojov´ ych kód˚ u se pak podpora databáze SQLite v˚ ubec nevytvoˇr´ı a to d´ıky podm´ınˇenému pˇrekladu. Vˇsechny ˇca´sti kódu, které se t´ ykaj´ı podpory databáze, jsou mezi direktivami preprocesoru #ifdef GNU GAMA LOCAL SQLITE READER a #endif. Jedná se o obsah hlaviˇckového souboru sqlitereader.h, zdrojového souboru sqlitereader.cpp a nˇekteré ˇca´sti souboru bin/gama-local.cpp. V pˇr´ıpadˇe, ˇze nen´ı definováno makro (identifikátor) GNU GAMA LOCAL SQLITE READER, nebudou ˇcásti t´ ykaj´ıc´ı se podpory SQLite databáze do pˇrekladu zahrnuty. O tom, zda má b´ yt makro definováno rozhodne právˇe systém GNU Autotools. Vˇetˇsinu kódu potˇrebného k integraci tˇr´ıdy SqliteReader napsal autor projektu ˇ GNU Gama a vedouc´ı této práce, prof. Ing. Aleˇs Cepek, CSc..

7

Testov´ an´ı

Testován´ı je d˚ uleˇzité pro kaˇzd´ y program. Pro program gama-local je d˚ uleˇzitˇejˇs´ı o to, ˇze si uˇzivatel programu vˇetˇsinou nem˚ uˇze nijak ovˇeˇrit, ˇze v´ ysledky, které mu program poskytl, jsou správné. V´ yvoj tˇr´ıdy SqliteReader – stejnˇe jako v´ yvoj celého projektu GNU Gama – prob´ıhá pod systémy z rodiny GNU/Linux . D´ıky lze pˇri testován´ı vyuˇz´ıt ˇradu moˇznost´ı, které tyto systémy nab´ız´ı. Kontrola správnosti byla provedena dvˇema zp˚ usoby. Jeden vyuˇz´ıvá program diff (viz 7.2) a druh´ y vyuˇz´ıvá program gama-local-cmp (viz 7.3). Pˇr´ımo bˇehem v´ yvoje se vyuˇzily moˇznosti kompilátoru GCC (viz 7.1). Dále se samozˇrejmˇe také pouˇz´ıvaly, ne pˇr´ıliˇs uznávané, avˇsak hojnˇe vyuˇz´ıvané, orientaˇcn´ı testy pomoc´ı textov´ ych v´ ypis˚ u vˇseho druhu. 19

http://autotoolset.sourceforge.net/

49

ˇ CVUT Praha

7.1

´ Í 7 TESTOVAN

Kontroly pomoc´ı kompil´ atoru GCC

Kompilátory C++ nejen upozorˇ nuj´ı na chyby, kv˚ uli kter´ ym nelze kód sestavit, ale jsou také schopny poskytnout varován´ı, která mohou upozornit na problematick´ y kód.20 Jak je uvedeno v [4], v C++ je velmi vhodné pouˇz´ıvat kontroly bˇehem kompilace. Ty jsou moˇzné napˇr´ıklad proto, ˇze C++ je staticky typovan´ y jazyk. Autoˇri toto shrnuj´ı do dvou pravidel (1 a 14). Kompilujte bez varován´ı i pˇri vysoké citlivosti kompilátoru. Chyby pˇri sestavován´ı jsou lepˇs´ı neˇz chyby pˇri bˇehu. Kompilátor GCC nab´ız´ı ˇradu nastaven´ı, kter´ ymi lze ˇr´ıdit kontroly bˇehem kompilace. Lze urˇcit, v jak´ ych pˇr´ıpadech má kompilátor podat varovnou zprávu, a lze také urˇcit, jaká varován´ı se maj´ı stát chybami, ˇc´ımˇz si lze na programátorovi vynutit dodrˇzen´ı dodrˇzen´ı prvnˇe jmenovaného pravidla. Pˇri v´ yvoji tˇr´ıdy SqliteReader byla pouˇzita celá ˇrada nastaven´ı kompilátoru GCC . Jejich kompletn´ı seznam je uveden v pˇr´ıloze C. Tato nastaven´ı vyvolaj´ı ˇradu varovn´ ych hláˇsen´ı, která ˇcasto pouze upozorˇ nuj´ı na nedodrˇzen´ı jist´ ych dobr´ ych zvyk˚ u (napˇr´ıklad nastaven´ı -Weffc++). Projekt GNU Gama nen´ı kompilován s tak citliv´ ym nastaven´ım kompilátoru, jako bylo pouˇzito pro v´ yvoj tˇr´ıdy SqliteReader. Niˇzˇs´ı citlivost kompilátoru vˇsak nen´ı nutnˇe chybou. Napˇr´ıklad v´ yˇse zm´ınˇené nastaven´ı -Weffc++ nut´ı v nˇekter´ ych pˇr´ıpadech explicitnˇe inicializovat objekt typu std::string prázdn´ ym ˇret’ezcem (""), aˇckoli je tato inicializace implicitn´ı. Pouˇzit´ı zmiˇ novan´ ych nastaven´ı pˇri kompilaci projektu GNU Gama by zp˚ usobilo velké mnoˇzstv´ı varovn´ ych hláˇsen´ı, ve kter´ ych by se snadno ztratila varovná hláˇsen´ı zp˚ usobená nov´ ym, vyv´ıjen´ ym kódem. Avˇsak tˇr´ıda SqliteReader byla vyv´ıjena v samostatném projektu a projekt GNU Gama byl pouˇzit jiˇz zkompilovan´ y v podobˇe knihovny. To by vˇsak samo o sobˇe nestaˇcilo ke skryt´ı vˇsech varován´ı zp˚ usoben´ ych stávaj´ıc´ım kódem projektu GNU Gama, protoˇze vˇzdy je tˇreba vkládat hlaviˇckové soubory. Nejnovˇejˇs´ı verze kompilátoru GCC (4.6) umoˇzn ˇuje skr´ yt varován´ı z hlaviˇckov´ ych soubor˚ u pomoc´ı pomoc´ı direktivy #pragma. 20

Dnes uˇz podobné schopnosti maj´ı i editory, napˇr´ıklad program Qt Creator, kter´ y jsem pouˇz´ıval

pˇri v´ yvoji. Program Qt Creator vˇsak nenab´ız´ı takové moˇznosti kontroly jako kompilátor GCC .

50

ˇ CVUT Praha

´ Í 7 TESTOVAN

Ve verzi 4.4, kterou pouˇz´ıvám já, tato moˇznost nen´ı, avˇsak je moˇzné pˇripojit pˇri kompilaci hlaviˇckové soubory jako systémové, coˇz skryje varován´ı z takto pˇripojen´ ych hlaviˇckov´ ych soubor˚ u. Hlaviˇckové soubory se pˇripoj´ı jako systémové tak, ˇze m´ısto obvyklého -I se pˇred cestu k soubor˚ um nap´ıˇse -isystem, v mém pˇr´ıpadˇe tedy -isystem../gama/lib. Dalˇs´ı moˇznost´ı, jak se zbavit varovn´ ych hláˇsen´ı je filtrovat hláˇsen´ı pomoc´ı programu grep. Toto ˇreˇsen´ı vˇsak nefunguje tak dobˇre, jako kdyˇz se pouˇzije pˇr´ımo kompilátor. V manuálu ke kompilátoru GCC [3] je pro programy v C a C++ doporuˇceno toto nastaven´ı: -ansi -pedantic -Wall -Wextra -Wconversion -Wshadow -Wcast-qual -Wwrite-strings Z tˇechto nastaven´ı zde pro zaj´ımavost vysvˇetl´ım pouze dvˇe. Nastaven´ı -Wconversion zp˚ usob´ı varován´ı, pˇri konverzi z double na int. A nastaven´ı -Wshadow zp˚ usob´ı varován´ı, kdyˇz lokáln´ı promˇenná zakryje sv´ ym jménem jinou promˇenou. Jeˇstˇe je vhodné poznamenat, ˇze nastaven´ı -Wextra je stejné jako nastaven´ı -W. Oznaˇcen´ı -W je vˇsak zastaralé. Jak jiˇz bylo uvedeno, pˇri v´ yvoji tˇr´ıdy SqliteReader bylo pouˇzito v´ıce nastaven´ı (viz pˇr´ıloha C). Nastaven´ı doporuˇcená manuálem jsou vˇsak ta nejuˇziteˇcnˇejˇs´ı. Nicménˇe ˇzádn´ y kompilátor nem˚ uˇze zachytit vˇsechny chyby, proto je vˇzdy nutné provádˇet testován´ı.

7.2

Testov´ an´ı pomoc´ı programu diff

Program diff je jedn´ım z mal´ ych jedno´ uˇcelov´ ych program˚ u pouˇz´ıvan´ ych na unixov´ ych systémech, jin´ ymi slovy patˇr´ı mezi takzvané unixové utility. Program umoˇzn ˇuje porovnat mezi sebou dva textové soubory. Testován´ı programu gama-local spoˇc´ıvá v tom, ˇze se programem gama-local spoˇc´ıtá s´ıt’. Pˇri tom se je jako v´ ystupn´ı formát nastav´ı prost´ y textov´ y soubor. V´ ypoˇcet se provede dvakrát. Jednou se data ˇctou z XML souboru a jednou z databáze SQLite. Z kaˇzdého v´ ypoˇctu je tedy jeden textov´ y soubor. Tyto soubory se následnˇe porovnaj´ı programem diff . Pro hromadné testován´ı byl vytvoˇren skript pro bash. Ten obsahuje i pˇr´ıkazy, které vytvoˇr´ı a napln´ı SQLite databázi. Jako testovac´ı data byla pouˇzita sb´ırka 51

ˇ CVUT Praha

´ Í 7 TESTOVAN

pˇr´ıklad˚ u, která je souˇca´st´ı projektu GNU Gama, s v´ yjimkou tˇech pˇr´ıklad˚ u, které zp˚ usobuj´ı problémy pˇri vyrovnán´ı.21 Porovnán´ı programem diff má vˇsak jisté nev´ yhody. Nev´ yhodu, která se projevuje nejˇcastˇeji, je to, ˇze porovnává jednotlivé znaky, nikoli hodnoty v souborech. V textovém v´ ystupu se vˇsak nˇekdy stává, ˇze nˇejaká veliˇcina má sice v obou souborech hodnotu nula, ale tato nula má v jednom souboru znaménko kladné a ve druhém záporné (je to dáno t´ım, jak funguje textov´ y v´ ystup v jazyce C++ a v programu gama-local ). Program diff takovéto soubory oznaˇc´ı jako rozd´ılné a v´ ysledkem testu je, ˇze se v´ ypoˇcty liˇsily, aˇckoli byly stejné. Dále se m˚ uˇze stát, v d˚ usledku numerického ˇsumu, ˇze v´ ysledné hodnoty nebudou v textov´ ych souborech ve stejném poˇrad´ı. V souborech se bude liˇsit poˇrad´ı ˇra´dk˚ ua program diff je opˇet oznaˇc´ı jako rozd´ılné, i kdyˇz se v´ ysledky v´ ypoˇct˚ u neliˇs´ı. Dalˇs´ı nev´ yhoda plyne z pouˇzit´ı textového formátu jako v´ ystupu z programu gama-local . Hodnoty v tomto v´ ystupu jsou totiˇz zaokrouhlené, a tak je moˇzné, ˇze nebudou odhaleny malé rozd´ıly ve v´ ysledn´ ych hodnotách. Mohlo by se zdát, ˇze by problém byl vyˇreˇsen pouˇzit´ım soubor˚ u ve formátu XML. To by ovˇsem zp˚ usobilo jen dalˇs´ı problémy. Hodnoty v XML souborech nejsou totiˇz v˚ ubec zaokrouhlené. To zp˚ usob´ı, ˇze ˇc´ıslo, které m˚ uˇzeme vzhledem k pˇresnosti, s jakou prob´ıhá v´ ypoˇcet v programu a s jakou se poˇc´ıtá v geodézii, povaˇzovat za nulu, bude vyjádˇreno dvˇema ˇ adky s tˇemito ˇc´ısly program diff samozˇrejmˇe oznaˇc´ı jako zcela odliˇsn´ ymi ˇc´ısly. R´ rozd´ılné. D˚ usledkem by opˇet bylo oznaˇcen´ı shodn´ ych v´ ypoˇct˚ u za neshodné. I pˇres jmenované nev´ yhody je porovnán´ı v´ ystupn´ıch soubor˚ u v textovém formátu pomoc´ı programu diff u ´ˇcinnou testovac´ı technikou a bylo donedávna jedin´ ym zp˚ usobem, jak´ ym se provádˇelo hromadné testován´ı programu gama-local . Program diff naˇsel rozd´ıly v mnoha textov´ ych souborech, avˇsak vˇetˇsina tˇechto rozd´ıl˚ u byla dána pouze r˚ uzn´ ym zápisem hodnot (viz v´ yˇse). V nˇekolika pˇr´ıpadech se vˇsak jednalo o skuteˇcné rozd´ıly ve v´ ysledc´ıch. Následuj´ıc´ı ˇca´st 7.3 tyto rozd´ıly rozeb´ırá. 21

Pˇr´ıklady lze z´ıskat, stejnˇe jako zdrojové kódy, ze stránek projektu [14]. Problematick´ ym kon-

figurac´ım se vˇenuje pr´ ace [6].

52

ˇ CVUT Praha

7.3

´ Í 7 TESTOVAN

Testov´ an´ı pomoc´ı programu gama-local-cmp

Program gama-local-cmp je souˇca´st´ı diplomové práce [6]. Z n´ı a také od jej´ıho autora Ing. Gabriela Györiho jsem ˇcerpal znalosti o funkcionalitˇe programu a zp˚ usobu pouˇzit´ı. Program gama-local-cmp umoˇzn ˇuje porovnat dva XML soubory s v´ ysledky vyrovnán´ı z programu gama-local . Program porovnává hodnoty naˇctené z XML soubor˚ u a urˇcuje jejich rozd´ıly. S pomoc´ı programu gama-local-cmp je moˇzné sledovat posuny v geodetick´ ych s´ıt´ı, avˇsak stejnˇe tak je vhodn´ y i k testován´ı v´ ysledk˚ u vyrovnán´ı programem gama-local . Lze jej vyuˇz´ıt ke zjiˇstˇen´ı rozd´ıl˚ u ve v´ ypoˇctu r˚ uzn´ ymi algoritmy nebo r˚ uzn´ ymi verzemi programu gama-local (tak byl pouˇzit i ve zmiˇ nované diplomové práci [6]). Zde je program pouˇzit pro zjiˇstˇen´ı rozd´ıl˚ u ve vyrovnán´ı, kdy jednou je vstupem XML soubor a jednou data z databáze. Program gama-local-cmp vypisuje vˇsechny rozd´ıly, které jsou vˇetˇs´ı neˇz 1e-09. Samotné testován´ı prob´ıhalo stejnˇe jako s programem diff (viz 7.2). Jen skript pro bash musel b´ yt ˇcásteˇcnˇe pozmˇenˇen. Testy ukázaly jisté rozd´ıly mezi v´ ysledky vyrovnán´ı, kde vstupem byl XML soubor, a vyrovnán´ı, kde vstupem byla databáze SQLite. Tyto rozd´ıly byly pouze u prvk˚ u kovarianˇcn´ı matice. V´ ysledné souˇradnice a vyrovnaná mˇeˇren´ı vˇcetnˇe jejich doplˇ nuj´ıc´ıch u ´daj˚ u se ve vˇsech testovan´ ych souborech shodovala. Absolutn´ı hodnoty rozd´ıl˚ u byly ˇrádu 1e-04 a menˇs´ı. Následné zv´ yˇsen´ı pˇresnosti v´ ypisu prvk˚ u kovarianˇcn´ı matice pˇri generovan´ı v´ ystupn´ıho XML souboru22 rozd´ıly mezi hodnotami zmenˇsilo tak, ˇze byly nejv´ yˇse ˇrádu 1e-06, vˇetˇsinou vˇsak 1e-09. Po celou dobu testován´ı byla pˇresnost v´ ypis˚ u nastavena na 20 desetinn´ ych m´ıst, coˇz je zbyteˇcnˇe vysoká hodnota, avˇsak vyluˇcuje chybu pˇri v´ ypisu. Aby byl pˇri dalˇs´ım testován´ı práce s databáz´ı vylouˇcen vliv nového kódu (tj. tˇr´ıdy SqliteReader), byl pouˇzit program na pˇrevod u ´daj˚ u uloˇzen´ ych v databázi SQLite do vstupn´ı dávky XML. Tento program se pouˇz´ıvá pouze pro u ´ˇcely testován´ı a jmenuje se sql2xml. Testován´ı spoˇc´ıvalo v tom, ˇze nejprve se pˇrevedl testovaná konfigurace uloˇzená v XML souboru do SQL dávky (pˇrevod zajiˇst’uje program gamalocal-xml2sql ). Touto dávkou byla následnˇe naplnˇena databáze. Z databáze byla konfigurace pˇrenesena zpˇet do XML programem sql2xml. Obˇe vstupn´ı dávky byly 22

Zmˇena se t´ yk´ a tˇr´ıdy LocalNetworkXML, metody write v souboru localnetowork.cpp.

53

ˇ CVUT Praha

´ Í 7 TESTOVAN

postupnˇe vyrovnány programem gama-local . XML soubory s v´ ysledky vyrovnán´ı byly porovnány pomoc´ı programu gama-local-cmp. Porovnán´ı opˇet ukázalo rozd´ıly. V dokumentace databáze SQLite [12] je uvedeno, byt’ ponˇekud v jiné souvislosti, ˇze pˇresnost ˇc´ısel s plovouc´ı desetinou ˇcárkou (REAL) je 15 platn´ ych cifer.23 Také pokusy, které jsem provedl s SQLite C/C++ API a v pˇr´ıkazové ˇrádce SQLite, ukázaly, ˇze pˇri uloˇzen´ı je ˇc´ıslo zaokrouhleno na 15 platn´ ych cifer. To ukázalo na to, ˇze rozd´ıly by mohly vznikat pˇri ukládán´ı hodnot do databáze. Zkoumán´ı jednotliv´ ych krok˚ u pˇri pˇrevádˇen´ı dat toto také potvrdilo. Pro zjiˇst’ován´ı chybn´ ych pˇrevod˚ u jsem vytvoˇril konfiguraci, kde je s´ıt’ tvoˇrena jen tˇremi body (dva jsou známé, jeden neznám´ y). Aby byl vyˇcerpán poˇcet platn´ ych cifer, tak jsem jako souˇradnice znám´ ych bod˚ u jsem zvolil velké hodnoty. Zde je ukázka jednoho bodu. <point id=’1’ x=’600154980.484654321’ y=’100644898.590654321’ fix=’xy’/> ˇ ısla maj´ı 18 platn´ C´ ych cifer. Do databáze se vˇsak uloˇz´ı pouze 15, zbytek se ztrat´ı. Tato oˇrezaná ˇc´ısla se pˇri pˇrevodu uloˇz´ı do XML souboru (ukázka následuje). <point id=’1’ x=’600154980.484654’ y=’100644898.590654’ fix=’xy’/> V´ ysledky vyrovnán´ı programem gama-local se kv˚ uli rozd´ıl˚ u ve vstupn´ıch souborech také liˇs´ı. Program gama-local-cmp v tomto konkrétn´ım pˇr´ıpadˇe zjistil rozd´ıly v ˇra´du 1e-07. Rozd´ıly jsou v souˇradnic´ıch vypoˇcteného bodu a samozˇrejmˇe také v souˇradnic´ıch pevn´ ych bod˚ u. Na základˇe v´ yˇse uveden´ ych poznatk˚ u lze rozd´ıly v´ ysledk˚ u vyrovnán´ı (pˇri ˇcten´ı u ´daj˚ u z XML a pˇri ˇcten´ı u ´daj˚ u z databáze) vysvˇetlit t´ım, ˇze pˇri ukládán´ı ˇc´ısel do databáze SQLite docház´ı k zaokrouhlen´ı24 . To se následnˇe projev´ı jak pˇri naˇc´ıtán´ı u ´daj˚ u pomoc´ı tˇr´ıdy SqliteReader, tak i pˇri pouˇzit´ı soubor˚ u z´ıskan´ ych programem sql2xml. 23

K pˇresnosti uloˇzen´ı ˇc´ısel je nutné jeˇstˇe poznamenat, ˇze zp˚ usob uloˇzen´ı ˇc´ısel v C++ je závisl´ y

na implementaci. Norma C++ [2] pouze zaruˇcuje jisté minimáln´ı poˇzadavky, které mus´ı splˇ novat dan´ y typ. 24 Jak uk´ azaly testy, datab´ aze SQLite ˇc´ısla pˇri ukládán´ı neoˇrezává, ale zaokrouhluje.

54

ˇ CVUT Praha

´ Í 7 TESTOVAN

Rozd´ıly v souˇradnic´ıch se vˇsak projevily pouze v testovac´ım souboru vytvoˇreném pro tento u ´ˇcel. Ve skuteˇcn´ ych konfigurac´ıch (ze sb´ırky pˇr´ıklad˚ u projektu GNU Gama) se vˇsak rozd´ıly ve vypoˇcten´ ych hodnotách projevily pouze u prvk˚ u kovarianˇcn´ı matice. Rozd´ıly jsou malé a tak nejsou v´ ysledky vyrovnán´ı znehodnoceny. K velikosti rozd´ıl˚ u prvk˚ u kovarianˇcn´ı matice je jeˇstˇe nutné poznamenat, ˇze program gama-local-cmp poˇc´ıtá a posuzuje absolutn´ı rozd´ıl dvou prvk˚ u. Avˇsak hodnoty prvk˚ u v kovarianˇcn´ı matici jsou ˇrádovˇe r˚ uzné, v závislosti na dané konfiguraci (vˇetˇsinou od 1e-02 do 1e+03). Posuzován´ı pˇresnosti t´ım zp˚ usobem, ˇze se prvky odeˇctou a rozd´ıl porovná s hodnotou 1e-09, m˚ uˇze v pˇr´ıpadˇe mal´ ych hodnot prvk˚ u vést k pˇrehlédnut´ı chyby a v pˇr´ıpadˇe velk´ ych hodnot naopak k oznaˇcen´ı chyby tam, kde nenastala.

55

ˇ CVUT Praha

´ ER ˇ ZAV

Z´ avˇ er C´ılem této bakaláˇrské práce bylo rozˇs´ıˇrit program gama-local o funkcionalitu, která umoˇzn´ı ˇcten´ı dat pˇr´ımo z databáze SQLite. Data pˇreˇctená z databáze jsou ukládána pˇr´ımo do datov´ ych struktur, které program gama-local pouˇzije pro vyrovnán´ı lokáln´ı geodetické s´ıtˇe. D˚ uleˇzité bylo implementovat ˇcten´ı dat z databáze na takové u ´rovni, aby novou funkcionalitu bylo moˇzné zapojit do projektu GNU Gama. Pro ˇcten´ı dat z databáze SQLite bylo pouˇzito nativn´ı rozhran´ı (SQLite C/C++ API). Konkrétnˇe ta ˇca´st rozhran´ı, kde se vyuˇz´ıvaj´ı callback funkce. Rozhran´ı je urˇceno jak pro jazyk C, tak i pro jazyk C++. Jeho pouˇzit´ı má jistá specifika, která plynou z rozd´ıl˚ u obou jazyk˚ u. Tato práce se jim zevrubnˇe vˇenuje. Novou funkcionalitu bylo nutné otestovat. Pro u ´ˇcely testován´ı bylo vytvoˇreno nˇekolik skript˚ u pro bash, které vyuˇz´ıvaj´ı programy diff a gama-local-cmp. Jako testovac´ı data byla pouˇzita témˇeˇr celá sb´ırka pˇr´ıklad˚ u, které jsou souˇcást´ı projektu GNU Gama. Testy prob´ıhaly tak, ˇze se porovnávaly v´ ysledky spoˇctené na základˇe dat ze souboru XML s v´ ysledky spoˇcten´ ymi na základˇe dat z databáze SQLite. Testy ukázaly, ˇze pˇri naˇc´ıtán´ı data z databáze nedocház´ı k ˇza´dn´ ym chybám, které by zp˚ usobily rozd´ıly ve vyrovnan´ ych souˇradnic´ıch a vyrovnan´ ych mˇeˇren´ıch. Program gama-local-cmp vˇsak odhalil rozd´ıly mezi prvky kovarianˇcn´ı matice vyrovnan´ ych neznám´ ych. Dalˇs´ı testy ukázaly, ˇze rozd´ıly jsou zp˚ usobené ukládán´ım dat do databáze SQLite. Zp˚ usob ukládan´ı ˇc´ısel je dan´ y databáz´ı SQLite a nelze ho tud´ıˇz zmˇenit. Zjiˇstˇené rozd´ıly se t´ ykaj´ı smˇerodatn´ ych odchylek vyrovnan´ ych souˇradnic, nikoli souˇradnic samotn´ ych. Tyto rozd´ıly jsou malé a neznehodnocuj´ı v´ ysledky vyrovnán´ı. Vzhledem k tomu, lze povaˇzovat rozˇs´ıˇren´ı programu gama-local za plnˇe funkˇcn´ı. D´ıky moˇznosti ˇcten´ı u ´daj˚ u z databáze SQLite maj´ı uˇzivatelé programu gama-local alternativu k XML souboru. Mohou tak pouˇz´ıt to, co je pro jejich práci v´ yhodnˇejˇs´ı. Jiˇz bˇehem v´ yvoje se ukázalo, ˇze ˇcten´ı dat pˇr´ımo z databáze by pro uˇzivatele mohlo b´ yt velkou v´ yhodou. Dalˇs´ım krokem tedy jistˇe bude rozˇs´ıˇren´ı podpory databáze SQLite v programu gama-local o zápis v´ ysledk˚ u vyrovnán´ı do databáze. Pˇri tom bude v´ yhodné pouˇz´ıt opˇet SQLite C/C++ API. Pˇredt´ım vˇsak bude nutné navrhnout databázové schéma pro v´ ysledky vyrovnán´ı, které bude muset b´ yt – stejnˇe jako schéma pro vstupn´ı u ´daje – v souladu s potˇrebami projektu QGama. 56

ˇ CVUT Praha

ˇ E ´ ZDROJE POUZIT

Pouˇ zit´ e zdroje [1] STROUSTRUP, Bjarne. The C++ Programming Language – Special Edition. AT&T Labs, Florham Park, New Jersey. United States of America: AddisonWesley, 2000. 1020 s. ISBN 0-201-70073-5. [2] ISO/IEC 14882. INTERNATIONAL STANDARD: Programming languages – C++. 11 West 42nd Street, New York, New York 10036: American National Standards Institute, First edition, 1998-09-01. 748 s. [3] GOUGH, Brian J. An Introduction to GCC – for the GNU Compilers gcc and g++. Foreword by Richard M. Stallman. Network Theory Limited, United Kingdom. Revised August 2005. ISBN 0954161793. URL: [4] SUTTER, Herb; ALEXANDRESCU, Andrei. 101 programovac´ıch technik. Prvn´ı vydán´ı. Brno: Zoner Press, 2005. 232 s. ISBN 80-86815-28-5. ˇ ´ [5] CEPEK, Aleˇs. Informatika: Uvod do C++. Prvn´ı vydán´ı. Praha: Nakladatelstv´ı ˇ CVUT, 2004. 265 s. ISBN 80-01-03074-1 ¨ [6] GYORI, Gabriel. Analýza a kontrola XML výsledk˚ u vyrovnania GNU Gama. ˇ Praha, 2011. 112 s. Diplomová práce. CVUT v Praze, Fakulta stavebn´ı. [7] GNU General Public License [online]. Version 3, 29 June 2007. Free Software Foundation, Inc. 51 Franklin Street, Suite 500 Boston, MA 02110-1335 USA [cit. 2011-03-12]. URL: [8] W3C. Extensible Markup Language (XML) [online]. Last modified 2011-03-08. c1996-2003 World Wide Web Consortium MIT/CSAIL in USA [cit. 2011-04-03]. URL: ˇ [9] CEPEK, Aleˇs. Manuál k programu GNU Gama [online]. 2010-08-22 [cit. 201103-12]. URL: [10] An Introduction To The SQLite C/C++ Interface [online]. Modified 2011-03-28 [cit. 2011-03-30]. URL:

57

ˇ CVUT Praha

ˇ E ´ ZDROJE POUZIT

[11] C/C++ Interface For SQLite Version 3 [online]. Modified 2011-04-17 [cit. 201104-18]. URL: [12] Datatypes In SQLite Version 3 [online]. Modified 2011-04-17 [cit. 2011-04-19]. URL: URL: [13] Qt Development Frameworks. Qt – Cross-platform application and UI framework [online]. c2008-2011 Nokia Corporation [cit. 2011-04-18]. URL: . ˇ [14] CEPEK, Aleˇs. GNU Gama [program]. Edition 1.10, c2009-. URL: ´ [15] NOVAK, Jiˇr´ı. QGama [program]. Last update 2010-10-18. URL:

58

ˇ CVUT Praha

ˇ ıLOH SEZNAM PR´

Seznam pouˇ zit´ ych zkratek SQL

Structured Query Language

XML

Extensible Markup Language

HTML

HyperText Markup Language

PDF

Portable Document Format

API

Application Programming Interface

GCC

GNU Compiler Collection

GPL

General Public License

LGPL

Lesser General Public License

RAII

Resource Acquisition Is Initialization

PIMPL

Private Implementation, Pointer to Implementation

Seznam pˇ r´ıloh Databázové schéma gama-local-schema.sql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Dokumentace tˇr´ıdy SqliteReader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Pouˇzitá nastaven´ı kompilátoru GCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

59

A

Datab´ azov´ e sch´ ema gama-local-schema.sql

/* GNU Gama -- adjustment of geodetic networks Copyright ( C ) 2010 Ales Cepek < cepek@gnu . org > , 2010 Jiri Novak < jiri . novak@petriny . net > , 2010 Vaclav Petras < vaclav . petras@fsv . cvut . cz > This file is part of the GNU Gama C ++ library . This library is free software ; you can redistribute it and / or modify it under the terms of the GNU General Public License as published by the Free Software Foundation ; either version 3 of the License , or ( at your option ) any later version . This library is distributed in the hope that it will be useful , but WITHOUT ANY WARRANTY ; without even the implied warranty of M ER CH AN T AB IL IT Y or FITNESS FOR A PARTICULAR PURPOSE .

See the

GNU General Public License for more details . You should have received a copy of the GNU General Public License along with this library ; if not , write to the Free Software Foundation , Inc . , 51 Franklin Street , Fifth Floor , Boston , MA

02110 -1301

$

*/

create table g n u _ g a m a _ l o c a l _ c o n f i g u r a t i o n s ( conf_id

integer primary key ,

conf_name varchar (60) not null unique , sigma_apr double precision default 10.0 not null check ( sigma_apr > 0) , conf_pr

double precision

tol_abs

double precision default 1000 not null check ( tol_abs > 0) ,

default 0.95 not null check ( conf_pr > 0 and conf_pr <1) , sigma_act varchar (11) default ’ aposteriori ’ not null check ( sigma_act in ( ’ apriori ’ , ’ aposteriori ’)) , update_cc varchar (3) default ’no ’ not null check ( update_cc in ( ’ yes ’ , ’no ’)) , axes_xy

varchar (2) default ’ne ’ not null check ( axes_xy in ( ’ ne ’ , ’sw ’ , ’es ’ , ’wn ’ , ’en ’ , ’nw ’ , ’se ’ , ’ws ’)) ,

angles

varchar (12) default ’ right - handed ’ not null check ( angles in ( ’ left - handed ’ , ’ right - handed ’)) ,

epoch

double precision default 0.0 not null ,

algorithm varchar (12) default ’svd ’ not null check ( algorithm in ( ’ svd ’ , ’gso ’ , ’ cholesky ’ , ’sm - env ’)) , ang_units int default 400 not null check ( ang_units in (400 , 360)) , latitude

double precision default 50 not null ,

ellipsoid varchar (20)

60

); create table g n u _ g a m a _ l o c a l _ d e s c r i p t i o n s ( conf_id

integer references g nu_ gam a_l oca l_ con fig ura tio ns ,

indx

integer check ( indx >= 1) ,

text

varchar (1000) not null ,

primary key ( conf_id , indx ) ); create table g n u _ g a m a _ l o c a l _ p o i n t s ( conf_id


id

varchar (80) ,

x

double precision ,

y

double precision ,

z

double precision ,

txy

varchar (11) check ( txy in ( ’ fixed ’ , ’ adjusted ’ , ’ constrained ’)) ,

tz

varchar (11) check ( tz

in ( ’ fixed ’ , ’ adjusted ’ , ’ constrained ’)) ,

primary key ( conf_id , id ) ); create table g n u _ g a m a _ l o c a l _ c l u s t e r s ( conf_id


ccluster

integer check ( ccluster > 0) ,

dim

integer not null check ( dim > 0) ,

band

integer not null ,

tag

varchar (18) not null check ( tag in ( ’ obs ’ , ’ coordinates ’ , ’ vectors ’ , ’ height - differences ’)) ,

check ( band between 0 and dim -1) , primary key ( conf_id , ccluster ) ); -- upper triangular variance - covariance band - matrix (0 <= bandwidth < dim ) create table g n u _ g a m a _ l o c a l _ c o v m a t ( conf_id

integer ,

ccluster

integer ,

rind

integer check ( rind > 0) ,

cind

integer check ( cind > 0) ,

val

double precision not null ,

foreign key ( conf_id , ccluster ) references gnu_gama_local_clusters , primary key ( conf_id , ccluster , rind , cind ) ); create table g n u _ g a m a _ l o c a l _ o b s ( conf_id

integer ,

ccluster

integer ,

indx

integer check ( indx > 0) ,

tag

varchar (10) check ( tag in

61

( ’ direction ’ , ’ distance ’ , ’ angle ’ , ’s - distance ’ , ’z - angle ’ , ’dh ’)) , from_id


to_id


to_id2

varchar (80) ,

val

double precision not null ,

stdev

double precision ,

from_dh

double precision ,

to_dh

double precision ,

to_dh2

double precision ,

dist

double precision , -- dh dist

rejected

integer default 0 not null ,

primary key ( conf_id , ccluster , indx ) , foreign key ( conf_id , ccluster ) references gnu_gama_local_clusters , check ( tag <> ’ angle ’ or to_id2 is not null ) , check ( tag = ’dh ’ or ( tag <> ’dh ’ and dist is null )) ); create table g n u _ g a m a _ l o c a l _ c o o r d i n a t e s ( conf_id

integer ,

ccluster


indx


id

varchar (80) ,

x

double precision ,

y

double precision ,

z

double precision ,

rejected


foreign key ( conf_id , ccluster ) references gnu_gama_local_clusters , primary key ( conf_id , ccluster , indx ) ); create table g n u _ g a m a _ l o c a l _ v e c t o r s ( conf_id

integer ,

ccluster


indx


from_id

varchar (80) ,

to_id

varchar (80) ,

dx

double precision ,

dy

double precision ,

dz

double precision ,

from_dh

double precision ,

to_dh

double precision ,

rejected


foreign key ( conf_id , ccluster ) references gnu_gama_local_clusters , primary key ( conf_id , ccluster , indx ) );

62

B

Dokumentace tˇ r´ıdy SqliteReader

Dokumentace tˇr´ıdy SqliteReader je v dokumentaˇcn´ıch komentáˇr´ıch ve zdrojov´ ych kódech, zdokumentováno bylo rozhran´ı i implementace. Dokumentace je generována pomoc´ı nástroje Doxygen, kter´ y z dokumentaˇcn´ıch komentáˇr˚ u generuje dokumentaci (referenˇcn´ı manuál) v nˇekolika formátech (HTML, PDF, XML, . . . ). Dokumentaˇcn´ımi komentáˇri se rozum´ı speciálnˇe oznaˇcené bˇeˇzné komentáˇre, které obsahuj´ı nav´ıc jeˇstˇe formátovac´ı a jiné znaˇcky. Tato pˇr´ıloha obsahuje zkrácenou verzi dokumentace ve formátu PDF. Vynechány byly napˇr´ıklad callback funkce, jejich jména vˇsak dostateˇcnˇe vypov´ıdaj´ı o jejich u ´ˇcelu. Nav´ıc jsou callback funkce popsány v hlavn´ım textu.

63

4 Namespace Documentation

4

2

Namespace Documentation

4.1

anonymous_namespace{sqlitereader.cpp} Namespace Reference

Functions • void exec (sqlite3 ∗sqlite3Handle, const std::string &query, SqliteReaderCallbackType callback, ReaderData ∗readerData) • double ToDouble (const char ∗s, const std::string &m=T_gamalite_conversion_to_double_failed) • int ToInteger (const char ∗s, const std::string &m=T_gamalite_conversion_to_integer_failed) Variables • • • • • • •

const char ∗ T_gamalite_database_not_open const char ∗ T_gamalite_invalid_column_value const char ∗ T_gamalite_conversion_to_double_failed const char ∗ T_gamalite_conversion_to_integer_failed const char ∗ T_gamalite_unknown_exception_in_callback const char ∗ T_gamalite_stand_point_cluster_with_multi_dir_sets const char ∗ T_gamalite_configuration_not_found

4.1.1 4.1.1.1

Function Documentation void anonymous_namespace{sqlitereader.cpp}::exec (sqlite3 ∗ sqlite3Handle, const std::string & query, SqliteReaderCallbackType callback, ReaderData ∗ readerData)

A C++ wrapper around sqlite3_exec function. For internal use only. Connection to database has to be open. If the callback is NULL pointer, then no callback function is called (result rows are ignored). If callback requests query execution abort (by returning non-zero value), no other callbacks is called and exception is thrown (sqlite3_exec returns a value which differs from SQLITE_OK, see also ). If callback stores pointer to an exception to GNU_gama::local::sqlite_db::ReaderData::exception (p. 9) and callback requests query execution abort, exception will be rethrown. If GNU_gama::local::sqlite_db::ReaderData::exception (p. 9) is NULL pointer, GNU_gama::Exception::sqlitexc (p. 11) will be thrown with SQLite error message. Parameters sqlite3Handle pointer to struct sqlite3 query query string callback pointer to callback function readerData pointer to struct ReaderData Exceptions GNU_gama::Exception::sqlitexc (p. 11) if error occurs when reading from database Generated on Sat Apr 23 20:58:43 2011 for GNU Gama: SqliteReader by Doxygen

4.1


3

GNU_gama::Exception::base if is error occurred by something another -- it depends on callback It can also throw any other exception derived from this class. Callback functions are expected to handle exceptions like this: \\ ... try block catch (GNU_gama::Exception::base& e) { d->exception = e.clone(); } catch (std::exception& e) { d->exception = new GNU_gama::Exception::string(e.what()); } catch (...) { d->exception = new GNU_gama::Exception::string("unknown"); } return 1;

See also GNU_gama::local::sqlite_db::ReaderData (p. 6), SqliteReaderCallbackType (p. 14), GNU_gama::Exception::sqlitexc (p. 11) Referenced by GNU_gama::local::sqlite_db::SqliteReader::retrieve(), and sqlite_db_readClusters(). 4.1.1.2

double anonymous_namespace{sqlitereader.cpp}::ToDouble (const char ∗ s, const std::string & m = T_gamalite_conversion_to_double_failed)

Converts string to double. Parameter s can not be NULL pointer. If conversion fails, exception is thrown. Parameters s string to convert m error message if conversion fails Exceptions GNU_gama::Exception::sqlitexc (p. 11) Referenced by sqlite_db_readConfigurationInfo(), sqlite_db_readCoordinates(), sqlite_db_readCovarianceMatrix(), sqlite_db_readHeightDifferences(), sqlite_db_readObservations(), sqlite_db_readPoints(), and sqlite_db_readVectors(). 4.1.1.3

int anonymous_namespace{sqlitereader.cpp}::ToInteger (const char ∗ s, const std::string & m = T_gamalite_conversion_to_integer_failed)

Converts string to integer. Parameter s can not be NULL pointer. If conversion fails, exception is thrown. Generated on Sat Apr 23 20:58:43 2011 for GNU Gama: SqliteReader by Doxygen

4.1


4

Parameters s string to convert m error message if conversion fails Exceptions GNU_gama::Exception::sqlitexc (p. 11) Referenced by sqlite_db_readClusters(), sqlite_db_readCoordinates(), sqlite_db_readCovarianceMatrix(), sqlite_db_readObservations(), and sqlite_db_readVectors(). 4.1.2 4.1.2.1

Variable Documentation const char∗ anonymous_namespace{sqlitereader.cpp}::T_gamalite_configuration_not_found Initial value:

"configuration not found"

error message, used in GNU_gama::local::sqlite_db::SqliteReader::retrieve (p. 11) Referenced by GNU_gama::local::sqlite_db::SqliteReader::retrieve(). 4.1.2.2

const char∗ anonymous_namespace{sqlitereader.cpp}::T_gamalite_conversion_to_double_failed Initial value:

"conversion to double failed"

error message, used in conversion function when no better message can be used 4.1.2.3

const char∗ anonymous_namespace{sqlitereader.cpp}::T_gamalite_conversion_to_integer_failed Initial value:

"conversion to integer failed"

error message, used in conversion function when no better message can be used 4.1.2.4

const char∗ anonymous_namespace{sqlitereader.cpp}::T_gamalite_database_not_open Initial value:

"database not open"

error message, used in GNU_gama::local::sqlite_db::SqliteReader::SqliteReader (p. 10) Referenced by GNU_gama::local::sqlite_db::SqliteReader::SqliteReader(). Generated on Sat Apr 23 20:58:43 2011 for GNU Gama: SqliteReader by Doxygen

4.2

GNU_gama Namespace Reference

4.1.2.5

5

const char∗ anonymous_namespace{sqlitereader.cpp}::T_gamalite_invalid_column_value Initial value:

"invalid column value"

error message, used in callbacks’ to indicate bad value of database field Referenced by sqlite_db_readClusters(), sqlite_db_readConfigurationInfo(), sqlite_db_readConfigurationText(), sqlite_db_readCoordinates(), sqlite_db_readCovarianceMatrix(), sqlite_db_readHeightDifferences(), sqlite_db_readObservations(), sqlite_db_readPoints(), and sqlite_db_readVectors(). 4.1.2.6

const char∗ anonymous_namespace{sqlitereader.cpp}::T_gamalite_stand_point_cluster_with_multi_dir_sets Initial value:

"StandPoint cluster with multiple directions sets"

error message, used in sqlite_db_readObservations (p. 17) Referenced by sqlite_db_readObservations(). 4.1.2.7

const char∗ anonymous_namespace{sqlitereader.cpp}::T_gamalite_unknown_exception_in_callback Initial value:

"unknown exception in SqliteReader’s callback"

error message, used in callbacks’ catch(...) Referenced by sqlite_db_readClusters(), sqlite_db_readConfigurationInfo(), sqlite_db_readConfigurationText(), sqlite_db_readCoordinates(), sqlite_db_readCovarianceMatrix(), sqlite_db_readHeightDifferences(), sqlite_db_readObservations(), sqlite_db_readPoints(), and sqlite_db_readVectors().

4.2

GNU_gama Namespace Reference

Namespaces • namespace Exception • namespace local

4.3

GNU_gama::Exception Namespace Reference

Classes • class sqlitexc Exception (p. 5) class for GNU_gama::local::sqlite_db::SqliteReader (p. 9).

Generated on Sat Apr 23 20:58:43 2011 for GNU Gama: SqliteReader by Doxygen

4.4

GNU_gama::local Namespace Reference

4.4

GNU_gama::local Namespace Reference

Namespaces • namespace sqlite_db

4.5

GNU_gama::local::sqlite_db Namespace Reference

Classes • struct ReaderData GNU_gama::local::sqlite_db::SqliteReader (p. 9) class private data

• class SqliteReader Reads LocalNetwork from SQLite 3 database.

5

Class Documentation

5.1

GNU_gama::local::sqlite_db::ReaderData Struct Reference

GNU_gama::local::sqlite_db::SqliteReader (p. 9) class private data Public Member Functions • ReaderData () Public Attributes • • • • • • • • • • • • •

GNU_gama::local::LocalNetwork ∗ lnet std::string algorithm bool correction_to_ellipsoid double latitude GNU_gama::Ellipsoid ellipsoid GNU_gama::Exception::base ∗ exception sqlite3 ∗ sqlite3Handle std::string configurationId GNU_gama::local::StandPoint ∗ currentStandPoint GNU_gama::local::Vectors ∗ currentVectors GNU_gama::local::Coordinates ∗ currentCoordinates GNU_gama::local::HeightDifferences ∗ currentHeightDifferences GNU_gama::local::CovMat ∗ currentCovarianceMatrix

Private Member Functions • ReaderData (const ReaderData &) • ReaderData & operator= (const ReaderData &)


6

5.1


5.1.1

7

Detailed Description

GNU_gama::local::sqlite_db::SqliteReader (p. 9) class private data For internal use only. Contains all private data. In file sqlitereader.h (p. 18) is forward declaration of this struct. But declaration is only available in this file (translation unit). All members are public. Functions especially (extern "C") callbacks can easy manipulate with this members. This is no OOP violation because we can think about functions in this file as ReaderData (p. 6) member functions. Functions outside this file can’t access this structure because they know only forward declaration and GNU_gama::local::sqlite_db::SqliteReader (p. 9) has declared pointer to this struct private of course. However, there are some problems with callbacks visibility (see SqliteReaderCallbackType (p. 14) or sqlite_db_readConfigurationInfo (p. 15) for details). Callbacks sqlite_db_readObservations (p. 17), ... and sqlite_db_readCovarianceMatrix (p. 17) have to share data between it’s invocations. So they needs access to the same StandPoint, Vectors, etc. They also needs access to exception (p. 9). This is the reason why ReaderData (p. 6) contains pointer to StandPoint etc. Pointers currentStandPoint (p. 8), currentVectors (p. 8), currentCoordinates (p. 8), currentHeightDifferences (p. 8) and currentCovarianceMatrix (p. 8) temporary points to objects which are in use at the moment by the exec() (p. 2) caller and corresponding callback invocations. When processing of one object is finished, this pointer should by set to NULL pointer. 5.1.2 5.1.2.1

Constructor & Destructor Documentation GNU_gama::local::sqlite_db::ReaderData::ReaderData () [inline]

It sets all member variables. Pointers are set to NULL pointers. Strings are initialised by "" to satisfied GCC -Weffc++ warning options. References ellipsoid. 5.1.2.2

GNU_gama::local::sqlite_db::ReaderData::ReaderData (const ReaderData &) [private] disabled copy constructor

5.1.3 5.1.3.1

Member Function Documentation ReaderData& GNU_gama::local::sqlite_db::ReaderData::operator= (const ReaderData &) [private] disabled assignment operator

5.1.4 5.1.4.1

Member Data Documentation std::string GNU_gama::local::sqlite_db::ReaderData::algorithm

Referenced by sqlite_db_readConfigurationInfo().


5.1


5.1.4.2

8

std::string GNU_gama::local::sqlite_db::ReaderData::configurationId

configuration id in database Referenced by GNU_gama::local::sqlite_db::SqliteReader::retrieve(), sqlite_db_readClusters(), and sqlite_db_readConfigurationInfo(). 5.1.4.3

bool GNU_gama::local::sqlite_db::ReaderData::correction_to_ellipsoid

Referenced by sqlite_db_readConfigurationInfo(). 5.1.4.4

GNU_gama::local::Coordinates∗ GNU_gama::local::sqlite_db::ReaderData::currentCoordinates

Referenced by sqlite_db_readClusters(), and sqlite_db_readCoordinates(). 5.1.4.5

GNU_gama::local::CovMat∗ GNU_gama::local::sqlite_db::ReaderData::currentCovarianceMatrix

provides access to same covariance matrix for callback readCovarianceMatrix and caller of exec() (p. 2) function Referenced by sqlite_db_readClusters(), and sqlite_db_readCovarianceMatrix(). 5.1.4.6

GNU_gama::local::HeightDifferences∗ GNU_gama::local::sqlite_db::ReaderData::currentHeightDifferences

Referenced by sqlite_db_readClusters(), and sqlite_db_readHeightDifferences(). 5.1.4.7

GNU_gama::local::StandPoint∗ GNU_gama::local::sqlite_db::ReaderData::currentStandPoint

provides access to same stand point for callback readObservations and caller of exec() (p. 2) function Referenced by sqlite_db_readClusters(), and sqlite_db_readObservations(). 5.1.4.8

GNU_gama::local::Vectors∗ GNU_gama::local::sqlite_db::ReaderData::currentVectors

Referenced by sqlite_db_readClusters(), and sqlite_db_readVectors(). 5.1.4.9

GNU_gama::Ellipsoid GNU_gama::local::sqlite_db::ReaderData::ellipsoid


5.2

GNU_gama::local::sqlite_db::SqliteReader Class Reference

9

Referenced by ReaderData(), and sqlite_db_readConfigurationInfo(). 5.1.4.10

GNU_gama::Exception::base∗ GNU_gama::local::sqlite_db::ReaderData::exception

an exception which was caught in callback or NULL if no exception was thrown Referenced by sqlite_db_readClusters(), sqlite_db_readConfigurationInfo(), sqlite_db_readConfigurationText(), sqlite_db_readCoordinates(), sqlite_db_readCovarianceMatrix(), sqlite_db_readHeightDifferences(), sqlite_db_readObservations(), sqlite_db_readPoints(), sqlite_db_readVectors(), and GNU_gama::local::sqlite_db::SqliteReader::∼SqliteReader(). 5.1.4.11

double GNU_gama::local::sqlite_db::ReaderData::latitude

Referenced by sqlite_db_readConfigurationInfo(). 5.1.4.12

GNU_gama::local::LocalNetwork∗ GNU_gama::local::sqlite_db::ReaderData::lnet

pointer to network object Referenced by GNU_gama::local::sqlite_db::SqliteReader::retrieve(), sqlite_db_readClusters(), sqlite_db_readConfigurationInfo(), sqlite_db_readConfigurationText(), and sqlite_db_readPoints(). 5.1.4.13

sqlite3∗ GNU_gama::local::sqlite_db::ReaderData::sqlite3Handle

pointer to struct sqlite3 Referenced by GNU_gama::local::sqlite_db::SqliteReader::retrieve(), GNU_gama::local::sqlite_db::SqliteReader::SqliteReader(), and db::SqliteReader::∼SqliteReader().

sqlite_db_readClusters(), GNU_gama::local::sqlite_-

The documentation for this struct was generated from the following file: • sqlitereader.cpp

5.2


Reads LocalNetwork from SQLite 3 database. #include <sqlitereader.h> Public Member Functions • SqliteReader (const std::string &fileName) • ∼SqliteReader () • void retrieve (LocalNetwork ∗&lnet, const std::string &configuration)


5.2


10

Private Member Functions • SqliteReader (const SqliteReader &) • SqliteReader & operator= (const SqliteReader &) Private Attributes • ReaderData ∗ readerData 5.2.1


Reads LocalNetwork from SQLite 3 database. 5.2.2 5.2.2.1

Constructor & Destructor Documentation SqliteReader::SqliteReader (const std::string & fileName)

Opens a database connection. Parameters fileName name of database file References readerData, GNU_gama::local::sqlite_db::ReaderData::sqlite3Handle, and anonymous_namespace{sqlitereader.cpp}::T_gamalite_database_not_open. 5.2.2.2

SqliteReader::∼SqliteReader ()

Closes a database connection. If function sqlite3_close returns another value then SQLITE_OK (there were some error), no action is performed. References GNU_gama::local::sqlite_db::ReaderData::exception, gama::local::sqlite_db::ReaderData::sqlite3Handle. 5.2.2.3

readerData,

and

GNU_-

GNU_gama::local::sqlite_db::SqliteReader::SqliteReader (const SqliteReader &) [private] disabled copy constructor

5.2.3 5.2.3.1

Member Function Documentation SqliteReader& GNU_gama::local::sqlite_db::SqliteReader::operator= (const SqliteReader &) [private] disabled assignment operator


5.3

GNU_gama::Exception::sqlitexc Class Reference

5.2.3.2

11

void SqliteReader::retrieve (LocalNetwork ∗& lnet, const std::string & configuration)

Reads configuration configuration from database. If lnet is a NULL pointer, new LocalNetwork is created. Type of network depends on algorithm fetched from database. Exceptions GNU_gama::Exception::sqlitexc (p. 11) References GNU_gama::local::sqlite_db::ReaderData::configurationId, anonymous_namespace{sqlitereader.cpp}::exec(), GNU_gama::local::sqlite_db::ReaderData::lnet, readerData, GNU_gama::local::sqlite_db::ReaderData::sqlite3Handle, sqlite_db_readClusters(), sqlite_db_readConfigurationInfo(), sqlite_db_readConfigurationText(), sqlite_db_readPoints(), and anonymous_namespace{sqlitereader.cpp}::T_gamalite_configuration_not_found. 5.2.4

Member Data Documentation

5.2.4.1

ReaderData∗ GNU_gama::local::sqlite_db::SqliteReader::readerData [private]

pointer to private data Referenced by retrieve(), SqliteReader(), and ∼SqliteReader().

The documentation for this class was generated from the following files: • sqlitereader.h • sqlitereader.cpp

5.3

GNU_gama::Exception::sqlitexc Class Reference

Exception (p. 5) class for GNU_gama::local::sqlite_db::SqliteReader (p. 9). #include <sqlitereader.h> Public Member Functions • sqlitexc (const std::string &message) • virtual sqlitexc ∗ clone () const • virtual void raise () const 5.3.1


Exception (p. 5) class for GNU_gama::local::sqlite_db::SqliteReader (p. 9).


6 File Documentation

5.3.2

12

Constructor & Destructor Documentation

5.3.2.1

GNU_gama::Exception::sqlitexc::sqlitexc (const std::string & message) [inline]

Parameters message sqlite database error message or SqliteReader message Referenced by clone(). 5.3.3

Member Function Documentation

5.3.3.1

virtual sqlitexc∗ GNU_gama::Exception::sqlitexc::clone () const [inline, virtual] Clones an exception.

For internal use only. The way as it is used in callback functions: // ... try block catch (GNU_gama::Exception::base& e) { d->exception = e.clone(); } return 1;

References sqlitexc(). 5.3.3.2

virtual void GNU_gama::Exception::sqlitexc::raise () const [inline, virtual] Rethrows an exception polymorphically.

For internal use only. The way as it is used in function exec in file sqlitereader.cpp (p. 12): if (readerData->exception != 0) { readerData->exception->raise(); }

The documentation for this class was generated from the following file: • sqlitereader.h

6 6.1

File Documentation sqlitereader.cpp File Reference

Implementation of GNU_gama::local::sqlite_db::SqliteReader (p. 9). Generated on Sat Apr 23 20:58:43 2011 for GNU Gama: SqliteReader by Doxygen

C

Pouˇ zit´ a nastaven´ı kompil´ atoru GCC

Zde jsou uvedeny parametry urˇcuj´ıc´ı, v jak´ ych chv´ıl´ıch bude kompilátor GCC hlásit varován´ı. Parametry uvedené v následuj´ıc´ım seznamu byly pouˇzity pˇri v´ yvoji tˇr´ıdy SqliteReader. -ansi -Wall -pedantic -Wextra -Weffc++ -Wconversion -Wsign-conversion -Wfloat-equal -Wno-div-by-zero -Wmissing-declarations -Wlogical-op -Wabi -Wold-style-cast -Woverloaded-virtual -Wshadow -Wcast-qual -Wwrite-strings -Wredundant-decls -fno-nonansi-builtins -Wctor-dtor-privacy

75

ˇ Cesk e vysok e uˇ cen ı technick e v Praze Fakulta stavebn ı Bakal aˇ rsk a pr ace Praha 2011 V aclav Petr aˇs

Recommend Documents