<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="memory-management" xml:lang="cs">

  <info>

    <link type="guide" xref="index#general-guidelines"/>

    <credit type="author copyright">

      <name>Philip Withnall</name>

      <email its:translate="no">philip.withnall@collabora.co.uk</email>

      <years>2015</years>

    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Správa přidělování a uvolňování paměti v C</desc>

  </info>

  <title>Správa paměti</title>

  
Zásobník GNOME je napsán převážně v jazyce C, takže dynamicky alokovaná paměť musí být spravována ručně. S použitím usnadňujícího API z GLib je však správa triviální, přesto by měli programátoři při psaní kódu na paměť vždy myslet.

  
Předpokládá se, že čtenář je dobře seznámen s principem alokace paměti na haldě s pomocí malloc() a free() a zná příslušnou dvojici obdobných funkcí z GLib g_malloc() a g_free().

  <synopsis>

    <title>Shrnutí</title>

    
Existují tři situace, kterým byste se měli vyhnout a které zde uvádíme podle důležitosti:

    <list type="numbered">

      <item>
Použití paměti po jejím uvolnění.
</item>

      <item>
Požití paměti před jejím přidělením.
</item>

      <item>
Neuvolnění paměti, která byla přidělena (tzv. únik).
</item>

    </list>

    
Klíčové principy (bez ohledu na pořadí důležitosti):

    <list>

      <item>
U každé proměnné určete a zdokumentujte, zda je či není vlastněna. Za běhu se to pak nikdy nesmí měnit. (<link xref="#principles"/>)
</item>

      <item>
Určete a zdokumentujte přenosy vlastnictví na hranicích funkcí. (<link xref="#principles"/>)
</item>

      <item>
Zajistěte, aby každé přiřazení, volání funkce a návrat z funkce respektovali příslušné přenosy vlastnictví. (<link xref="#assignments"/>, <link xref="#function-calls"/>, <link xref="#function-returns"/>)
</item>

      <item>
Kde je to možné, používejte raději počítání odkazů, než explicitní finalizaci. (<link xref="#reference-counting"/>)
</item>

      <item>
Kde je to možné, používejte vhodné funkce z GLib, jako třeba <link xref="#g-clear-object">g_clear_object()</link>. (<link xref="#convenience-functions"/>)
</item>

      <item>
Nerozdělujte správu paměti do více cest průchodu programem. (<link xref="#principles"/>)
</item>

      <item>
Používejte návrhový vzor pro jednocestné čištění pro rozsáhlé a složité funkce. (<link xref="#single-path-cleanup"/>)
</item>

      <item>
Uniky by měly být kontrolovány pomocí nástroje Valgrind nebo sanitizérem adres. (<link xref="#verification"/>)
</item>

    </list>

  </synopsis>

  <section id="principles">

    <title>Principy správy paměti</title>

    
Normální přístup ke správě paměti spočívá pro programátora v tom, mít přehled, které proměnné ukazují na alokovanou paměť a ručně ji uvolnit v situaci, kdy již není nadále potřeba. Tak je to v pořádku, ale dá se to zpřehlednit zavedením konceptu vlastnictví, což je kus kódu (například funkce, struktura nebo objekt), který je zodpovědný za uvolnění kusu alokované paměti (alokace). Každá alokace má právě jednoho vlastníka, který se ale za dobu běhu programu může měnit tzv. přenosem vlastnictví na jiný kus kódu. Každá proměnná je buď vlastněna nebo nevlastněna, podle toho, jestli je rozsah působnosti, jehož je součástí, vždy jejím vlastníkem. Každý parametr funkce a návratový typ buď přenáší vlastnictví předávané hodnoty nebo nepřenáší. V případě, že kód vlastnící nějakou paměti tuto paměť nedealokuje, dojde k úniku paměti. V případě, že kód, který nevlastní určitou paměť, tuto paměť uvolní, jedná se o dvojité uvolnění. Obojí je špatně.

    
Tím, že stačí napevno určit, které proměnné jsou vlastněné, se ze správy paměti stává jednoduchý úkol spočívající v nepodmíněném uvolňování proměnných před tím, než se opustí jejich rozsah působnosti, a v neuvolnění nevlastněných proměnných (viz <link xref="#single-path-cleanup"/>). Klíčovou otázkou pro kterýkoliv kus paměti tak je: která část kódu jej vlastní.

    
Je zde jedno důležité omezení: proměnné se za běhu nikdy nesmí změnit z vlastněných na nevlastněné (nebo naopak). Toto omezení je klíčové kvůli zjednodušení správy paměti.

    
Například mějme funkci:

    gchar *generate_string (const gchar *template);

void print_string (const gchar *str);

    
Následující kód byl opatřen anotacemi a komentáři, abyste se všimli, kde dochází k přenosu vlastnictví:

    gchar *my_str = NULL;  /* owned */

const gchar *template;  /* unowned */

GValue value = G_VALUE_INIT;  /* owned */

g_value_init (&value, G_TYPE_STRING);

/* Přenese vlastnictví řetězce z funkce do proměnné */

template = "XXXXXX";

my_str = generate_string (template);

/* Bez přenosu vlastnictví */

print_string (my_str);

/* Přenos vlastnictví. Nadále se již nemusíme starat o uvolnění @my_str. */

g_value_take_string (&value, my_str);

/* Stále vlastníme @value, takže před opuštěním této oblasti působnosti ji musíme uvolnit */

g_value_unset (&value);

    
Zastavme se u několika věcí: Za prvé, komentáře „vlastněno“ u deklarací proměnných naznačují, že tyto proměnné jsou vlastněné místním rozsahem působnosti, a proto potřebují být uvolněné před opuštěním tohoto rozsahu působnosti. Alternativou je „nevlastněno“, což znamená, že místní rozsah působnosti nemá vlastnictví a nemusí proměnnou uvolnit před opuštěním rozsahu působnosti. Obdobně, při přiřazení na něj vlastnictví nemusí být přeneseno.

    
Za druhé, modifikatory u proměnných odrážejí, jestli dochází k přenosu vlastnictví: protože my_str je vlastněna místním rozsahem působnosti, je typu gchar, zatímco template je const, což říká, že není vlastněna. Obdobně, parametr template funkce generate_string() a parametr str funkce print_string() jsou const, protože není přenášeno vlastnictví při volání těchto funkcí. Protože pro řetězcový parametr funkce g_value_take_string() je přenášeno vlastnictví, očekáváme, že její typ je gchar.

    
(Upozorňujeme, že toto se netýká objektu <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html">GObject</link> a podtříd, které nemohou být nikdy const. Týká se to jen řetězců a jednoduchých struktur struct.)

    
A na konec, pár knihoven používá zvyklosti v názvech funkcí k indikaci přenosu vlastnictví, například pomocí „take“ v názvu funkce, čímž oznamují úplný přenos parametru, jako třeba u g_value_take_string(). Dávajte ale pozor na to, že různé knihovny používají různé konvence, jak je ukázáno níže:

          
Název funkce

          
Konvence 1 (standardní)

          
Konvence 2 (alternativní)
 

          
Konvence 3 (<cmd>gdbus-codegen</cmd>)

          
get

          
Bez přenosu

          
Libovolný přenos

          
Úplný přenos

          
dup

          
Úplný přenos

          
Nepoužito

          
Nepoužito

          
peek

          
Nepoužito

          
Nepoužito

          
Bez přenosu

          
set

          
Bez přenosu

          
Bez přenosu

          
Bez přenosu

          
take

          
Úplný přenos

          
Nepoužito

          
Nepoužito

          
steal

          
Úplný přenos

          
Úplný přenos

          
Úplný přenos

    
V ideálním případě mají všechny funkce <link xref="introspection">anotaci k introspekci</link> ve formě (transfer) pro všechny příslušné parametry a návratovou hodnotu. Pokud tomu tak není, uvádíme zde sadu pravidel, které můžete použít k určení toho, jestli je vlastnictví návratové hodnoty přenášeno:

    <steps>

      <item>
Jestliže má typ uvedenou anotaci (transfer) k introspekci, podívejte se na ni.
</item>

      <item>
V ostatních případech, když je typ konstantní (const), nedochází k přenosu.
</item>

      <item>
Jinak, jestliže dokumentace k funkci výslovně uvádí, že návratová hodnota musí být uvolněna, jedná se o úplný nebo kontejnerový přenos.
</item>

      <item>
V ostatních případech, když se funkce nazývá „dup“, „take“ nebo „steal“, dochází k úplnému nebo kontejnerovému přenosu.
</item>

      <item>
V ostatních případech, když se funkce nazývá „peek“, nedochází k přenosu.
</item>

      <item>
Jinak se musíte podívat do kódu funkce, abyste určili, jestli zamýšlí vlastnictví přenášet. Nahlaste také chybu vůči dokumentaci této funkce a v hlášení požádejte o přidání anotace k introspekci.
</item>

    </steps>

    
Když máme vlastnictví a přenos takhle jasně dány, je správný přístup k alokaci paměti v kterékoliv situaci otázkou mechanického rozhodnutí. V každém případě, funkce copy() musí odpovídat datovému typu, například g_strdup() pro řetězec nebo g_object_ref() pro GObject.

    
Když se nad přenosem vlastnictví zamyslíte, jsou malloc()/free() a počítání referencí to stejné: v prvním případě je naalokování nového kusu paměti z haldy přenosem vlastnictví, ve druhém případě nové zvýšení referencí. Viz <link xref="#reference-counting"/>.

    <section id="assignments">

      <title>Přiřazení</title>

            
Přiřazení z/do

            
Vlastněný cíl

            
Nevlastněný cíl

            
Vlastněný zdroj

              
Kopírování nebo přesun zdroje do cíle.

              owned_dest = copy (owned_src)

              owned_dest = owned_src; owned_src = NULL

              
Prosté přiřazení, předpokládá se, že nevlastněná proměnná se nepoužije po té, co je vlastněná uvolněna.

              unowned_dest = owned_src

            
Nevlastněný zdroj

              
Kopírování zdroje do cíle.

              owned_dest = copy (unowned_src)

              
Prosté přiřazení.

              unowned_dest = unowned_src

    </section>

    <section id="function-calls">

      <title>Volání funkcí</title>

            
Volání z/do

            
Přenos úplného parametru

            
Žádný přenos parametru

            
Vlastněný zdroj

              
Kopírování nebo přesun zdroje pro parametr.

              function_call (copy (owned_src))

              function_call (owned_src); owned_src = NULL

              
Prosté předání parametru.

              function_call (owned_src)

            
Nevlastněný zdroj

              
Kopírování zdroje pro parametr.

              function_call (copy (unowned_src))

              
Prosté předání parametru.

              function_call (unowned_src)

    </section>

    <section id="function-returns">

      <title>Návrat z funkcí</title>

            
Návrat z/do

            
Přenos úplné návratové hodnoty

            
Žádný přenos návratové hodnoty

            
Vlastněný zdroj

              
Prostý návrat proměnné.

              return owned_src

              
Neplatné. Zdroj potřebuje být uvolněn, takže vrácená hodnota by používala volnou paměť — chyba „použití po uvolnění“.

            
Nevlastněný zdroj

              
Kopírování zdroje pro návratovou hodnotu.

              return copy (unowned_src)

              
Prosté předání proměnné.

              return unowned_src

    </section>

  </section>

  <section id="documentation">

    <title>Dokumentace</title>

    
Zdokumentování přenosu vlastnictví u každého parametru funkce a návratové hodnoty a vlastnictví u každé proměnné je velmi důležité. Zatím co při psaní kódu to může být zcela jasné, o pár měsíců později to již tak jasné být nemusí. A už vůbec to nemusí být jasné uživatelům API. Proto by to mělo být vždy zdokumentováno.

    
Nejlepším způsobem zdokumentování přenosu vlastnictví je použít anotaci <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations#Memory_and_lifecycle_management">(transfer)</link>, která byla zavedena spolu s <link xref="introspection">introspekcí pro GObject</link>. Uveďte ji do dokumentačních komentářů k API pro všechny parametry a návratové typy funkcí. I když funkce není veřejným API, napište k ní dokumentační komentář a do něj zahrňte anotaci (transfer). Díky tomu budo moci nástroje pro introspekci číst potřebné anotace a správně prozkoumávat API.

    
Například:

    /**

 * g_value_take_string:

 * @value: (transfer none): an initialized #GValue

 * @str: (transfer full): string to set it to

 *

 * Function documentation goes here.

 */

/**

 * generate_string:

 * @template: (transfer none): a template to follow when generating the string

 *

 * Function documentation goes here.

 *

 * Returns: (transfer full): a newly generated string

 */

    
Vlastnictví proměnných lze dokumentovat pomocí vložených komentářů. Není to standardem a nečtou to všechny nástroje, ale může se to stát zvyklostí, pokud to bude jednotně dodržováno.

    GObject *some_owned_object = NULL;  /* owned */

GObject *some_unowned_object;  /* unowned */

    
Obdobně i dokumentování pro <link xref="#container-types"/> je čistě jen zvyklost. Součástí je také typ obsaženého prvku:

    GPtrArray/*<owned gchar*>*/ *some_unowned_string_array;  /* unowned */

GPtrArray/*<owned gchar*>*/ *some_owned_string_array = NULL;  /* owned */

GPtrArray/*<unowned GObject*>*/ *some_owned_object_array = NULL;  /* owned */

    
Pamatujte také, že vlastněné proměnné by měly být vždy inicializovány, takže jejich uvolnění je pak mnohem pohodlnější. Viz <link xref="#convenience-functions"/>.

    
Poznamenejme také, že některé typy, například základní typy v C, jako je řetězec, mohou mít v případě, že nejsou vlastněny, přidán modifikátor const, což má výhodu, že kompilátor zobrazí varování, když se pokusíte takovouto proměnnou přiřadit do vlastněné proměnné (která modifikátor const použít nesmí). V případě použití modifikátoru je možné vynechat komentář /* unowned */.

  </section>

  <section id="reference-counting">

    <title>Počítání odkazů</title>

    
Mimo tradičních typů ve stylu malloc()/free() máte v GLib k dispozici i různé typy počítání referencí — základním příkladem je <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html"> GObject</link>.

    
Koncept vlastnictví a jeho přenosu se používá stejně jako počítání referencí, které dělají alokované typy. Rozsah působnosti vlastní typy s počítáním referencí, pokud drží silnou referenci na instanci (například zavoláním <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-ref">g_object_ref()</link>. Instance se dá „zkopírovat“ opětovným zavoláním g_object_ref(). Vlastnictví se dá uvolnit pomocí <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref()</link> — i když se tím nemusí ve skutečnosti ukončit instance, uvolní se tím vlastnictví instance v aktuálním rozsahu působnosti.

    
Viz <link xref="#g-clear-object"/> ohledně vhodného způsobu zacházení s referencemi GObject.

    
V GLib existují další typy s počítáním referencí, jako je <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html"> GHashTable</link> (používá <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-ref"> g_hash_table_ref()</link> a <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-unref"> g_hash_table_unref()</link>), nebo <link href="https://developer.gnome.org/glib/stable/glib-GVariant.html"> GVariant</link> (<link href="https://developer.gnome.org/glib/stable/glib-GVariant.html#g-variant-ref"> g_variant_ref()</link>, <link href="https://developer.gnome.org/glib/stable/glib-GVariant.html#g-variant-unref"> g_variant_unref()</link>). Některé typy, jako GHashTable podporují jak počítání referencí, tak vynucenou finalizaci. Použití počítání referencí by se měla vždy dávat přednost, protože umožňuje instancím se jednoduše sdílet mezi více rozsahy působnosti (každá se drží svoji vlastní referenci), bez nutnosti alokovat více kopií instance. Šetří se tím paměť.

    <section id="floating-references">

      <title>Plovoucí reference</title>

      
Třídy odvozené z <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GInitiallyUnowned">GInitiallyUnowned</link> mají, oproti <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct">GObject</link>, počáteční referenci, která je plovoucí, což znamená, že ji nevlastní žádný kód. Jakmile je zavolána funkce <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-ref-sink">g_object_ref_sink()</link>, změní se plovoucí reference na silnou referenci a volající kód je pokládán za vlastníka objektu.

      
Plovoucí reference jsou vhodné pro použití v jazyce C v takových API, jako je GTK+, kde je zapotřebí vytvářet a organizovat do hierarchie velké množství objektů. V takových případech by zavolání g_object_unref() kvůli zachození všech silných referencí vedlo na velké množství kódu.

      <example>

        
Plovoucí reference umožňují následující kód zjednodušit:

        GtkWidget *new_widget;

new_widget = gtk_some_widget_new ();

gtk_container_add (some_container, new_widget);

g_object_unref (new_widget);

        
Místo toho můžete použít následující kód s GtkContainer předpokládajícím vlastnictví plovoucí reference:

gtk_container_add (some_container, gtk_some_widget_new ());

      </example>

      
Plovoucí reference používá jen pár API, zejména to je GtkWidget a všechny jeho podtřídy. Musíte si zjistit, která API je podporují a která API je umějí přijímat a používat je jen dohromady.

      
Všimněte si, že g_object_ref_sink() se chová stejně jako g_object_ref(), když je zavolána na neplovoucí referenci, díky čemuž se gtk_container_add() neliší v takovýchto případech od jiných funkcí.

      
Více informací o plovoucích referencích najdete v <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#floating-ref">příručce k GObject</link>.

    </section>

  </section>

  <section id="convenience-functions">

    <title>Vhodné funkce</title>

    
GLib poskytuje řadu funkcí usnadňujících správu paměti, hlavně pro GObject. Tři z nich jsou zde rozebrány, ale existují i další — podívejte se na ně do dokumentace k API GLib. Typicky dodržují podobné schéma pojmenování, jako zmíněné tři (používají sufix „_full“ nebo sloveso „clear“ v názvu).

    <section id="g-clear-object">

      <title>g_clear_object()</title>

      
<link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-clear-object">g_clear_object()</link> je verzí funkce <link href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-unref">g_object_unref()</link>, která zruší referenci na GObject a vymaže ukazatel nastavením na NULL.

      
Díky tomu je snažší napsat programový kód, který zaručuje, že ukazatel na GObject je vždy buď NULL nebo je vlastněn objektem GObject (ale nikdy neukazuje na GObject, který již není vlastněn).

      
Tím, že inicializujete všechny vlastněné ukazatel na GObject na NULL, je jejich uvolnění na konci oblasti působnosti možné pouhým zavoláním g_clear_object() bez jakýchkoliv kontrol, tak jak je to probráno v <link xref="#single-path-cleanup"/>:

      void

my_function (void)

{

  GObject *some_object = NULL;  /* owned */

  if (rand ())

    {

      some_object = create_new_object ();

      /* zde se s objektem něco udělá */

    }

  g_clear_object (&some_object);

}

    </section>

    <section id="g-list-free-full">

      <title>g_list_free_full()</title>

      
<link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html#g-list-free-full"> g_list_free_full()</link> uvolní všechny prvky v zřetězeném seznamu a všechna jejich data. To je mnohem pohodlnější, než procházet celý seznam, abyste uvolnily data jednotlivých prvků a následně zavolat <link href="https://developer.gnome.org/glib/stable/glib-Doubly-Linked-Lists.html#g-list-free"> g_list_free()</link>, aby se uvolnily vlastní prvky seznamu GList.

    </section>

    <section id="g-hash-table-new-full">

      <title>g_hash_table_new_full()</title>

      
<link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-new-full"> g_hash_table_new_full()</link> je novou verzí funkce <link href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#g-hash-table-new">g_hash_table_new()</link>, která umožňuje nastavit funkce pro likvidaci jednotlivých klíčů a hodnot hašovací tabulky při jejím odstranění. Tyto funkce jsou pak automaticky volány pro všechny klíče a hodnoty, když je hašovací tabulka likvidována nebo když je odstraněna položka pomocí g_hash_table_remove().

      
V podstatě to zjednodušuje správu paměti s klíči a hodnotami na otázku, jestli se nacházejí v hašovací tabulce. Vlastnictví prvku v kontejnerových typech je rozebráno v <link xref="#container-types"/>.

      
Obdobná funkce existuje pro GPtrArray: <link href="https://developer.gnome.org/glib/stable/glib-Pointer-Arrays.html#g-ptr-array-new-with-free-func">g_ptr_array_new_with_free_func()</link>.

    </section>

  </section>

  <section id="container-types">

    <title>Typy kontejnerů</title>

    
Při používání kontejnerových typů, jako je GPtrArray nebo GList, vzniká další úroveň vlastnictví: kromě vlastnictví instance kontejneru je také vlasněn nebo nevlastněn každý z prvků v kontejneru. Při vnoření kontejnerů pak musí být sledováno více úrovní vlastnictví. Vlastnictví vlastněných prvků náleží kontejneru a vlastnictví kontejneru náleží rozsahu působnosti kódu, ve kterém se nachází (což může být i další kontejner).

    
Klíčovým principem pro zjednodušení toho celého je, zajistit, aby všechny prvky v kontejneru měly stejného vlastníka: buď jsou všechny vlastněny nebo nejsou. To se děje automaticky, když jsou použity normální <link xref="#convenience-functions"/> pro typy, jako jsou GPtrArray a GHashTable.

    
Když kontejner prvky vlastní, pak je jejich přidání do kontejneru v podstatě přenosem vlastnictví. Například, pro pole řetězců, pokud jsou prvky vlastněny, je definice g_ptr_array_add() ve skutečnosti:

    /**

 * g_ptr_array_add:

 * @array: a #GPtrArray

 * @str: (transfer full): string to add

 */

void

g_ptr_array_add (GPtrArray *array,

                 gchar     *str);

    
Takže například konstantní (nevlastněný) řetězec musí být přidán do pole pomocí g_ptr_array_add (array, g_strdup ("constant string")).

    
Zatímco, když prvek není vlastněn, je definice ve skutečnosti:

    /**

 * g_ptr_array_add:

 * @array: a #GPtrArray

 * @str: (transfer none): string to add

 */

void

g_ptr_array_add (GPtrArray   *array,

                 const gchar *str);

    
Zde může být konstantní řetězec přidán bez jeho kopírování: g_ptr_array_add (array, "constant string").

    
Příklady komentářů, které se přidávají ke definicím proměnných kvůli anotacím k typu a vlastnictví, viz <link xref="#documentation"/>.

  </section>

  <section id="single-path-cleanup">

    <title>Jednocestné čištění</title>

    
Vhodným návrhovým vzorem pro složitější funkce je mít v jediné cestě průchodu vyčištění (uvolnění) alokací a návrat k volajícímu. Tím se nesmírně zjednoduší sledování alokací, protože není nadále nutné přemýšlet na tím, které alokace již byly v jednotlivých cestách průchodu uvolněny – všechny cesty průchodu končí ve stejném bodě, za kterým teprve provádíte uvolnění. Výhody tohoto přístupu se rychle projeví u rozsáhlých funkcí s více vlastněnými lokálními proměnnými. Pro menší funkce tento návrhový vzor smysluplný být nemusí.

    
Tento přístup má dva předpoklady:

    <list type="numbered">

      <item>
Návrat z funkce je v jediném bodě a pro dosažení tohoto bodu z jiných míst se používá goto.
</item>

      <item>
Všechny vlastněné proměnné jsou při inicializaci nebo při přenosu vlastnictví pryč nastaveny na NULL.
</item>

    </list>

    
Příklad níže je pro malou funkci (kvůli stručnosti), ale měl by ukázat principy i pro aplikaci, které chce tento vzor použít pro rozsáhlé funkce:

    <listing>

      <title>Příklad jednocestného číštění</title>

      <desc>Příklad implementace jednocestného čištění pro jednoduchou funkci</desc>

      GObject *

some_function (GError **error)

{

  gchar *some_str = NULL;  /* owned */

  GObject *temp_object = NULL;  /* owned */

  const gchar *temp_str;

  GObject *my_object = NULL;  /* owned */

  GError *child_error = NULL;  /* owned */

  temp_object = generate_object ();

  temp_str = "example string";

  if (rand ())

    {

      some_str = g_strconcat (temp_str, temp_str, NULL);

    }

  else

    {

      some_operation_which_might_fail (&child_error);

      if (child_error != NULL)

        {

          goto done;

        }

      my_object = generate_wrapped_object (temp_object);

    }

done:

  /* Zde je proměnná @some_str buď NULL nebo řetězec, který má být uvolněn, takže

   * může být předána do g_free() nepodmíněně.

   *

   * Obdobně, @temp_object je buď NULL nebo objekt, na nějž má být zrušena reference,

   * takže může být předána do g_clear_object() nepodmíněně. */

  g_free (some_str);

  g_clear_object (&temp_object);

  /* Tento vzor může být použit také zajištění, že funcke vždy vrátí

   * buď nějakou chybu nebo návratovou hodnotu (ale nikdy obojí). */

  if (child_error != NULL)

    {

      g_propagate_error (error, child_error);

      g_clear_object (&my_object);

    }

  return my_object;

}

    </listing>

  </section>

  <section id="verification">

    <title>Ověření</title>

    
Úniky paměti mohou být kontrolovány dvěma způsoby: statickou analýzou a kontrolou úniků za běhu.

    
Statická analýza pomocí nástrojů, jako je <link xref="tooling#coverity">Coverity</link>, <link xref="tooling#clang-static-analyzer">statický analyzátor Clang</link> nebo <link xref="tooling#tartan">Tartan</link>, může zachytit některé úniky, ale potřebuje k tomu znalost přenosu vlastnictví u všech funkcí volaných v kódu. Statické analyzátory zaměřené na určitou oblast, jako Tartan (který zná alokaci paměti a přenosy knihovny GLib) si mohou vést lépe. Ale zrovna Tartan je poněkud mladý projekt a stále postrádá některé věci (nízkou četnost pravdivých hlášení). Ze zmíněných důvodů je doporučováno projít kód statickým analyzátorem, ale jako hlavní nástroj pro zjišťování úniků by měla být kontrola za běhu.

    
Kontrola úniků za běhu se provádí pomocí <link xref="tooling#valgrind">Valgrind</link>, konkrétně nástrojem <link xref="tooling#memcheck">memcheck</link>. Kterýkoliv únik, který je detekován jako „trvalá ztráta paměti“, by měl být opraven. Řada úniků, které jsou „potenciální ztráta paměti“ ve skutečnosti žádné uniky nejsou a měly by být přidány do souboru pro potlačení.

    
Pokud kompilujete pomocí nejnovějších verzí Clang nebo GCC, můžete místo toho zapnout <link xref="tooling#address-sanitizer">sanitizér adres</link>, který bude za běhu detekovat problémy s úniky paměti a přetečením, ale bez složitosti běhu nástrojů Valgrind ve správném prostředí. Upozorňujeme ale, že se jedná stále o nevyzrálý nástroj, takže v některých případech může selhat.

    
Další informace ohledně použití aplikace Valgrind viz <link xref="tooling#valgrind"/>.

  </section>

</page>