€•B      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ$/translations/zh_CN/core-api/cleanup”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/zh_TW/core-api/cleanup”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/it_IT/core-api/cleanup”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/ja_JP/core-api/cleanup”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/ko_KR/core-api/cleanup”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/sp_SP/core-api/cleanup”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒ>/var/lib/git/docbuild/linux/Documentation/core-api/cleanup.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒScope-based Cleanup Helpers”h]”hŒScope-based Cleanup Helpers”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hXx  The "goto error" pattern is notorious for introducing subtle resource
leaks. It is tedious and error prone to add new resource acquisition
constraints into code paths that already have several unwind
conditions. The "cleanup" helpers enable the compiler to help with
this tedium and can aid in maintaining LIFO (last in first out)
unwind ordering to avoid unintentional leaks.”h]”hX€  The â€œgoto errorâ€ pattern is notorious for introducing subtle resource
leaks. It is tedious and error prone to add new resource acquisition
constraints into code paths that already have several unwind
conditions. The â€œcleanupâ€ helpers enable the compiler to help with
this tedium and can aid in maintaining LIFO (last in first out)
unwind ordering to avoid unintentional leaks.”…””}”(hhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h Khh¶hžhubhÊ)”}”(hX!  As drivers make up the majority of the kernel code base, here is an
example of using these helpers to clean up PCI drivers. The target of
the cleanups are occasions where a goto is used to unwind a device
reference (pci_dev_put()), or unlock the device (pci_dev_unlock())
before returning.”h]”hX!  As drivers make up the majority of the kernel code base, here is an
example of using these helpers to clean up PCI drivers. The target of
the cleanups are occasions where a goto is used to unwind a device
reference (pci_dev_put()), or unlock the device (pci_dev_unlock())
before returning.”…””}”(hhÚhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h Khh¶hžhubhÊ)”}”(hŒ|The DEFINE_FREE() macro can arrange for PCI device references to be
dropped when the associated variable goes out of scope::”h]”hŒ{The DEFINE_FREE() macro can arrange for PCI device references to be
dropped when the associated variable goes out of scope:”…””}”(hhéhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h Khh¶hžhubhŒliteral_block”“”)”}”(hŒ DEFINE_FREE(pci_dev_put, struct pci_dev *, if (_T) pci_dev_put(_T))
...
struct pci_dev *dev __free(pci_dev_put) =
        pci_get_slot(parent, PCI_DEVFN(0, 0));”h]”hŒ DEFINE_FREE(pci_dev_put, struct pci_dev *, if (_T) pci_dev_put(_T))
...
struct pci_dev *dev __free(pci_dev_put) =
        pci_get_slot(parent, PCI_DEVFN(0, 0));”…””}”hhúsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1høhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h Khh¶hžhubhÊ)”}”(hŒüThe above will automatically call pci_dev_put() if **dev** is non-NULL
when **dev** goes out of scope (automatic variable scope). If a function
wants to invoke pci_dev_put() on error, but return **dev** (i.e. without
freeing it) on success, it can do::”h]”(hŒ3The above will automatically call pci_dev_put() if ”…””}”(hj	  hžhhŸNh NubhŒstrong”“”)”}”(hŒ**dev**”h]”hŒdev”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj	  ubhŒ is non-NULL
when ”…””}”(hj	  hžhhŸNh Nubj  )”}”(hŒ**dev**”h]”hŒdev”…””}”(hj%  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj	  ubhŒp goes out of scope (automatic variable scope). If a function
wants to invoke pci_dev_put() on error, but return ”…””}”(hj	  hžhhŸNh Nubj  )”}”(hŒ**dev**”h]”hŒdev”…””}”(hj7  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj	  ubhŒ1 (i.e. without
freeing it) on success, it can do:”…””}”(hj	  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h Khh¶hžhubhù)”}”(hŒreturn no_free_ptr(dev);”h]”hŒreturn no_free_ptr(dev);”…””}”hjP  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1høhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K"hh¶hžhubhÊ)”}”(hŒ...or::”h]”hŒ...or:”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K$hh¶hžhubhù)”}”(hŒreturn_ptr(dev);”h]”hŒreturn_ptr(dev);”…””}”hjn  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1høhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K&hh¶hžhubhÊ)”}”(hŒyThe DEFINE_GUARD() macro can arrange for the PCI device lock to be
dropped when the scope where guard() is invoked ends::”h]”hŒxThe DEFINE_GUARD() macro can arrange for the PCI device lock to be
dropped when the scope where guard() is invoked ends:”…””}”(hj}  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K(hh¶hžhubhù)”}”(hŒfDEFINE_GUARD(pci_dev, struct pci_dev *, pci_dev_lock(_T), pci_dev_unlock(_T))
...
guard(pci_dev)(dev);”h]”hŒfDEFINE_GUARD(pci_dev, struct pci_dev *, pci_dev_lock(_T), pci_dev_unlock(_T))
...
guard(pci_dev)(dev);”…””}”hjŒ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1høhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K+hh¶hžhubhÊ)”}”(hŒ‰The lifetime of the lock obtained by the guard() helper follows the
scope of automatic variable declaration. Take the following example::”h]”hŒˆThe lifetime of the lock obtained by the guard() helper follows the
scope of automatic variable declaration. Take the following example:”…””}”(hj›  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K/hh¶hžhubhù)”}”(hŒÄfunc(...)
{
        if (...) {
                ...
                guard(pci_dev)(dev); // pci_dev_lock() invoked here
                ...
        } // <- implied pci_dev_unlock() triggered here
}”h]”hŒÄfunc(...)
{
        if (...) {
                ...
                guard(pci_dev)(dev); // pci_dev_lock() invoked here
                ...
        } // <- implied pci_dev_unlock() triggered here
}”…””}”hjª  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1høhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K2hh¶hžhubhÊ)”}”(hŒ^Observe the lock is held for the remainder of the "if ()" block not
the remainder of "func()".”h]”hŒfObserve the lock is held for the remainder of the â€œif ()â€ block not
the remainder of â€œfunc()â€.”…””}”(hj¹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K;hh¶hžhubhÊ)”}”(hŒ¤Now, when a function uses both __free() and guard(), or multiple
instances of __free(), the LIFO order of variable definition order
matters. GCC documentation says:”h]”hŒ¤Now, when a function uses both __free() and guard(), or multiple
instances of __free(), the LIFO order of variable definition order
matters. GCC documentation says:”…””}”(hjÈ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K>hh¶hžhubhÊ)”}”(hŒÄ"When multiple variables in the same scope have cleanup attributes,
at exit from the scope their associated cleanup functions are run in
reverse order of definition (last defined, first cleanup)."”h]”hŒÈâ€œWhen multiple variables in the same scope have cleanup attributes,
at exit from the scope their associated cleanup functions are run in
reverse order of definition (last defined, first cleanup).â€”…””}”(hj×  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h KBhh¶hžhubhÊ)”}”(hŒ¿When the unwind order matters it requires that variables be defined
mid-function scope rather than at the top of the file.  Take the
following example and notice the bug highlighted by "!!"::”h]”hŒÂWhen the unwind order matters it requires that variables be defined
mid-function scope rather than at the top of the file.  Take the
following example and notice the bug highlighted by â€œ!!â€:”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h KFhh¶hžhubhù)”}”(hX»  LIST_HEAD(list);
DEFINE_MUTEX(lock);

struct object {
        struct list_head node;
};

static struct object *alloc_add(void)
{
        struct object *obj;

        lockdep_assert_held(&lock);
        obj = kzalloc(sizeof(*obj), GFP_KERNEL);
        if (obj) {
                LIST_HEAD_INIT(&obj->node);
                list_add(obj->node, &list):
        }
        return obj;
}

static void remove_free(struct object *obj)
{
        lockdep_assert_held(&lock);
        list_del(&obj->node);
        kfree(obj);
}

DEFINE_FREE(remove_free, struct object *, if (_T) remove_free(_T))
static int init(void)
{
        struct object *obj __free(remove_free) = NULL;
        int err;

        guard(mutex)(&lock);
        obj = alloc_add();

        if (!obj)
                return -ENOMEM;

        err = other_init(obj);
        if (err)
                return err; // remove_free() called without the lock!!

        no_free_ptr(obj);
        return 0;
}”h]”hX»  LIST_HEAD(list);
DEFINE_MUTEX(lock);

struct object {
        struct list_head node;
};

static struct object *alloc_add(void)
{
        struct object *obj;

        lockdep_assert_held(&lock);
        obj = kzalloc(sizeof(*obj), GFP_KERNEL);
        if (obj) {
                LIST_HEAD_INIT(&obj->node);
                list_add(obj->node, &list):
        }
        return obj;
}

static void remove_free(struct object *obj)
{
        lockdep_assert_held(&lock);
        list_del(&obj->node);
        kfree(obj);
}

DEFINE_FREE(remove_free, struct object *, if (_T) remove_free(_T))
static int init(void)
{
        struct object *obj __free(remove_free) = NULL;
        int err;

        guard(mutex)(&lock);
        obj = alloc_add();

        if (!obj)
                return -ENOMEM;

        err = other_init(obj);
        if (err)
                return err; // remove_free() called without the lock!!

        no_free_ptr(obj);
        return 0;
}”…””}”hjõ  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1høhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h KJhh¶hžhubhÊ)”}”(hŒdThat bug is fixed by changing init() to call guard() and define +
initialize **obj** in this order::”h]”(hŒMThat bug is fixed by changing init() to call guard() and define +
initialize ”…””}”(hj  hžhhŸNh Nubj  )”}”(hŒ**obj**”h]”hŒobj”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj  ubhŒ in this order:”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h Kyhh¶hžhubhù)”}”(hŒJguard(mutex)(&lock);
struct object *obj __free(remove_free) = alloc_add();”h]”hŒJguard(mutex)(&lock);
struct object *obj __free(remove_free) = alloc_add();”…””}”hj%  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1høhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K|hh¶hžhubhÊ)”}”(hX+  Given that the "__free(...) = NULL" pattern for variables defined at
the top of the function poses this potential interdependency problem
the recommendation is to always define and assign variables in one
statement and not group variable definitions at the top of the
function when __free() is used.”h]”hX/  Given that the â€œ__free(...) = NULLâ€ pattern for variables defined at
the top of the function poses this potential interdependency problem
the recommendation is to always define and assign variables in one
statement and not group variable definitions at the top of the
function when __free() is used.”…””}”(hj4  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h Khh¶hžhubhÊ)”}”(hX[  Lastly, given that the benefit of cleanup helpers is removal of
"goto", and that the "goto" statement can jump between scopes, the
expectation is that usage of "goto" and cleanup helpers is never
mixed in the same function. I.e. for a given routine, convert all
resources that need a "goto" cleanup to scope-based cleanup, or
convert none of them.”h]”hXk  Lastly, given that the benefit of cleanup helpers is removal of
â€œgotoâ€, and that the â€œgotoâ€ statement can jump between scopes, the
expectation is that usage of â€œgotoâ€ and cleanup helpers is never
mixed in the same function. I.e. for a given routine, convert all
resources that need a â€œgotoâ€ cleanup to scope-based cleanup, or
convert none of them.”…””}”(hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h K…hh¶hžhubeh}”(h]”Œscope-based-cleanup-helpers”ah ]”h"]”Œscope-based cleanup helpers”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j}  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”jW  jT  sŒ	nametypes”}”jW  ‰sh}”jT  h¶sŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.