Zobrazení zdroje stránky C a PostgreSQL - interní mechanismy

[[Category:Články]]
''Autor: Pavel Stěhule, 2011''

Před devíti lety jsem pro Root napsal [http://www.root.cz/clanky/rozsirovani-postgresql-v-c-funkce/ seriál o psaní doplňků] pro PostgreSQL. Tehdy jsem zhruba věděl, jak co funguje, a dokázal jsem napsat několik jednodušších funkcí. Moje znalosti
byly, když to tak vezmu, docela povrchní. Teď mám o něco více zkušeností, takže bych rád 
předchozí seriál doplnil o popis několika základních a zásadních technik, které se používají
jak při vývoji samotného PostgreSQL, tak při vývoji doplňků pro PostgreSQL. 
=Jazyk C a PostgreSQL=
Zdrojové kódy PostgreSQL jsou z 99% v Cčku. Proč jazyk C? Odpověď je poměrně jednoduchá - v
době, která byla pro PostgreSQL přelomová nebyl k dispozici vhodný překladač C++ a stejně tak
chyběli programátoři, kteří by perfektně ovládali C++. Z důvodu přenositelnosti se vývojáři drží
letitého standardu ANSI C. Nyní po 16-letém vývoji by byl přepis do jiného programovacího jazyka
kontraproduktivní. Zdravé jádro vývojářů má Cčko perfektně zažité, poměrně bezbolestně udržuje
multiplatformní kód a vývoj funguje bez větších excesů - takže není důvod ke změně. 
Je pravděpodobné, že časem dojde k razantní změně - a ke kompletní revizi kódu, ale ve výsledku to
už nebude starý PostgreSQL (viz Firebird - přepis do C++ z Interbase nebo Drizzle - přepis
z C++ do C++ z MySQL). Osobně si nemyslím, že by se tak stalo v příštích několika letech. PostgreSQL
se nemůže dostat do stejné situace jako MySQL nebo Interbase, která si vynutila fork (díky BSD licenci).

V PostgreSQL 9.0 došlo k několika úpravám zdrojového kódu, tak aby bylo možné 
vyvíjet externí moduly i v C++ (modifikovaly se hlavičkové soubory, upravovaly se
identifikátory, které kolidovaly s klíčovými slovy C++). Jazyk C nenabízí příliš komfortu.
To je fakt, s kterým se musíme smířit. Je ale podporován všude, a přeložený kód je ďábelsky
rychlý. Nedostatek komfortu je do jisté míry vyvážen poměrně bohatým repertoárem maker a 
knihovních funkcí, které si vývojáři pro sebe během těch 16 let vytvořili. 

Ze začátku to může být docela nezvyk, jelikož se v PostgreSQL používá vlastní typový systém a i vlastní 
způsob předávání parametrů. Můžete mi ovšem věřit, že to má svojí logiku. Vychází to z požadavku
na rozšiřitelnost PostgreSQL - v PostgreSQL můžete mít vlastní funkce, vlastní operátory,
vlastní datové typy, vlastní implementaci indexů. Rozhodně nebudu zde tvrdit, že psaní
zákaznických funkcí v Cčku je běžné a banální. To není. Ale jen díky rozšiřitelné architektuře
PostgreSQL vznikají moduly jako je PostGIS nebo třeba Orafce. 

==Zdroje na internetu==
# [http://www.neilconway.org/talks/hacking/hack_slides.pdf hack slides]

==Typový systém==

Pro všechny datové typy dostupné z SQL se v PostgreSQL používá interní datový typ "Datum". 
To je 4/8 bajtový generický typ, který obsahuje buďto ukazatel nebo nějakou hodnotu, pokud
se tato hodnota vejde do 4/8 bajtů (zaleží na platformně 32/64bit). Generický typ "Datum" 
neobsahuje žádná data, z kterých by bylo možné rozpoznat obsah - není zde prostor pro identifikátor
typu. Programátor musí vždy vědět s jakým typem pracuje (''Výjimka potvrzuje pravdlo - i uvnitř funkce lze dohledat údaje o typu každého parametru pomocí deskriptoru funkce. To ale na věci nic moc nemění. S dynamickými datovými typy (v PostgreSQL tzv. polymorfní typy) je spojena větší režie, a u obvykle i delší a složitější kód, tudíž je lépe se jim vyhnout (pokud je to možné - v C (v PLpgSQL je to zas trochu o něčem jiném))'') - také proto je v PostgreSQL přísně 
staticky typový systém. Pokud zaregistruji funkci příkazem:
<pre>
CREATE FUNCTION foo(a text)
RETURNS text AS ...
</pre>
tak mám zajištěno, že první parametr bude typu "text" a je mým úkolem vracet hodnotu typu
"text". Pokud vrátím jiný typ, tak pravděpodobně dojde k pádu serveru. Vzhledem k tomu, že je
typový systém pro zákaznická data v PostgreSQL nezávislý na typovém systému jazyka C,
tak mi s typovou kontrolou céčkový překladač moc nepomůže. To proto, že popis SQL funkcí je uložen
mimo dosah překladače (v systémové tabulce pg_proc). Z pohledu překladače jsou všechny SQL
funkce téměř stejné - liší se pouze názvem. 

Pokud hodnota typu ''Datum'' obsahuje ukazatel, tak v 99% obsahuje ukazatel na strukturu, kterou
označujeme jako typ ''varlena'' nebo obsahuje ukazatel na Cčkový string. V několika málo případech
může obsahovat ukazatel na cokoliv, ale to je natolik výjmečná situace, že s ní teď nebudu 
počítat. Typ ''varlena'' je předek všech SQL typů s variabilní délkou nebo typů, které jsou delší
než je velikost typu ''datum''. Typ ''varlena'' vypadá následovně - prvních n bajtů obsahuje informaci
o délce (1/2/4 byte) a ve zbývajících je zakódován vlastní obsah. Pro pamětníky - je to hodně 
podobné implementaci stringu v Borland Pascalu. Pár volných bitů v hlavičce struktury ''varlena''
ještě obsahuje informace o tom, zda-li je vlastní obsah načtený v paměti nebo je jej nutné
načíst z tabulky _toast - případně, zda-li je nutné obsah dekomprimpovat. Pravidla pro přístup
k jednotlivým položkém této struktury jsou docela složitá, takže pro přístup k atributům struktury
''varlena'' se používají makra (zrovna tak pro nastavení atributů).

Pozn. Systém pro ukládání velkách dat TOAST. V PostgreSQL se používá poměrně unikátní systém pro
ukládaní hodnot nad 8KB, který se označujeme zkratkou TOAST. PostgreSQL jako většina databází 
docela obtížně řeší situaci, kdy velikost záznamu přesáhne velikost datové stránky, což je 8KB. 
TOAST je trik, kterým se tato situace řeší. Pokud je záznam delší než 2KB, tak se vybere nejdelší
položka záznamu. Zkomprimuje se, a rozseká na bloky s maximální velikostí 2KB. Tyto bloky se pak
uloží do tzv. TOAST tabulky (pokud tabulka může obsahovat velká data, tak pro ní systém automaticky
vytvoří pomocnou tabulku (TOAST tabulku), do které se tato velká data uloží). Adresa dat v TOAST
tabulce nahradí původní data v záznamu - tím se záznam, který chceme uložit radikálně zkrátí.
Popsaný proces je opakován tak dlouho, dokud nemá záznam požadovanou délku (pozn. spouštěcí mechanismus 
a pravidla pro TOAST se liší verze od verze - v novějších verzích se spouští vždy, jelikož je snaha
o komprimaci ukládaných dat). Při čtení záznamu se přečtou všechny jeho položky. Některé položky
ovšem nemusí obsahovat přímo data. Místo toho obsahují adresu (ukazatel) do TOAST tabulky. Pokud
není potřeba zpracovávat data v TOAST tabulce, tak se TOAST tabulka nečte. K načtení dat v TOAST
tabulkce dojde teprve ve chvíli, kdy jsou skutečně potřeba. Podobný mechanismus se v ORM označuje
jako "Lazy Loading". Přístup k datům uloženým v TOAST tabulkách je natolik komplikovaný, že se téměř
vždy používají makra nebo funkce, které proces načítání a dekomprimace obalují a skrývají před
programátorem.

==Předávání parametrů - volající konvence==
Můžete psát zákaznické funkce v Cčku a používat Cčkové předávání parametrů. To je ovšem způsob,
který se nedoporučuje. Vývojáři si napsali vlastní systém předávání parametrů a výsledku, který
lépe odpovídá požadavkům SQL. V čem je problém? Problém je v NULL. V Cčku neumíme rozlišit
mezi 0 a NULL u parametrů funkce předávaných hodnotou. Způsob předávání parametrů (označuje se
jako V1) spočívá v tom, že si parametry předáváme pomocí komplexnější struktury místo přes
zásobník. Ta struktura se jmenuje 'FunctionCallInfoData':
<pre>
typedef struct 
{
	FmgrInfo	*flinfo;			// deskriptor funkce
	fmNodePtr	context;			// kontext volání funkce
	fmNodePtr	resultinfo;			// deskriptor výsledku (pokud je výsledkem složená hodnota)  
	bool isnull;				// výsledek je NULL?
	short	nargs;				// počet parametrů
	Datum	arg[FUNC_MAX_ARGS];		// vlastní parametry funkce
	bool	argnull[FUNC_MAX_ARGS];		// který parametr je nebo není NULL
} FunctionCallInfoData.
</pre>
jednoduchá funkce, která sečte dvě čísla by mohla vypadat následovně:
<pre>
Datum
sum_int(FunctionCallInfoData *fcinfo)
{
	int a1,
		a2;

	/* pokud je některý z parametrů NULL, pak výsledek je NULL */
	if (fcinfo->argnull[0] || fcinfo->argnull[1])
	{
		fcinfo->isnull = true;
		return (Datum) 0;
	}

	a1 = DatumGetInt32(fcinfo->arg[0]);
	a2 = DatumGetInt32(fcinfo->arg[1]);

	fcinfo->isnull = false;
	return Int32GetDatum(a1 + a2);
}
</pre>
Funkci musíme zaregistrovat:
<pre>
CREATE FUNCTION sum_int(int, int)
RETURNS int AS 'libdir/nazev_knihovny'
LANGUAGE C;
</pre>
Tuto funkci můžeme zjednodušit s pomocí atributu STRICT:
<pre>
CREATE FUNCTION sum_int(int, int)
RETURNS int AS 'libdir/nazev_knihovny'
LANGUAGE C STRICT;
</pre>
Pokud je funkce označena jako STRICT, pak v případě, že je jeden z parametrů NULL, tak je jasné, že
výsledkem bude NULL, a funkce se nezavolá. Díky tomu nemusíme uvnitř funkce zjišťovat, zda-li je
nebo není některý z parametrů NULL (prakticky všechny vestavěné SQL funkce mají atribut STRICT). 
Již bylo řečeno, že se při vývoji zákaznických funkcí intenzivně používají makra. Při jejich 
použití (pro varlena typy je to nutnost) by zdrojový kód výše uvedené funkce vypadal asi takto:
<pre>
Datum
sum_int(PG_FUNCTION_ARGS)
{
	int a1 = PG_GETARG_INT32(0);	// vrať první parametr funkce převedený do 4byte int
	int a2 = PG_GETARG_INT32(1);	// vrať druhý parametr funkce převedený do 4byte int

	PG_RETURN_INT32(a1 + a2);	// jako výsledek funkce vrať součet hodnot
}
</pre>
Pro začátečníka to může být trochu kryptografické - ale hodně to snižuje riziko chyb a také to zavádí
určitý jednotný styl, určitou štábní kulturu. Pro přístup k parametrům se používají makra PG_GETARG_typ(n)
(případně makra PG_GETARG_typ_P(n) pokud je typ ukazatelem). Naopak výsledek funkce se předává
pomocí makra PG_RETURN_typ(hodnota) (případně makrem PG_RETURN_POINTER(ukazatel), pokud je typ
ukazatelem). V případě, že funkce vrací NULL se použije makro PG_RETURN_NULL(). Tato makra se postarají
o všechny potřebné vstupně/výstupní konverze. Aby funkce vracela správné hodnoty, musí typ vrácené
hodnoty souhlasit s návratovým typem registrované funkce. To je poměrně častá chyba začátečníků.
<pre>
#define PG_FUNCTION_ARGS   FuncationCallInfo fcinfo
#define PG_NARGS()         (fcinfo->nargs)
#define PG_ARGISNULL(n)    (fcinfo->argnull[n])
#define PG_GETARG_DATUM(n) (fcinfo->arg[n])
#define PG_GETARG_INT32(n) DatumGetInt32(PG_GETARG_DATUM(n))
#define PG_RETURN_INT32(x) return Int32GetDatum(x)
#define PG_RETURN_NULL()   do { fcinfo->isnull = true; return (Datum) 0; } while (0)
</pre>

'''Pozor na přetěžování funkcí. V PostrgeSQL můžete mít registrováno několik funkcí pod stejným názvem s různými parametry a různými typy vrácené hodnoty. Také se mi stalo, že jsem upravoval funkci, přičemž moje úpravy se vůbec v chování funkce neprojevily. Až po chvíli mi došlo, že jsem upravoval jinou funkci než tu, kterou jsem volal.'''

==Volání funkcí navržených pro V1 konvenci (volání vestavěných SQL funkcí)==
V1 funkci nelze volat klasicky - protože V1 funkce očekává V1 předávání parametrů místo Cčkového způsobu předávání parametrů. Protože ale předávání parametrů V1 volající konvencí je fakticky postavené na Cčkovém předávání parametrů lze snadno realizovat volání V1 funkce přímo v C. Musíme jen připravit a naplnit strukturu ''FunctionCallInfo''. K inicializaci této struktury můžeme použít makro ''InitFunctionCallInfo''.
<pre>
#define InitFunctionCallInfoData(Fcinfo, Flinfo, Nargs, Context, Resultinfo) \
      do { \
            (Fcinfo).flinfo = (Flinfo); \
            (Fcinfo).context = (Context); \
            (Fcinfo).resultinfo = (Resultinfo); \
            (Fcinfo).isnull = false; \
            (Fcinfo).nargs = (Nargs); \
      } while (0)
</pre>

Pokud známe adresu funkce (ukazatel na funkci), tak lze použít přípravenou sadu funkcí, ''DirectFunctionCallN'', kterým předáváme ukazatel na funkci a parametry. Uvnitř této funkce se inicializuje struktura ''FunctionCallInfo'' a dojde k zavolání funkce:
<pre>
Datum
DirectFunctionCall1(PGFunction func, Datum arg1)
{
      FunctionCallInfoData fcinfo;
      Datum      result;

      InitFunctionCallInfoData(fcinfo, NULL, 1, NULL, NULL);

      fcinfo.arg[0] = arg1;
      fcinfo.argnull[0] = false;

      result = (*func) (&fcinfo);

      /* Check for null result, since caller is clearly not expecting one */
      if (fcinfo.isnull)
      elog(ERROR, "function %p returned NULL", (void *) func);

      return result;
}

/* ukázka - převod řetězce na velká písmena */
result = DatumGetTextP(DirectFunctionCall1(upper, TextPGetDatum(str)));
</pre>

Pokud adresu funkce neznáme - což jsou např funkce z dynamických knihoven, tak můžeme identifikovat volanou funkci jejím ''oid'' (''object identifier''). Místo ''DirectFunctionCall používáme funkci ''OidFunctionCall'':
<pre>
Datum
OidFunctionCall1(Oid functionId, Datum arg1)
{
      FmgrInfo      flinfo;
      FunctionCallInfoData fcinfo;
      Datum      result;

      fmgr_info(functionId, &flinfo);

      InitFunctionCallInfoData(fcinfo, &flinfo, 1, NULL, NULL);

      fcinfo.arg[0] = arg1;
      fcinfo.argnull[0] = false;

      result = FunctionCallInvoke(&fcinfo);

      /* Check for null result, since caller is clearly not expecting one */
      if (fcinfo.isnull)
            elog(ERROR, "function %u returned NULL", flinfo.fn_oid);

      return result;
}
</pre>
Nyní stojíme před problémem, jak získat ''Oid'' funkce. Pro hledání vstupně/výstupních funkcí k požadovanému typu existuje funkce ''getTypeInputInfo''. Id běžných funkcí můžeme dohledat dotazem:
<pre>
postgres=# select 'sin(double precision)'::regprocedure::int;
 int4 
------
 1604
(1 row)
</pre>
také lze použít fragment z implementace vstupní funkce typu ''regprocedure'':
<pre>
      /*
       * Else it's a name and arguments.  Parse the name and arguments, look up
       * potential matches in the current namespace search list, and scan to see
       * which one exactly matches the given argument types.<>(There will not be
       * more than one match.)
       *
       * XXX at present, this code will not work in bootstrap mode, hence this
       * datatype cannot be used for any system column that needs to receive
       * data during bootstrap.
       */
      parseNameAndArgTypes(pro_name, false, &names, &nargs, argtypes);
      clist = FuncnameGetCandidates(names, nargs, NIL, false, false);

      for (; clist; clist = clist->next)
      {
            if (memcmp(clist->args, argtypes, nargs * sizeof(Oid)) == 0)
                  break;
      }

      if (clist == NULL)
            ereport(ERROR,
                        (errcode(ERRCODE_UNDEFINED_FUNCTION),
                         errmsg("function \"%s\" does not exist", pro_name)));

      result = clist->oid;
</pre>
Pokud víme, že funkce není přetížena, lze výše uvedený fragment zjednodušit:
<pre>
      names = stringToQualifiedNameList(pro_name);
      clist = FuncnameGetCandidates(names, -1, NIL, false, false);

      if (clist == NULL)
            ereport(ERROR,
                        (errcode(ERRCODE_UNDEFINED_FUNCTION),
                         errmsg("function \"%s\" does not exist", pro_name_or_oid)));
      else if (clist->next != NULL)
            ereport(ERROR,
                        (errcode(ERRCODE_AMBIGUOUS_FUNCTION),
                         errmsg("more than one function named \"%s\"",
                                                                  pro_name)));
      result = clist->oid;
</pre>
Konečně - pokud funkci identifikovanou ''Oid'' voláme opakovaně, tak je vhodné si uložit její descriptor ''FmgrInfo'' a ten pak používat pro identifikaci funkce:
<pre>
/*
 * This macro invokes a function given a filled-in FunctionCallInfoData
 * struct. The macro result is the returned Datum --- but note that
 * caller must still check fcinfo->isnull! Also, if function is strict,
 * it is caller's responsibility to verify that no null arguments are present
 * before calling.
 */
#define FunctionCallInvoke(fcinfo)      ((* (fcinfo)->flinfo->fn_addr) (fcinfo))

Datum
FunctionCall1(FmgrInfo *flinfo, Datum arg1)
{
      FunctionCallInfoData fcinfo;
      Datum  result;

      InitFunctionCallInfoData(fcinfo, flinfo, 1, NULL, NULL);

      fcinfo.arg[0] = arg1;
      fcinfo.argnull[0] = false;

      result = FunctionCallInvoke(&fcinfo);

      /* Check for null result, since caller is clearly not expecting one */
      if (fcinfo.isnull)
            elog(ERROR, "function %u returned NULL", fcinfo.flinfo->fn_oid);

      return result;
}
</pre>

==K čemu slouží signatura funkce?==
Při zavádění V1 volající konvence vývojáři PostgreSQL hledali způsob, jak zajistit kompatibilitu stávajících externích modulů. Řešení je poměrně vtipné - každá V1 funkce musí mít svou signaturu - a na základě její existence nebo neexistence se executor rozhoduje, jestli použije C volající konvenci nebo V1 volající konvenci. 

Toto řešení funguje dobře - drobným kazem na kráse jsou občas "nevysvětlitelné pády" serveru při ladění V1 funkcí, u kterých vývojář zapomněl signaturu - obvykle přístup k V1 struktuře, která ovšem nebyla inicializována, jelikož funkce byla volána s C volající konvencí vede k ''segmantation-faultu''. ''Je proto praktické napsat nejprve signaturu V1 funkce a teprve poté vlastní V1 funkci'' (pozn. pokud dojde k nečekaným pádům v makrech PG_GETARG_* nebo PG_ARGISNULL(), pak jako první krok doporučuji zkontrolovat shodu identifikátoru funkce a identifikátoru signatury).

Signaturou funkce se míní použití makra ''PG_FUNCTION_INFO_V1'':
<pre>
PG_FUNCTION_INFO_V1(pst_left);

Datum
pst_left(PG_FUNCTION_ARGS)
{
      ...
      ...
      PG_RETURN_TEXT_P(result);
}
</pre>
Toto makro vytvoří funkci ''pg_finfo_názevfce'':
<pre>
const Pg_finfo_record *
pg_finfo_pst_left (void)
{
      static const pg_finfo_record myfinfo = {1};
      return &myfinfo;
}
</pre>
Přičemž před použitím funkce se zjišťuje, zda-li taková funkce existuje. Pokud existuje, tak se zavolá a z výsledku se zjistí, jakou volající konvenci funkce vyžaduje (podporuje). Zatím existuje pouze V1 volající konvence, nicméně v budoucnu je možné vytvořit i další rozšíření této konvence.
<pre>
const Pg_finfo_record *
fetch_finfo_record(void *filehandle, char *funcname)
{
      char   *infofuncname;
      PGFInfoFunction infofunc;
      static Pg_finfo_record default_inforec = {0};

      infofuncname = (char *) palloc(strlen(funcname) + 10);
      strcpy(infofuncname, “pg_finfo_”);
      strcat(infofuncname, funcname);

      infofunc = lookup_external_function(filehandle,
                                                     Infofuncname);
      if (infofunc == NULL)
      {
            /* Not found --- assume version 0 */
            pfree(infofuncname);
            return &default_inforec;
      }

      /* Found, so call it */
      inforec = (*infofunc) ();

      pfree(infofuncname);
      return inforec;
}
</pre>
Na základě signatury funkce je rozhodnuto o způsobu volání funkce - viz kód funkce ''fmgr_info_C_lang''.

==K čemu slouží signatura modulu?==
Vývoj externích modulů v PostgreSQL se potýká s jedním základním problémem - a tím je neexistence univerzálního stabilního API napříč major verzemi. Samozřejmě, že je snahou API neměnit - případně, pokud to lze, tak měnit bez narušení zpětné kompatibility. Jinak by byli vývojáři PostgreSQL sami proti sobě. Navíc z důvodu rozdílné velikosti základních typů nejsou kompatibilní moduly pro 32 a 64bit. Obtížně detekovatelnou chybou je použití nekompatibilních externích modulů. Aby se této chybě zabránilo, tak každý modul má v sobě zakompilovanou informaci o tom, vůči které verzi PostgreSQL byl zkompilován. Při inicializaci externího modulu se tato informace porovná se skutečnou verzí PostgreSQL a v případě, že modul nebyl zkompilován pro použitou verzi PostgreSQL, je hlašena chyba a modul není použit. Vložení informací o verzi pro pozdější porovnání zajistí makro ''PG_MODULE_MAGIC'', tím že vytvoří funkci ''Pg_magic_func'':
<pre>
#ifdef PG_MODULE_MAGIC
PG_MODULE_MAGIC;
#endif
</pre>
Aktuálně se vloží následující údaje:
<pre>
/* Definition of the magic block structure */
typedef struct
{
     int               len;               /* sizeof(this struct) */
     int               version;          /* PostgreSQL major version */
     int               funcmaxargs;     /* FUNC_MAX_ARGS */
     int               indexmaxkeys;    /* INDEX_MAX_KEYS */
     int               namedatalen;     /* NAMEDATALEN */
     int               float4byval;     /* FLOAT4PASSBYVAL */
     int               float8byval;     /* FLOAT8PASSBYVAL */
} Pg_magic_struct;

/* The actual data block contents */
#define PG_MODULE_MAGIC_DATA \
{ \
     sizeof(Pg_magic_struct), \
     PG_VERSION_NUM / 100, \
     FUNC_MAX_ARGS, \
     INDEX_MAX_KEYS, \
     NAMEDATALEN, \
     FLOAT4PASSBYVAL, \
     FLOAT8PASSBYVAL \
}

#define PG_MODULE_MAGIC \
const Pg_magic_struct * \
Pg_magic_func(void) \
{ \
        static const Pg_magic_struct Pg_magic_data = { \
								sizeof(Pg_magic_struct), \
								PG_VERSION_NUM / 100, \
								FUNC_MAX_ARGS, \
								INDEX_MAX_KEYS, \
								NAMEDATALEN, \
								FLOAT4PASSBYVAL, \
								FLOAT8PASSBYVAL \
							}; \
        return &Pg_magic_data; \
} \
</pre>
Funkce ''Pg_magic_func'' je volána při natažení modulu - vrací strukturu ''Pg_magic_struct'', která je pak binárně porovnána s aktuální Pg_magic_struct strukturou serveru.
<pre>
/* Check the magic function to determine compatibility */
magic_func = (PGModuleMagicFunction)
pg_dlsym(file_scanner->handle, PG_MAGIC_FUNCTION_NAME_STRING);
if (magic_func)
{
		const Pg_magic_struct *magic_data_ptr = (*magic_func) ();

		if (magic_data_ptr->len != magic_data.len ||
			memcmp(magic_data_ptr, &magic_data, magic_data.len) != 0)
		{
				/* copy data block before unlinking library */
				Pg_magic_struct module_magic_data = *magic_data_ptr;
</pre>

==Konverze z generického typu "Datum" do C typu a zpět==
Typ ''Datum'' je pro PostgreSQL zásadní - představuje jediný interní abstraktní typ s kterým se pracuje v kódu PostgreSQL. Datum je celočíselný typ stejné velikosti jako ukazatel - může obsahovat číslo, znak nebo ukazatel na větší strukturu dat. Trochu zvláštností je konverze na C typy, která je realizována pomocí sady maker/funkcí. Tyto makra jsou relativně důležitá, zakrývají implementační záležitosti a transparentně zajišťují deTOAST a dekomprimaci typů s variabilní délkou. U kratších typů než je ukazatel tato makra zajišťují vymaskování balastu. Kromě jiného realizují i konkrétní přetypování:
<pre>
#define Int32GetDatum(X)    ((Datum) SET_4_BYTES(X))
#define DatumGetInt32(X)    ((int32) GET_4_BYTES(X))
#define PointerGetDatum(X)  ((Datum) X)
</pre>
DeTOAST struktury ''varlena'' zajišťuje zajišťuje funkce ''pg_detoast_datum'', která se v následující ukázce objeví:
<pre>
#define PG_DETOAST_DATUM(X)  pg_detoast_datum((struct varlena *) DatumGetPointer(X))
#define DatumGetTextP(X)     ((text *) PG_DETOAST_DATUM(X))

#define PG_GETARG_TEXT_P(X)  DatumGetTextP(PG_GETARG_DATUM(X))
#define PG_RETURN_TEXT_P(X)  PG_RETURN_POINTER(X)
</pre>
Názvy konverzních maker dodržují následující metodiku: ''ZdrojovýTyp''Get''CílovýTyp''.

==String Builder==

Spojování, formátování řetězců je v Cčku docela "dřina". Musí se správně alokovat paměť, musí se dávat
pozor na přetečení bufferů. K zpříjemnění života si vývojáři připravili knihovnu "stringinfo", která
všechny výše uvedené operace zvládá:
<pre>
#include "lib/stringinfo.h"

...

	StringInfoData	ds;

	initStringInfo(&ds);
	appenStringInfo(&ds, "Hello, %s", "World");
...
	pfree(ds.data);
</pre>

==Použití C řetězců==
Cčkovému char* odpovídá typ CString. Používá se pro vstupně/výstupní operace. Každý datový typ v PostgreSQL
má zaregistrovánu jednu "in" funkci a jednu "out" funkci. Vstupem "in" funkce je hodnota typu CString, výstupem
pak adekvátní binární hodnota. "out" funkce je reverzní k "in" funkci. "in" funkce se používá pro parsování 
vstupu. "out" funkce se používá pro formátování výstupu. Je jasné, že se s typem CString bude v Cčku poměrně
pohodlně pracovat - přesto se nedoporučuje psát funkce (mimo "in"/"out" funkcí), které by měly parametry tohoto
typu nebo vracely CString. Tento typ totiž nepodporuje TOAST a tudíž nelze uložit delší řetězce než je 8KB
(samozřejmě, že lze pracovat s delšími CString řetězci, jen je nelze uložit do db). 
Proto si také můžete všimnout, že se CString neobjevuje ani ve vestavěných funkcí. Z pohledu SQL generický typ
pro řetězce je "text".

Pro konverzi mezi CStringem a typem "text", která je častá (naopak funkce z glibc neumí pracovat s typy PostgreSQL),
lze používat makra:
<pre>
text_to_cstring(text *txt);
cstring_to_text(char *str);
cstring_to_text_with_len(char *str, size_t len);
</pre>
Variace na funkci "Hello" by v PostgreSQL s použitím string builderu mohla vypadat asi následovně:
<pre>
Datum
hello(PG_FUNCTION_ARGS)
{
	StringInfoData	ds;
	text	*txt;

	txt = PG_GETARG_TEXT_P(0);
	initStringInfo(&ds);
	appendStringInfo(&ds, "Hello, %s", text_to_cstring(txt));

	PG_RETURN_TEXT_P(cstring_to_text_with_len(ds.data, ds.len));
}

-- registrace funkce
CREATE FUNCTION hello(text)
RETURNS text AS 'libdir/hellolib'
LANGUAGE C STRICT;
</pre>
==Úpravy kódu pro více bajtová kódování (UTF8)==
V okamžiku, kdy uvnitř funkce potřebujeme znát počet znaků, musíme si uvědomit, že existují tzv více bajtová kódování. Jedno z nich - ''UTF8'' - se intenzivně používá i v středoevropském prostoru (cca v devadesátých letech bylo použití více bajtových kódování omezeno téměř výlučně na asijskou oblast). Rozdíly v implementaci více bajtových kódování mizí při použití PostgreSQL knihovní funkce ''pg_mblen''. Tato funkce vrací velikost aktuálního vícebajtového znaku. 

Funkce, která vrací počet znaků v řetězci - nikoliv počet bajtů může vypadat následovně:
<pre>
Datum string_length(PG_FUNCTION_ARGS)
{
    text *str = PG_GETARG_TEXT_P(0);
    int bytes, processed, mblen = 0;
    int result = 0;
    char *ptr;

    ptr = VARDATA(str);
    bytes = VARSIZE(str) - VARHDRSZ;

    while (processed < bytes)
    {
        result++;
        mblen = pg_mblen(ptr);
        ptr += mblen;
        processed += mblen;
    }
   PG_RETURN_INT32(result);
}
</pre>

==Základní makra pro typ "varlena"==
Abstraktní typ ''varlena'' se v PostgreSQL používá pro všechny typy s variabilní velikostí nebo pro typy větší než je velikost typu Datum. Tato struktura je sama o sobě poměrně variabilní - zvládá jak typy, které podporují TOAST, tak i typy, které TOAST nepodporují. Navíc v novějších může být délka (viz níže) 8, 16 nebo 32 bitů. V zásadě je ''varlena'' blok dat, který v prvních n bajtů má uloženou délku bloku (plus v několika málo bitech ještě procesní metadata). U krátkých typů (např. NUMERIC) je zásadní, že délka může být zakódována v jednom bajtu. S hodnotou typu ''varlena'' můžeme provádět základní operace - kopírování, serializaci, deserializaci, aniž bychom museli rozumět obsahu, který je v hodnotě zakódován. 
<pre>
typedef struct varlena
{
    char v1_len[4];
    char v1_dat[1];
}
</pre>
Vzhledem ke složitosti operací, které tato struktura zajišťuje (a jejich významu) se nedoporučuje pracovat s daty ve formátu (struktuře) ''varlena'' přímo. Používají se připravená makra dle zažitých vzorů:
<pre>
/* získání čisté délky */
VARSIZE(ptr) - VARHDRSZ;

/* získání ukazatele na vlastní data */
VARDATA(ptr);

/* určení délky */
SET_VARSIZE(ptr, velikost + VARHDRSZ);
</pre>
Dobrou a jednoduchou ukázkou používání ''varlena'' typu může být jednoduchá funkce ''concat'', která slouží k spojení dvou řetězců:
<pre>
Datum
concat(PG_FUNCTION_ARGS)
{
     text *a = PG_GETARG_TEXT_P(0);
     text *b = PG_GETARG_TEXT_P(1);
     text *result;
     int l_a, l_b, l_result;
     char *ptr;

     l_a = VARSIZE(a) - VARHDRSZ;
     l_b = VARSIZE(b) - VARHDRSZ;
     l_result = l_a + l_b + VARHDRSZ;
     result = palloc(l_result);
     ptr = VARDATA(result);

     memcpy(ptr, VARDATA(a), l_a);
     memcpy(ptr + l_a, VARDATA(b), l_b);
     SET_VARSIZE(result, l_result);

     PG_RETURN_TEXT_P(result);   
}
</pre>

==Správa paměti==
V PostgreSQL je dynamické paměť alokována z aktuálního nebo jinak určeného kontextu. Zjednodušeně lze kontext popsat jako jakousi abstraktní evidenci jednotlivých alokací paměti. Alokovanou paměť lze uvolnit voláním ''pfree'' (čímž dojde k uvolnění bufferů a výmazu z evidence) nebo zrušením kontextu. Odstranění kontextu je podstatně rychlejší operace než jednotlivá volání ''pfree'' - navíc použití kontextů snižuje fragmentaci paměti. Řada důležitých procesů v PostgreSQL má přidělen jeden nebo více paměťových kontextů. Uvnitř procesu se alokuje paměť vždy z těchto přidělených kontextů a po dokončení procesu se přidělené paměťové kontexty odstraňují. Tím se '''minimalizuje''' riziko úniků paměti (memory leaks) a do jisté míry se i zjednodušuje kód. Paměťové kontexty mohou být hierarchické. Odstranění kontextu vede k odstranění všech podřízených paměťových kontextů. 

Nevýhodou paměťových kontextů je jejich režie, která se projeví při alokaci ''palloc'' velkého počtu extrémně malých bloků. Implementace paměťových kontextů předřazuje ke každému alokovanému bloku ukazatel na deskriptor kontextu. Pokud by mělo docházet k intenzivní alokaci paměti a pak její realokaci ''realloc'', tak je výhodnější si alokovat více paměti a snížit počet volání ''realloc''. Dobrou ukázkou je kód v knihovně ''stringinfo''. poměrně často se v PostgreSQL můžeme setkat se situací, kdy je paměť pouze alokována a nikde není explicitně uvolněna (např. ve funkcích, které jsou dostupné z SQL). Před zavoláním každé funkce executorem je vytvořen dočasný aktuální kontext, který se prohlásí za aktuální. Uvnitř funkce se pak paměť alokuje (pokud se neuvede explicitně jinak) z tohoto kontextu. Poté, co funkce skončí (a to ať úspěšně nebo neúspěšně), executor odstraní tento dočasný kontext (poté co zkopíroval výsledek do nadřazeného kontextu - pokud se jedná o ''varlena'' typ). Tímto mechanismem je zajištěno, že nedojde k únikům paměti - nebo je toto riziko zásadně minimalizováno. To je pro PostgreSQL poměrně zásadní, neboť se předpokládá, že zákaznické funkce v C si pokročilí uživatelé PostgreSQL budou psát sami a je poměrně velká šance, že svůj kód dostatečně nezabezpečí proti úniku paměti. Pokud nedochází k velkým alokacím paměti, pak (při dnešních kapacitách paměti), lze neřešit explicitní uvolnění paměti (které může být pomalejší než zruešení kontextu), protože víme, že po ukončení funkce bude vždy celý paměťový kontext, a s ním i veškerá v něm alokovaná paměť, vždy odstraněn.

Určitou obtíž, kterou paměťové kontexty mají je nutnost jejich zvládnutí a pochopení pro začínající programátory. Typicky se očekává, že bude výsledek typu ''varlena'' alokován v aktuálním kontextu (v aktuálním kontextu při startu funkce). Některá API - např. SPI při své inicializaci mění aktuální kontext - za svůj vlastní, který je při uvolnění SPI odstraněn. Pokud by návratová hodnota byla alokována v tomto kontextu, tak je přepsána (nebo může být náhodně přepsána (viz parametr konfigurace '''--enable-cassert''')). Reference na takový blok paměti může vést k získání výsledku, který odpovídá náhodné posloupnosti bajtů v paměti nebo k pádu serveru - typicky segmentation fault. Pokud je PostgreSQL konfigurován s parametrem --enable-cassert, pak před uvolněním kontextu dojde k explicitnímu přepsání alokovaných dat (takže viditelně poznáme problém) a v některých kontrolních bodech ověřuje platnost kontextu. Pro SPI je nutné paměť pro výsledek alokovat funkcí ''SPI_calloc'', která vrací paměť z kontextu, který byl aktuální před inicializací SPI. 

Pokud funkce vrací typ ''tuplestore'' je nutné použít nikoliv aktuální kontext při inicializaci funkce, nýbrž vyhrazený kontext, který je přednastavený ve struktuře ''fcinfo''. Tím, že tento kontext prohlásíme aktuální, budou všechny alokace nasměrované do tohoto kontextu (s přenastavením aktuálního kontextu na konkrétní aktuální kontext se v PostgreSQL setkáme často viz ''MemoryContextSwitchTo''):
<pre>
Datum
generate_series(PG_FUNCTION_ARGS)
{
        ReturnSetInfo *rsinfo = (ReturnSetInfo *) fcinfo->resultinfo;
        TupleDesc       tupdesc;
        Tuplestorestate *tupstore;
        MemoryContext per_query_ctx;
        MemoryContext oldcontext;
        int i, start, end;

       /* check to see if caller supports us returning a tuplestore */
        if (!(rsinfo->allowedModes & SFRM_Materialize))
                ereport(ERROR,
                                (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                                 errmsg("materialize mode required, but it is not " \
                                                "allowed in this context")));
        start = PG_GETARG_INT32(0);
        end = PG_GETARG_INT32(1);

        /* need to build tuplestore in query context */
        per_query_ctx = rsinfo->econtext->ecxt_per_query_memory;
        oldcontext = MemoryContextSwitchTo(per_query_ctx);

        tupdesc = rsinfo->expectedDesc;
        tupstore = tuplestore_begin_heap(true, false, work_mem);

        for (i = start; i <= end; i++)
        {
                Datum        value;
                bool         null = false;
                HeapTuple       tuple;

                /* generate junk in short-term context */
                MemoryContextSwitchTo(oldcontext);

                value = Int32GetDatum(i);
                tuple = heap_form_tuple(tupdesc, &value, &null);

                MemoryContextSwitchTo(per_query_ctx);
                tuplestore_puttuple(tupstore, tuple);
        }

        /* clean up and return the tuplestore */
        tuplestore_donestoring(tupstore);

        MemoryContextSwitchTo(oldcontext);

        rsinfo->returnMode = SFRM_Materialize;
        rsinfo->setResult = tupstore;
        rsinfo->setDesc = tupdesc;

        return (Datum) 0;
}
</pre>
Privátní kontext se obvykle vytváří pod paměťovým kontextem vytvořeným executorem. Tím, je zajištěno jeho odstranění v případě chyby. Vlastník kontextu (procedura, která vytvořila kontext) je zodpovědný za jeho zrušení. Pokud nemůžeme využít tento mechanismus - např. chceme aby paměťový kontext "přežil" volání funkce, musíme odstranit kontext v callback funkci transakce nebo subtransakce viz funkce ''AtEOSubXact_SPI''. Callback funkce transakce se registrují funkcemi ''RegisterXactCallback'' nebo ''RegisterSubXactCallback'':
<pre>
      RegisterXactCallback(plpgsql_xact_cb, NULL);
      RegisterSubXactCallback(plpgsql_subxact_cb, NULL);
</pre>

==API pro zákaznické funkce (Server Programming Interface)==
Rozhraní SPI je jediné rozhraní, které je, jako takové, určeno pro použití v uživatelských funkcích. Umožňuje provést SQL příkaz, umožňuje získat a zpracovat výsledek SQL příkazu. Podporuje kurzory a nechybí ani podpora prepared statements a parametrized queries. Práce s tímto rozhraním není komplikovaná. Pravděpodobně jediná záludnost je v tom, že vytváří vlastní paměťový kontext, v kterém jsou uložené výsledky SQL příkazů, a který po uzavření API odstraňuje. '''Pokud nedojde k zkopírování výsledků do vnějšího paměťového kontextu, tak zrušením kontextu dojde ke ztrátě výsledků.''' Pro alokaci paměti z vnějšího paměťového kontextu lze použít funkci ''SPI_palloc()''.

API lze používat po volání funkce ''SPI_connect()''. Funkce ''SPI_finish()'' uvolňuje zdroje - zejména alokovanou paměť.

<pre>
Datum
eval_query(PG_FUNCTION_ARGS)
{
        char *query = text_to_cstring(PG_GETARG_TEXT_P(1));
        char *result = NULL;
        text *result_text = NULL;
        MemoryContext callCtx = CurrentMemoryContext;

        SPI_connect();

        ret = SPI_exec(query, 0);
        if (ret > 0 && SPI_tuptable != NULL)
        {
                TupleDesc tupdesc = SPI_tuptable->tupdesc;
                SPITupleTable *tuptable = SPI_tuptable;
                HeapTuple tuple = tuptable->vals[0];

                if (tupdesc->natts > 1)
                        elog(ERROR, “Query returned more columns”);
                if (SPI_processed > 1)
                        elog(ERROR, “Query returned more rows”);
                else if (SPI_processed == 1)
                        result = SPI_getvalue(tuple, tupdesc, 1);
        }

        /*
         * Aktuálně result je NULL nebo se odkazuje na c string v
         * v prostoru spravovaném SPI, proto je nutne pripadny
         * obsah vytvorit v kontextu, ktery byl aktualni v dobe
         * volani funkce.
         */
        if (result != NULL)
        {
                 MemoryContext spiCtx;

                 spiCtx = MemoryContextSwitchTo(callCtx);
                 result_text = cstring_to_text(result);
                 MemoryContextSwitchTo(spiCtx);
        }

        /*
         * Nyni je vysledek dotazu uspesne zkopirovan, a tudiz lze
         * odstranit pametovy kontext spravovany SPI
         */
        SPI_logout();

        if (result_text != NULL)
                 PG_RETURN_TEXT_P(result_text);
        else
                 PG_RETURN_NULL();
}
</pre>
Ve výše zmíněné ukázce dochází k transformaci výsledku dotazu z formátu ''cstring'' do formátu ''text''. Jelikož před touto transformací došlo ke změně paměťového kontextu, tak zároveň dochází k exportu dat z kontextu SPI do kontextu funkce. Transformovaný řetězec - ve formátu ''text'' bude vytvořen v paměťovém kontextu, který je aktuální při spuštění funkce (a který je aktuální během transformace).

Parametrický dotaz se provádí prostřednictvím funkce ''SPI_execute_with_args''. Pokud se používají skalární datové typy, tak i tato funkce se používá jednoduše. Poněkud neobvyklé je předávání informace o tom, zda-li je některý parametr NULL. Tyto informace se nepředávají v poli typu boolean, jak bychom čekali, nýbrž v poli znaků, kde mezera znamená NOT NULL a znak 'n' znamená NULL. pokud bychom naší funkci ''eval'' rozšířili o podporu parametrizovaných dotazů, pak by tato funkce - resp. část, kde se aktivuje zpracování SQL příkazu, mohla vypadat následovně (Funkce musí být deklarována s variadickým parametrem typu "any"):

<pre>
        Datum args[FUNC_MAX_ARGS];
        char nulls[FUNC_MAX_ARGS];
        Oid types[FUNC_MAX_ARGS]
        int i;

        for(i = 0; i < PG_NARGS() - 1; i++)
        {
                 args[i] = PG_GETARG_DATUM(i + 1);
                 nulls[i] = PG_ARGISNULL(i + 1) ? 'n' : ' ';
                 types[i] = get_fn_expr_argtype(fcinfo->flinfo, i + 1);
        }

        res = SPI_execute_with_args(query, 
                                            PG_NARGS() - 1, types,
                                                                   args, nulls,
                                                                                true, 2);
        ...
</pre>
Funkce ''get_fn_expr_argtype'' vrací ''Oid'' n-tého parametru.

==Sebereflexe uvnitř PostgreSQL - typ ''Node''==
Typ ''Node'' a typy z něj vycházející  umožňují vytvářet "chytré" kompozitní typy, které podporují serializaci, deserializaci, porovnání, kopírování a zobrazení. Typ ''Node'' je jednoduchá struktura, která jako první položku obsahuje číslo, které určuje obsah struktury. Typ ''Node'' můžeme chápat jako o pokus implementace abstraktní třídy v klasickém neobjektovém jazyku C. V C není k dispozici dědičnost, tudíž není možné dost dobře mluvit o potomcích typu ''Node''. Můžeme ovšem hovořit o množině typů respektujících ''interface'' typu ''Node''.
<pre>
typedef struct Node
{
      NodeTag      type;
} Node;

/*
 * nodes/{outfuncs.c,print.c}
 */
extern char *nodeToString(void *obj);

/*
 * nodes/{readfuncs.c,read.c}
 */
extern void *stringToNode(char *str);

/*
 * nodes/copyfuncs.c
 */
extern void *copyObject(void *obj);

/*
 * nodes/equalfuncs.c
 */
extern bool equal(void *a, void *b);

typedef struct Value
{
      NodeTag      type;           /* tag appropriately (eg. T_String) */
      union ValUnion
      {
            long      ival;         /* machine integer */
            char   *str;            /* string */
      }           val;
} Value;

typedef struct Value
{
      NodeTag      type;           /* tag appropriately (eg. T_String) */
      union ValUnion
      {
            long     ival;          /* machine integer */
            char   *str;            /* string */
      }           val;
} Value;
</pre>
Typu respektující interface ''Node'' se v PostgreSQL vyskytují ve všech modulech - v parseru, optimalizéru, v executoru, v interních knihovnách. Všude, kde je nutné řešit serializaci, deserializaci. Všude, kde je potřeba řešit ''hluboké kopírování''. Generický typ ''List'' respektuje ''Node'' interface. V některých případech z meta dat funkce můžeme zjistit kontext volání funkce. Opět tato metadata typicky respektují interface ''Node''. Množinu typů respektujících interface ''Node'' nelze rozšiřovat bez změny zdrojových kódů PostgreSQL - primárně rozšíření výčtu ''NodeTag''.

Pokud datový typ respektuje interface ''Node'', tak pak můžeme ověřit, zda-li je nebo není nějaká struktura určitého typu. Používá se makro ''IsA'':
<pre>
#define nodeTag(nodeptr)            (((Node*)(nodeptr))->type)
#define IsA(nodeptr,_type_)             (nodeTag(nodeptr) == T_##_type_)
</pre>

V kódu PostgreSQL se často setkáváme  hierarchií struktur respektujících interface ''Node'':
<pre>
struct ExprState
{
      NodeTag>      type;
      Expr   *expr;           /* associated Expr node */
      ExprStateEvalFunc evalfunc; /* routine to run to execute node */
};

/* ----------------
 *      GenericExprState node
 *
 * This is used for Expr node types that need no local run-time state,
 * but have one child Expr node.
 * ----------------
 */
typedef struct GenericExprState
{
      ExprState xprstate;
      ExprState  *arg;                  /* state of my child node */
} GenericExprState;

/* ----------------
 *      AggrefExprState node
 * ----------------
 */
typedef struct AggrefExprState
{
      ExprState xprstate;
      List      *args;                  /* states of argument expressions */
      int             aggno;            /* ID number for agg within its plan node */
} AggrefExprState;

/* ----------------
 *      WindowFuncExprState node
 * ----------------
 */
typedef struct WindowFuncExprState
{
      ExprState xprstate;
      List    *args;                    /* states of argument expressions */
      int            wfuncno;           /* ID number for wfunc within its plan node */
} WindowFuncExprState;
</pre>
V následující ukázce se zjišťuje kontext volání funkce a podle tagu se určuje, zda-li byla funkce volána jako agregační nebo jako analytická (window) funkce:
<pre>
int
AggCheckCallContext(FunctionCallInfo fcinfo, MemoryContext *aggcontext)
{
      if (fcinfo->context && IsA(fcinfo->context, AggState))
      {
            if (aggcontext)
                  *aggcontext = ((AggState *) fcinfo->context)->aggcontext;
            return AGG_CONTEXT_AGGREGATE;
      }
      if (fcinfo->context && IsA(fcinfo->context, WindowAggState))
      {
            if (aggcontext)
                  *aggcontext = ((WindowAggState *) fcinfo->context)->aggcontext;
            return AGG_CONTEXT_WINDOW;
      }

      /* this is just to prevent "uninitialized variable" warnings */
      if (aggcontext)
            *aggcontext = NULL;
      return 0;
}
</pre>
K vytvoření nové struktury typu ''Node'' slouží makro ''makeNode''. Toto makro je ukázkou toho, co lze realizovat preprocesorem v C, pokud si vybudujeme šikovnou infrastrukturu datových typů a identifikátorů:
<pre>
#define newNode(size, tag) \
( \
        AssertMacro((size) >= sizeof(Node)),            /* need the tag, at least */ \
        newNodeMacroHolder = (Node *) palloc0fast(size), \
        newNodeMacroHolder->type = (tag), \
        newNodeMacroHolder \
)
#endif   /* __GNUC__ */

        
#define makeNode(_type_)                ((_type_ *) newNode(sizeof(_type_),T_##_type_))
#define NodeSetTag(nodeptr,t)   (((Node*)(nodeptr))->type = (t))
</pre>
===Operace nad zanořenými (rekurzivními) strukturami podporující interface ''Node''===
V zdrojovém kódu PostgreSQL se nejčastěji setkáme s identifikací struktury typu Node a s provedením určitých operací odpovídajících tomu či onomu subtypu:
<pre>
Node *
transformExpr(ParseState *pstate, Node *expr)
{
        Node       *result = NULL;

        if (expr == NULL)
                return NULL;

        /* Guard against stack overflow due to overly complex expressions */
        check_stack_depth();

        switch (nodeTag(expr))
        {
                case T_ColumnRef:
                        result = transformColumnRef(pstate, (ColumnRef *) expr);
                        break;

                case T_ParamRef:
                        result = transformParamRef(pstate, (ParamRef *) expr);
                        break;

                case T_A_Const:
                        {
                                A_Const    *con = (A_Const *) expr;
                                Value      *val = &con->val;

                                result = (Node *) make_const(pstate, val, con->location);
                                break;
                        }
                    ...

                case T_ArrayCoerceExpr:
                case T_ConvertRowtypeExpr:
                case T_CollateExpr:
                case T_CaseTestExpr:
                case T_ArrayExpr:
                case T_CoerceToDomain:
                case T_CoerceToDomainValue:
                case T_SetToDefault:
                        {
                                result = (Node *) expr;
                                break;
                        }                                                                                 
                
                default:
                        /* should not reach here */
                        elog(ERROR, "unrecognized node type: %d", (int) nodeTag(expr));
                        break;
        }
      
        return result;                                                                                   
}
</pre>
již bylo zmíněno, že data uložená ve strukturách typu Node lze porovnávat, kopírovat (fce ''copyObject()''), porovnávat (fce ''equal()''), serializovat (fce ''nodeToString()'' a načítat (fce ''stringToNode()''). 

Pro porovnávání a kopírování nelze použít funkce, které přistupují přímo k paměti. Při kopírování se vytváří nezávislá kopie včetně vnořených položek. Při porovnávání se zase ignoruje položka ''location''. 

Implementace opět intenzivně používá makra.

Kopírování:
<pre>
/* Copy a simple scalar field (int, float, bool, enum, etc) */
#define COPY_SCALAR_FIELD(fldname) \
        (newnode->fldname = from->fldname)

/* Copy a field that is a pointer to some kind of Node or Node tree */
#define COPY_NODE_FIELD(fldname) \
        (newnode->fldname = copyObject(from->fldname))

/* Copy a field that is a pointer to a Bitmapset */
#define COPY_BITMAPSET_FIELD(fldname) \
        (newnode->fldname = bms_copy(from->fldname))

/* Copy a field that is a pointer to a C string, or perhaps NULL */
#define COPY_STRING_FIELD(fldname) \
        (newnode->fldname = from->fldname ? pstrdup(from->fldname) : (char *) NULL)

/*
 * _copyNamedArgExpr *
 */
static NamedArgExpr *
_copyNamedArgExpr(NamedArgExpr *from)
{
        NamedArgExpr *newnode = makeNode(NamedArgExpr);

        COPY_NODE_FIELD(arg);
        COPY_STRING_FIELD(name);
        COPY_SCALAR_FIELD(argnumber);
        COPY_LOCATION_FIELD(location);
        
        return newnode;
}
</pre>
Test na ekvivalenci:
<pre>
/* Compare a simple scalar field (int, float, bool, enum, etc) */
#define COMPARE_SCALAR_FIELD(fldname) \
        do { \
                if (a->fldname != b->fldname) \
                        return false; \
        } while (0)

/* Compare a field that is a pointer to some kind of Node or Node tree */
#define COMPARE_NODE_FIELD(fldname) \
        do { \
                if (!equal(a->fldname, b->fldname)) \
                        return false; \
        } while (0)

/* Compare a field that is a pointer to a Bitmapset */
#define COMPARE_BITMAPSET_FIELD(fldname) \
        do { \
                if (!bms_equal(a->fldname, b->fldname)) \
                        return false; \
        } while (0)

/* Compare a field that is a pointer to a C string, or perhaps NULL */
#define COMPARE_STRING_FIELD(fldname) \
        do { \
                if (!equalstr(a->fldname, b->fldname)) \
                        return false; \
        } while (0)

static bool
_equalNamedArgExpr(NamedArgExpr *a, NamedArgExpr *b)
{
        COMPARE_NODE_FIELD(arg);
        COMPARE_STRING_FIELD(name);
        COMPARE_SCALAR_FIELD(argnumber);
        COMPARE_LOCATION_FIELD(location);

        return true;
}
</pre>
Serializace:
<pre>
#define WRITE_NODE_TYPE(nodelabel) \
        appendStringInfoString(str, nodelabel)

/* Write an integer field (anything written as ":fldname %d") */
#define WRITE_INT_FIELD(fldname) \
        appendStringInfo(str, " :" CppAsString(fldname) " %d", node->fldname)

/* Write an unsigned integer field (anything written as ":fldname %u") */
#define WRITE_UINT_FIELD(fldname) \
        appendStringInfo(str, " :" CppAsString(fldname) " %u", node->fldname)

/* Write an OID field (don't hard-wire assumption that OID is same as uint) */
#define WRITE_OID_FIELD(fldname) \
        appendStringInfo(str, " :" CppAsString(fldname) " %u", node->fldname)

/* Write a long-integer field */
#define WRITE_LONG_FIELD(fldname) \
        appendStringInfo(str, " :" CppAsString(fldname) " %ld", node->fldname)

/* Write a char field (ie, one ascii character) */
#define WRITE_CHAR_FIELD(fldname) \
        appendStringInfo(str, " :" CppAsString(fldname) " %c", node->fldname)

/* Write an enumerated-type field as an integer code */
#define WRITE_ENUM_FIELD(fldname, enumtype) \
        appendStringInfo(str, " :" CppAsString(fldname) " %d", \
                                         (int) node->fldname)

/* Write a float field --- caller must give format to define precision */
#define WRITE_FLOAT_FIELD(fldname,format) \
        appendStringInfo(str, " :" CppAsString(fldname) " " format, node->fldname)

/* Write a boolean field */
#define WRITE_BOOL_FIELD(fldname) \
        appendStringInfo(str, " :" CppAsString(fldname) " %s", \
                                         booltostr(node->fldname))

/* Write a character-string (possibly NULL) field */
#define WRITE_STRING_FIELD(fldname) \
        (appendStringInfo(str, " :" CppAsString(fldname) " "), \
         _outToken(str, node->fldname))


static void
_outNamedArgExpr(StringInfo str, NamedArgExpr *node)
{
        WRITE_NODE_TYPE("NAMEDARGEXPR");
        
        WRITE_NODE_FIELD(arg);
        WRITE_STRING_FIELD(name);
        WRITE_INT_FIELD(argnumber);
        WRITE_LOCATION_FIELD(location);
}
</pre>

===Použití iterátorů a mutátorů===
Vzájemně se referencující struktury typu ''Node'' vytvářejí dynamickou super strukturu dat a vzájemných vztahů se kterou je nutné transformovat, zjednodušovat, rozpoznávat. Tato superstruktura není nesena abstraktní datovou strukturou, tudíž nelze jednoduše iterovat napříč touto strukturou. Navíc jazyk C nezpřístupňuje (minimálně ne jednoduše) popis jednotlivých struktur - tudíž nelze použít postupy založené na sebereflexi. V PostgreSQL se tento problém řeší pomocí tzv. iterátorů nebo mutátorů - což jsou funkce, uvnitř kterých je natvrdo zakódována struktura struktur typu ''Node'', a které umožňují pro každou identifikovanou hodnotu zavolat ''callback'' funkci.

Iteraci napříč strukturami lze přerušit vrácením true z callback funkce.
<pre>
 
bool
expression_tree_walker(Node *node,
                                           bool (*walker) (),
                                           void *context)
{
        ListCell   *temp;
 
        /*
         * The walker has already visited the current node, and so we need only
         * recurse into any sub-nodes it has.
         *
         * We assume that the walker is not interested in List nodes per se, so
         * when we expect a List we just recurse directly to self without
         * bothering to call the walker.
         */
        if (node == NULL)
                return false;

        /* Guard against stack overflow due to overly complex expressions */
        check_stack_depth();

        switch (nodeTag(node))
        {
                case T_Var:
                case T_Const:
                case T_Param:
                case T_CoerceToDomainValue:
                case T_CaseTestExpr:
                case T_SetToDefault:
                case T_CurrentOfExpr:
                case T_RangeTblRef:
                case T_SortGroupClause:
                        /* primitive node types with no expression subnodes */
                        break;
                case T_Aggref:
                        {
                                Aggref     *expr = (Aggref *) node;

                                /* recurse directly on List */
                                if (expression_tree_walker((Node *) expr->args,
                                                                                   walker, context))
                                        return true;
                                if (expression_tree_walker((Node *) expr->aggorder,
                                                                                   walker, context))
                                        return true;
                                if (expression_tree_walker((Node *) expr->aggdistinct,
                                                                                   walker, context))
                                        return true;
                        }
                        break;
                         ...

                case T_List:
                        foreach(temp, (List *) node)
                        {
                                if (walker((Node *) lfirst(temp), context))
                                        return true;
                        }
                        break;

                         ...

                case T_PlaceHolderInfo:
                        return walker(((PlaceHolderInfo *) node)->ph_var, context);
                default:
                        elog(ERROR, "unrecognized node type: %d",
                                 (int) nodeTag(node));
                        break;
        }
        return false;
}
</pre>

Úkolem iterátoru je zavolat callback funkci pro každou referenci na strukturu typu ''Node'' ve vybraných strukturách typu ''Node''. Iterátory jsou vždy zaměřené na hodnoty vyskytující se v určitém procesu zpracování SQL příkazů: surový dotaz, transformovaný dotaz, plán (ukázka obsahuje iterátor pro struktury typu ''Node'' použité pro implementaci výrazů). 

Callback funkce používané v kombinaci s iterátory obsahují rozskok podle podtypu a případnou volání iterátoru:
<pre>
static Bitmapset *
find_unaggregated_cols(AggState *aggstate)
{
        Agg                *node = (Agg *) aggstate->ss.ps.plan;
        Bitmapset  *colnos;

        colnos = NULL;
        (void) find_unaggregated_cols_walker((Node *) node->plan.targetlist,
                                                                                 &colnos);
        (void) find_unaggregated_cols_walker((Node *) node->plan.qual,
                                                                                 &colnos);
        return colnos;
}
 
static bool
find_unaggregated_cols_walker(Node *node, Bitmapset **colnos)
{
        if (node == NULL)
                return false;
        if (IsA(node, Var))
        {
                Var                *var = (Var *) node;
        
                /* setrefs.c should have set the varno to OUTER */
                Assert(var->varno == OUTER);
                Assert(var->varlevelsup == 0);
                *colnos = bms_add_member(*colnos, var->varattno);
                return false;
        }
        if (IsA(node, Aggref))          /* do not descend into aggregate exprs */
                return false;
        return expression_tree_walker(node, find_unaggregated_cols_walker,
                                                                  (void *) colnos);
}
</pre>

Mutátor slouží k modifikování stávající super struktury. Mutátor vytváří novou upravenou kopii dat. Stávající data zůstávají nezměněna.
<pre>
Node *
expression_tree_mutator(Node *node,
                                                Node *(*mutator) (),
                                                void *context)
{
        /*
         * The mutator has already decided not to modify the current node, but we
         * must call the mutator for any sub-nodes.
         */
         
#define FLATCOPY(newnode, node, nodetype)  \
        ( (newnode) = (nodetype *) palloc(sizeof(nodetype)), \
          memcpy((newnode), (node), sizeof(nodetype)) )
        
#define CHECKFLATCOPY(newnode, node, nodetype)  \
        ( AssertMacro(IsA((node), nodetype)), \
          (newnode) = (nodetype *) palloc(sizeof(nodetype)), \
          memcpy((newnode), (node), sizeof(nodetype)) )
          
#define MUTATE(newfield, oldfield, fieldtype)  \
                ( (newfield) = (fieldtype) mutator((Node *) (oldfield), context) )

        if (node == NULL)
                return NULL;
        
        /* Guard against stack overflow due to overly complex expressions */
        check_stack_depth();

        switch (nodeTag(node))
        {
                        /*
                         * Primitive node types with no expression subnodes.  Var and
                         * Const are frequent enough to deserve special cases, the others
                         * we just use copyObject for.
                         */
                case T_Var:
                        {
                                Var                *var = (Var *) node;
                                Var                *newnode;
                           
                                FLATCOPY(newnode, var, Var);
                                return (Node *) newnode;
                        }
                        break;
                case T_Const:
                        {
                                Const      *oldnode = (Const *) node;
                                Const      *newnode;

                                FLATCOPY(newnode, oldnode, Const);
                                /* XXX we don't bother with datumCopy; should we? */
                                return (Node *) newnode;
                        }
                        break;
                case T_Param:
                case T_CoerceToDomainValue:
                case T_CaseTestExpr:
                case T_SetToDefault:
                case T_CurrentOfExpr:
                case T_RangeTblRef:
                case T_SortGroupClause:
                        return (Node *) copyObject(node);
                     ....
                case T_List:
                        {
                                /*
                                 * We assume the mutator isn't interested in the list nodes
                                 * per se, so just invoke it on each list element. NOTE: this
                                 * would fail badly on a list with integer elements!
                                 */
                                List       *resultlist;
                                ListCell   *temp;

                                resultlist = NIL;
                                foreach(temp, (List *) node)
                                {
                                        resultlist = lappend(resultlist,
                                                                                 mutator((Node *) lfirst(temp),
                                                                                                 context));
                                }
                                return (Node *) resultlist;
                        }
                        break;

                     ....

                case T_PlaceHolderInfo:
                        {
                                PlaceHolderInfo *phinfo = (PlaceHolderInfo *) node;
                                PlaceHolderInfo *newnode;
 
                                FLATCOPY(newnode, phinfo, PlaceHolderInfo);
                                MUTATE(newnode->ph_var, phinfo->ph_var, PlaceHolderVar *);
                                /* Assume we need not copy the relids bitmapsets */
                                return (Node *) newnode;
                        }
                        break;
                default:
                        elog(ERROR, "unrecognized node type: %d",
                                 (int) nodeTag(node));
                        break;
        }
        /* can't get here, but keep compiler happy */
        return NULL;
}
</pre>

''expression_tree_mutator'' se používá např. při substituci a vyhodnocení konstant v SQL příkazu:
<pre>
static Node *
eval_const_expressions_mutator(Node *node,
                                                           eval_const_expressions_context *context)
{
        if (node == NULL)
                return NULL;

               ...
        if (IsA(node, FuncExpr))
        {
                FuncExpr   *expr = (FuncExpr *) node;
                List       *args;
                bool            has_named_args;
                Expr       *simple;
                FuncExpr   *newexpr;
                ListCell   *lc;

                /*
                 * Reduce constants in the FuncExpr's arguments, and check to see if
                 * there are any named args.
                 */
                args = NIL;
                has_named_args = false;
                foreach(lc, expr->args)
                {
                        Node       *arg = (Node *) lfirst(lc);

                        arg = eval_const_expressions_mutator(arg, context);
                        if (IsA(arg, NamedArgExpr))
                                has_named_args = true;
                        args = lappend(args, arg);
                }
        
                /*
                 * Code for op/func reduction is pretty bulky, so split it out as a
                 * separate function.  Note: exprTypmod normally returns -1 for a
                 * FuncExpr, but not when the node is recognizably a length coercion;
                 * we want to preserve the typmod in the eventual Const if so.
                 */
                simple = simplify_function(expr->funcid,
                                                                   expr->funcresulttype, exprTypmod(node),
                                                                   expr->funccollid,
                                                                   expr->inputcollid,
                                                                   &args,
                                                                   has_named_args, true, context);
                if (simple)                             /* successfully simplified it */
                        return (Node *) simple;
                
                /*
                 * The expression cannot be simplified any further, so build and
                 * return a replacement FuncExpr node using the possibly-simplified
                 * arguments.  Note that we have also converted the argument list to
                 * positional notation.
                 */
                newexpr = makeNode(FuncExpr);
                newexpr->funcid = expr->funcid;
                newexpr->funcresulttype = expr->funcresulttype;
                newexpr->funcretset = expr->funcretset;
                newexpr->funcformat = expr->funcformat;
                newexpr->funccollid = expr->funccollid;
                newexpr->inputcollid = expr->inputcollid;
                newexpr->args = args;
                newexpr->location = expr->location;
                return (Node *) newexpr;
        }

               ...

        if (IsA(node, CoalesceExpr))
        {
                CoalesceExpr *coalesceexpr = (CoalesceExpr *) node;
                CoalesceExpr *newcoalesce;
                List       *newargs;
                ListCell   *arg;
                                
                newargs = NIL;
                foreach(arg, coalesceexpr->args)
                {
                        Node       *e;
                
                        e = eval_const_expressions_mutator((Node *) lfirst(arg),
                                                                                           context);
                
                        /*
                         * We can remove null constants from the list. For a non-null
                         * constant, if it has not been preceded by any other
                         * non-null-constant expressions then it is the result.
                         * Otherwise, it's the next argument, but we can drop following
                         * arguments since they will never be reached.
                         */
                        if (IsA(e, Const))
                        {
                                if (((Const *) e)->constisnull)
                                        continue;       /* drop null constant */
                                if (newargs == NIL)
                                        return e;       /* first expr */
                                newargs = lappend(newargs, e);
                                break;
                        }
                        newargs = lappend(newargs, e);
                }
                
                /* If all the arguments were constant null, the result is just null */
                if (newargs == NIL)
                        return (Node *) makeNullConst(coalesceexpr->coalescetype,
                                                                                  -1,
                                                                                  coalesceexpr->coalescecollid);
        
                newcoalesce = makeNode(CoalesceExpr);
                newcoalesce->coalescetype = coalesceexpr->coalescetype;
                newcoalesce->coalescecollid = coalesceexpr->coalescecollid;
                newcoalesce->args = newargs;
                newcoalesce->location = coalesceexpr->location;
                return (Node *) newcoalesce;
        }

               ...

        if (IsA(node, PlaceHolderVar) &&context->estimate)
        {
                /*
                 * In estimation mode, just strip the PlaceHolderVar node altogether;
                 * this amounts to estimating that the contained value won't be forced
                 * to null by an outer join.  In regular mode we just use the default
                 * behavior (ie, simplify the expression but leave the PlaceHolderVar
                 * node intact).
                 */
                PlaceHolderVar *phv = (PlaceHolderVar *) node;

                return eval_const_expressions_mutator((Node *) phv->phexpr,
                                                                                          context);
        }
                
        /*
         * For any node type not handled above, we recurse using
         * expression_tree_mutator, which will copy the node unchanged but try to
         * simplify its arguments (if any) using this routine. For example: we
         * cannot eliminate an ArrayRef node, but we might be able to simplify
         * constant expressions in its subscripts.
         */
        return expression_tree_mutator(node, eval_const_expressions_mutator,
                                                                   (void *) context);
}
</pre>

Použití iterátorů a mutátorů se snížil počet chyb v PostgreSQL, které byly způsobeny zavedením nové struktury typu ''Node''. Na druhou stranu, použití mutátorů zvyšuje paměťovou náročnost - dochází k intenzivnímu kopírování dat, přičemž k uvolňování paměti dochází až v okamžiku ukončení procesu - např. po vytvoření prováděcího plánu, po dokončení zpracování SQL příkazu.

==Seznamy a základní operace se seznamy v PostgreSQL==
Implementace generického jednosměrného seznamu ''List'' umožňuje efektivní přidávání prvku na konec nebo začátek seznamu a iteraci přes prvky uložené v seznamu. Jeho použití je nezvykle časté - viz parser (traduje se, že se jedná o pozůstatek z dob, kdy byl planner Postgres implementován v Lispu). Typ ''List'' podporuje interface ''Node'' a je jedním ze základních prvků komplexních datových struktur. Funkcí ''list_makeN'' inicializujeme seznam s ''N'' prvky. Funkce ''lappend'' slouží k přidání prvku na konec seznamu. V parseru, který je založen na gramatice zapsané v ''Bizonu'' (''Yaccu'') je typickou konstrukcí parsování seznamu hodnot oddělených čárkou:
<pre>
alter_generic_option_list:
                          alter_generic_option_elem
                                   {
                                            $$ = list_make1($1);
                                   }
                          | alter_generic_option_list ',' alter_generic_option_elem
                                   {
                                            $$ = lappend($1, $3);
                                   }
                ;
</pre>
K iteraci nad seznamem se používá makro ''foreach'' a makro ''lfirst''.V následující ukázce dochází k transformaci seznamu. Pokud dohází k transformaci interních struktur, tak až výjimky nedochází k modifikaci originálních struktur. Originální data zůstávají - nedochází ani k jejich uvolňování. Alokovaná paměť se uvolňuje až ve chvíli, kdy je zrušen aktuální paměťový kontext. Např. při generování prováděcího plánu je vytvořen dočasný paměťový kontext, který se stane aktuálním kontextem. Poté dojde k vytvoření prováděcího plánu. Následně se prováděcí plán zkopíruje (''deep copy'') do nadřazeného kontextu a aktuální kontext ze uvolní. Tím automaticky dojde k uvolnění všech dočasných dat. Tento přístup k paměti je poměrně náročný - nicméně potřeba paměti je zanedbatelná vzhledem k spotřebě paměti při realizaci datových operací - ''sort'', ''hashjoin'', ''hashagg''. Výhodou je čitelnější a jednodušší kód s menším pravděpodobností kritických chyb. Pozn: při optimalizaci extrémně velkých dotazů může dojít k použití virtuální paměti.
<pre>
exprList = NIL;
foreach(lc, selectQuery->targetList)
{
       TargetEntry *tle = (TargetEntry *) lfirst(lc);
       Expr       *expr;
        
       if (tle->resjunk)
              continue;
       if (tle->expr &&
              (IsA(tle->expr, Const) ||IsA(tle->expr, Param)) &&
                            exprType((Node *) tle->expr) == UNKNOWNOID)
              expr = tle->expr;
       else
       {
              Var  *var = makeVarFromTargetEntry(rtr->rtindex, tle);
 
              var->location = exprLocation((Node *) tle->expr);
              expr = (Expr *) var;
       }
       exprList = lappend(exprList, expr);
}
</pre>
Definice typů ''List'' a ''ListCell'' je následující:
<pre>
typedef struct ListCell ListCell;

typedef struct List
{
        NodeTag         type;                   /* T_List, T_IntList, or T_OidList */
        int                     length;
        ListCell   *head;
        ListCell   *tail;
} List;

struct ListCell
{
        union
        {
                void       *ptr_value;
                int                     int_value;
                Oid                     oid_value;
        }                       data;
        ListCell   *next;
};

/*
 * The *only* valid representation of an empty list is NIL; in other
 * words, a non-NIL list is guaranteed to have length >= 1 and
 * head/tail != NULL
 */
#define NIL    ((List *) NULL)

static inline ListCell *
list_head(List *l)
{
        return l ? l->head : NULL;
}
</pre>
Důležité makro ''lfirst'' vrací obsah prvního prvku seznamu - parametrem je ukazatel na ''ListCell'':
<pre>
#define lfirst(lc)         ((lc)->data.ptr_value)
</pre>
Makro ''foreach'' zapouzdřuje deklaraci příkazu ''for'':
<pre>
/*
 * foreach -
 *        a convenience macro which loops through the list
 */
#define foreach(cell, l)        \
        for ((cell) = list_head(l); (cell) != NULL; (cell) = lnext(cell))
</pre>
Dále existují makra pro přístup k prvnímu prvku seznamu ''linitial'', k druhému prvku seznamu ''lsecond'' atd (k poslednímu prvku seznamu ''llast'').

Při rozvinutí maker může jednoduchá iterace nad prvky seznamu vypadat následovně:
<pre>
List *l ;
ListCell *lc;

l = ..;
for ((lc) = list_head(l); (lc) != NULL; (lc) = lnext(lc))
{
       Datum d = (Datum) ((lc)->data.ptr_value);
       ...
}
</pre>
K dispozici jsou všechny operace, které očekáváme od seznamu - vrácení n-tého prvku, oříznutí seznamu, sloučení dvou seznamů, rozdíl dvou seznamů, test zda-li je hodnota prvkem seznamu či nikoliv, funkce ''list_copy'' představuje tzv ''shallow copy'' (mělké kopírování - vytváří se pouze struktur obsahujících seznamu - ''List'' a ''ListCell'', nedochází ke kopírování dat uložených v seznamu. Hluboké kopírování (''deep copy'') je možné pouze tehdy, když seznam obsahuje pouze ''Oid'' případně ''Int'' hodnoty - nebo ukazatele na ''varlena'' hodnoty.

==Vyvolání výjimky==
PostgreSQL interně používá vlastní systém výjimek založený na ''Longjmp'' a ''SetJmp''. Starší funkce, kterou je možné použít k vyvolání výjimky je funkce ''elog''. K dispozici je několik úrovní výjimek - varování (''WARNING'') a oznámení (''NOTICE'') nelze zachytit (zrovna tak nelze zachytit úrovně ''FATAL'' a ''PANIC'':
<pre>
        if (!HeapTupleIsValid(tuple))
                elog(ERROR, "cache lookup failed for language %u", langId);
</pre>
Podstatně bohatší možnosti nabízí funkce ''ereport'', která umožňuje do ve výjimce přenést ''SQLSTATE'' kód, detailní popis chyby, zjednodušenou nápovědu:
<pre>
if (!rsi || !IsA(rsi, ReturnSetInfo) ||
            (rsi->allowedModes & SFRM_Materialize) == 0 || rsi->expectedDesc == NULL)
                     ereport(ERROR,
                                         (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                                          errmsg("set-valued function called in context that cannot accept a set")));
</pre>
V případě, že výjimka není zachycena, tak je přeposlána na klienta. Ještě před tím dojde ke sběru informací o jednotlivých kontextech - simuluje se tím výpis zásobníku ''call-stack traceback''. Pokud vývojář chce poskytnout informaci o některém kontextu procesu může si zaregistrovat callback funkci. Registrací callback funkcí se vytváří vázaný seznam obsahující adresy funkcí. Voláním callback funkcí v opačném pořadí než byly zaregistrovány získáme seznam informačních textů chronologicky popisující jednotlivé chybové (funkční) kontexty (od nejmladšího po nejstarší). Tuto callback funkci nelze použít pro uvolnění zdrojů - nemusí být vždy volána (pokud je výjimka zachycena, tak nemá cenu sbírat ladící informace). Uvnitř této funkce nelze přistupovat k datům v tabulkách - jelikož došlo k přerušení transakce a teprve se čeká na ROLLBACK.
<pre>
static void
plpsm_exec_error_callback(void *arg)                    
{
        DebugInfo dinfo = (DebugInfo) arg;
        StringInfoData  ds;
                        
        if (dinfo->is_signal)
                return;

        initStringInfo(&ds);       
        appendStringInfo(&ds, "PLPSM function \"%s\"  Oid %d line %d\n\n", dinfo->module->code->name,
                                                                                            dinfo->module->oid,
                                                                                            pcode->lineno);                
        errcontext("%s", ds.data);
        pfree(ds.data);
}
</pre>
Registrace a deregistrace kontext callback funkce:
<pre>
Datum
plpsm_func_execute(Plpsm_module *mod, FunctionCallInfo fcinfo)
{
        ErrorContextCallback plerrcontext;
        DebugInfoData   dinfo;
        Datum result;

        /* 
         * Registrace callback funkce. Stávající errcontext se připojí k nově vytvořenému
         * chybovému kontextu, a nově vytvořený kontext se prohlásí za aktuální.
         */
        plerrcontext.callback = plpsm_exec_error_callback;
        plerrcontext.arg = &dinfo;
        plerrcontext.previous = error_context_stack;
        error_context_stack = &plerrcontext;

        /*
         * zde probíhá zpracování funkce
         */
        result = (Datum) ...

        /* 
         * K výjimce nedošlo, stávající chybový kontext zaniká. Vracíme se k přechozímu
         * chybovému kontextu.
         */
         error_context_stack = plerrcontext.previous; 
         return result;
} 
</pre>

==Zachycení a ošetření výjimek==
Výjimky jsou v PostgreSQL zachytávány primárně kvůli potřebě uvolnit "zdroje", které by v případě chyby nebyly uvolněny jiným mechanismem. Uvnitř PostgreSQL je každá zachycená výjimka po uvolnění zdrojů znovu vyvolána, přičemž absolutní zachycení výjimky je ošetřeno až na nejvyšší úrovni odvoláním aktuální transakce (přerušením zpracovávaného dotazu) a odesláním chybového hlášení uživateli. '''Pokud nedojde k odvolání aktuální transakce, tak zásadní interní datové struktury mohou být neinicializované nebo nevalidní. Jakákoliv trochu složitější operace přistupující k datům v db pak obvykle skončí pádem serveru.'''. Blok, kde lze zachytit výjimku vytvoříme pomocí maker ''PG_TRY'', ''PG_CATCH'' a ''PG_END_TRY'':
<pre>
PG_TRY();
{
      saveResourceOwner = CurrentResourceOwner;
      ...
 
}
PG_CATCH();
{
      /*
       * Po chybě vracíme resourceOwner na původní hodnotu.
       */
      CurrentResourceOwner = saveResourceOwner;

      /*
       * Přeposlání výjimky
       */
      PG_RE_THROW();
}
PG_END_TRY();
</pre>
Tato makra jsou definována jako:
<pre>
#define PG_TRY()  \
        do { \
                sigjmp_buf *save_exception_stack = PG_exception_stack; \
                ErrorContextCallback *save_context_stack = error_context_stack; \
                sigjmp_buf local_sigjmp_buf; \
                if (sigsetjmp(local_sigjmp_buf, 0) == 0) \
                { \
                        PG_exception_stack = &local_sigjmp_buf
                
#define PG_CATCH()      \
                } \
                else \
                { \
                        PG_exception_stack = save_exception_stack; \
                        error_context_stack = save_context_stack
 
#define PG_END_TRY()  \
                } \
                PG_exception_stack = save_exception_stack; \
                error_context_stack = save_context_stack; \
        } while (0)
</pre>

Uvnitř bloku zachycení výjimky můžeme přistupovat k datové struktuře ''ErrorData'', která drží strukturu výjimky. V tento okamžik je také možné zavolat callback kontextové funkce:
<pre>
typedef struct ErrorData
{
        int                     elevel;                 /* error level */
        bool            output_to_server;               /* will report to server log? */
        bool            output_to_client;               /* will report to client? */
        bool            show_funcname;  /* true to force funcname inclusion */
        bool            hide_stmt;              /* true to prevent STATEMENT: inclusion */
        const char *filename;           /* __FILE__ of ereport() call */
        int                     lineno;                 /* __LINE__ of ereport() call */
        const char *funcname;           /* __func__ of ereport() call */
        const char *domain;                     /* message domain */
        int                     sqlerrcode;             /* encoded ERRSTATE */
        char       *message;            /* primary error message */
        char       *detail;                     /* detail error message */
        char       *detail_log;         /* detail error message for server log only */
        char       *hint;                       /* hint message */
        char       *context;            /* context message */
        int                     cursorpos;              /* cursor index into query string */
        int                     internalpos;    /* cursor index into internalquery */
        char       *internalquery;      /* text of internally-generated query */
        int                     saved_errno;    /* errno at entry */
} ErrorData;
</pre>
Data atuální výjimky jsou nedostupná, jsou uložená v lokální proměnné modulu, přičemž ovšem lze získat kopii dat voláním funkce ''CopyErrorData''.

Pokud výjimka nebude opětovně vyvolána, je nezbytné použít subtransakci, která bude případně odvolána uvnitř obsloužení výjimky:
<pre>
MemoryContext oldcontext = CurrentMemoryContext;
ResourceOwner oldowner = CurrentResourceOwner;

BeginInternalSubTransaction(NULL);
/* Want to run statements inside function's memory context */
MemoryContextSwitchTo(oldcontext);

PG_TRY();
{
 ...
     /* Commit the inner transaction, return to outer xact context */
     ReleaseCurrentSubTransaction();
     MemoryContextSwitchTo(oldcontext);
     CurrentResourceOwner = oldowner;

     /*
      * AtEOSubXact_SPI() should not have popped any SPI context, but
      * just in case it did, make sure we remain connected.
      */
      SPI_restore_connection();
}       
PG_CATCH();
{
      ErrorData  *edata;
      ListCell   *e;

      /* Save error info */
      MemoryContextSwitchTo(oldcontext);
      edata = CopyErrorData();

      FlushErrorState();

      RollbackAndReleaseCurrentSubTransaction();
      MemoryContextSwitchTo(oldcontext);
      CurrentResourceOwner = oldowner;

      ....

      if (e == NULL)
               ReThrowError(edata);
      else
               FreeErrorData(edata);
}
PG_END_TRY();
</pre>
Funkce ''FlushErrorState()'' čistí chybový zásobník - volá se tehdy, když jsou data výjimky zkopírována.
==Deskriptor složeného typu ''TupleDesc''==
Pokud chceme přistupovat k položkám kompozitních typů, tak musíme znát (mít k dispozici) popis té či oné kompozitní hodnoty. Tento popis je v PostgreSQL uložen ve struktuře ''TupleDesc''. Ačkoliv tato struktura není rekurzivní, umožňuje, spolu s dalšími mechanismy, pracovat s vnořenými (nested) kompozitními hodnotami. Popis kompozitní hodnoty obsahuje primárně počet položek a jejich typ. Kompozitní hodnoty mohou být dočasné (anonymní) nebo persistentní neanonymní.
<pre>
CREATE TYPE o_type AS (a integer, b int);
CREATE TABLE x(a int, b int);
</pre>
Výše uvedené příkazy, kromě jiného, vytvořily neanonymní typy ''o_type'' a ''x''. Na tyto identifikátory lze použít pří přetypování anonymní hodnoty:
<pre>
postgres=# select (row(10,20)::x).*;
 a  | b  
----+----
 10 | 20
(1 row)

postgres=# select (row(10,20)::o_type).*;
 a  | b  
----+----
 10 | 20
(1 row)
</pre>
Struktura těchto typů je uložená v tabulkách ''pg_type'' a ''pg_attributte'' - čímž je zafixovaná - perzistentní. V PostgreSQL vznikají i dočasné kompozitní hodnoty - např. jako výsledek funkce s OUT proměnnými. U těchto dočasných hodnot vznikají metadata zároveň se vznikem dat, a po zániku dat zanikají i metadata. Protože tato data rychle vznikají a rychle zanikají, nepracuje se s systémovými tabulkami, ale přímo s cache.

Struktura ''TupleDesc'' (access/tupdesc.h) vypadá následovně:
<pre>
typedef struct tupleDesc
{
        int                     natts;                  /* number of attributes in the tuple */
        Form_pg_attribute *attrs;
        /* attrs[N] is a pointer to the description of Attribute Number N+1 */
        TupleConstr *constr;            /* constraints, or NULL if none */
        Oid                     tdtypeid;               /* composite type ID for tuple type */
        int32           tdtypmod;               /* typmod for tuple type */
        bool            tdhasoid;               /* tuple has oid attribute in its header */
        int                     tdrefcount;             /* reference count, or -1 if not counting */
}       *TupleDesc;
</pre>

Kompozitní neanonymní typ má unikátní object identifier ''oid'' a je dohledatelný v systémové tabulce ''pg_type''. Strukturu ''TupleDesc'' na základě oid typu vytvoří funkce <tt>lookup_rowtype_tupdesc(rectuptyp, rectuptypmod);</tt>. Tuto funkci můžeme použít i pro anonymní typy - typ ''RECORD''.
<pre>
static TupleDesc
lookup_rowtype_tupdesc_internal(Oid type_id, int32 typmod, bool noError)
{
        if (type_id != RECORDOID)
        {
                /*
                 * It's a named composite type, so use the regular typcache.
                 */
                TypeCacheEntry *typentry;

                typentry = lookup_type_cache(type_id, TYPECACHE_TUPDESC);
                if (typentry->tupDesc == NULL && !noError)
                        ereport(ERROR,
                                        (errcode(ERRCODE_WRONG_OBJECT_TYPE),
                                         errmsg("type %s is not composite",
                                                        format_type_be(type_id))));
                return typentry->tupDesc;
        }
        else
        {
                /*
                 * It's a transient record type, so look in our record-type table.
                 */
                if (typmod < 0 || typmod >= NextRecordTypmod)
                {
                        if (!noError)
                                ereport(ERROR,
                                                (errcode(ERRCODE_WRONG_OBJECT_TYPE),
                                                 errmsg("record type has not been registered")));
                        return NULL;
                }
                return RecordCacheArray[typmod];
        }
}
</pre>
V případě typu ''RECORD'' je významná položka ''typmod''. Na základě této položky se dohledává deskriptor v cache. Funkce, která vytvoří kompozitní hodnotu, která se dále distribuuje pod typem RECORD musí zaregistrovat deskriptor této složené hodnoty. Když se pak kompozit zpracovává, tak se přistupuje k této zaregistrované hodnotě. Registraci do cache zajišťuje funkce ''BlessTupleDesc'' - např. pokud funkce vrací kompozitní hodnotu typu RECORD, tak musí volat funkci BlessTupleDesc:
<pre>
TupleDesc
BlessTupleDesc(TupleDesc tupdesc)
{
        if (tupdesc->tdtypeid == RECORDOID &&
                tupdesc->tdtypmod < 0)
                assign_record_type_typmod(tupdesc);

        return tupdesc;                         /* just for notational convenience */
}
</pre>

Kompozitní deskriptor získáme posloupností kroků:
<pre>

HeapTupleHeader		rec = PG_GETARG_HEAPTUPLEHEADER(0);

rectuptyp = HeapTupleHeaderGetTypeId(rec);
rectuptypmod = HeapTupleHeaderGetTypMod(rec);
rectupdesc = lookup_rowtype_tupdesc(rectuptyp, rectuptypmod);
</pre>
Typ ''HeapTupleHeader'' slouží jako interface mezi C a SQL (používá se jako abstrakce pro typ RECORD a ROW typy v SQL prostoru).

Naopak při vytváření kompozitní hodnoty musíme provést:
<pre>
HeapTupleHeader		result;

resultTupleDesc = CreateTemplateTupleDesc(2, false);
TupleDescInitEntry(resultTupleDesc, (AttrNumber) 1, "file_name",
                                           TEXTOID, -1, 0);
TupleDescInitEntry(resultTupleDesc, (AttrNumber) 2, "file_offset",
                                           INT4OID, -1, 0);

resultTupleDesc = BlessTupleDesc(resultTupleDesc);

...

/*
 * Tuple jam: Having first prepared your Datums, then squash together
 */
resultHeapTuple = heap_form_tuple(resultTupleDesc, values, isnull);

/*
 * We cannot return tuple->t_data because heap_form_tuple allocates it as
 * part of a larger chunk, and our caller may expect to be able to pfree
 * our result.	So must copy the info into a new palloc chunk.
 */
result = (HeapTupleHeader) palloc(resultHeapTuple->t_len);
memcpy(result, resultHeapTuple->t_data, resultHeapTuple->t_len);

heap_freetuple(resultHeapTuple);
ReleaseTupleDesc(resultTupleDesc);

PG_RETURN_HEAPTUPLEHEADER(result);
</pre>
Poznámka: ''HeapTupleHeader'' se používá, pokud pracujeme s individuálními kompozitními hodnotami (explicitně s typem RECORD). Uvnitř funkcí, které vrací tabulku můžeme používat úspornější zápis:
<pre>
tuple = heap_form_tuple(funcctx->tuple_desc, values, nulls);
result = HeapTupleGetDatum(tuple);
PG_RETURN_DATUM(result);
</pre>
Tato konvence není příliš pochopitelná - ve skutečnosti je, ve velké většině případů, HeapTupleHeader částí HeapTuple - nedohledal jsem, proč pro RECORD se používá HeapTupleHeader a pro ostatní případy - interní funkce, SRF funkce, se používá HeapTuple.

Pro konverzi z typu HeapTuple na typ HeapTupleHeader lze použít funkci ''SPI_returntuple'' (za předpokladu, že se používá SPI API).

Poznámka 2: ''TupleDesc'' se při separaci položek z ''HeapTuple'' použije k určení pořadí položek a jejich typů (na jejich základě je určeno zarovnávání v paměti). Vlastní separace položek probíhá sekvenčně - z bloku dat se přečte vždy n bajtů, zjistí se obsah a velikost, a pokračuje se následujícími m bajty.

TupleDesc se používá i v případě, že funkce vrací kompozitní typ (případně množinu kompozitních typů). Tehdy je připravený TupleDesc výsledku a lze jej získat voláním funkce ''get_call_result_type'':
<pre>
       estate.rtinfo = plpgpsm_make_typeinfo_typeid(&estate, rettypeid, -1);
       if (func->parser->noutargs > 1)
              get_call_result_type(fcinfo, NULL, &estate.rettupdesc);
       else
              estate.rettupdesc = NULL;
</pre>
V případě, že funkce vrací množinu, pak je návratový TupleDesc dostupný pomocí struktury ''ReturnSetInfo'':
<pre>
       plpgsql_estate_setup(&estate, func, (ReturnSetInfo *) fcinfo->resultinfo);
       ...
       ReturnSetInfo *rsi = estate->rsi;
       ...
       estate->rettupdesc = rsi->expectedDesc;
</pre>