€•ÏF      Œ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ŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ$/translations/pt_BR/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j  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1j  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j9  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jK  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²hubj  )”}”(hŒreturn no_free_ptr(dev);”h]”hŒreturn no_free_ptr(dev);”…””}”hjd  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1j  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js  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²hubj  )”}”(hŒreturn_ptr(dev);”h]”hŒreturn_ptr(dev);”…””}”hj‚  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1j  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²hubj  )”}”(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Æuh1j  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´K1hhÊh²hubj  )”}”(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Æuh1j  h³ŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h´K4h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ŒsThe ACQUIRE() macro can be used in all places that guard() can be
used and additionally support conditional locks::”h]”hŒrThe ACQUIRE() macro can be used in all places that guard() can be
used and additionally support conditional locks:”…””}”(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²hubj  )”}”(hŒ¬DEFINE_GUARD_COND(pci_dev, _try, pci_dev_trylock(_T))
...
ACQUIRE(pci_dev_try, lock)(dev);
rc = ACQUIRE_ERR(pci_dev_try, &lock);
if (rc)
        return rc;
// @lock is held”h]”hŒ¬DEFINE_GUARD_COND(pci_dev, _try, pci_dev_trylock(_T))
...
ACQUIRE(pci_dev_try, lock)(dev);
rc = ACQUIRE_ERR(pci_dev_try, &lock);
if (rc)
        return rc;
// @lock is held”…””}”hjë  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1j  h³ŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h´KChhÊh²hubhÞ)”}”(hŒ®Now, when a function uses both __free() and guard()/ACQUIRE(), 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()/ACQUIRE(), 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´KKh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´KOh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´KShhÊh²hubj  )”}”(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Æuh1j  h³ŒW/var/lib/git/docbuild/linux/Documentation/core-api/cleanup:7: ./include/linux/cleanup.h”h´KWh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j6  h²hh³Nh´Nubj&  )”}”(hŒ**obj**”h]”hŒobj”…””}”(hj>  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j%  hj6  ubhŒ in this order:”…””}”(hj6  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²hubj  )”}”(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jW  sbah}”(h]”h ]”h"]”h$]”h&]”hÅhÆuh1j  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jf  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ju  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”}”j‰  j†  sŒ	nametypes”}”j‰  ‰sh}”j†  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.