Resource acquisition is initialization: Difference between revisions

Revision as of 07:32, 8 January 2020

Latest revision as of 09:32, 1 July 2025

(48 intermediate revisions by 34 users not shown)

Line 1:

{{short description|Approach to managing resources by tying them to object lifetime}}

{{more citations needed|date=December 2012}}

'''Resource acquisition is initialization''' ('''RAII''')<ref name="faq">{{cite web

Line 6 ⟶ 7:

| last=Stroustrup

| date=2017-09-30

| accessdateaccess-date=2019-03-09}}</ref> is a [[programming idiom]]<ref>{{cite book |last1=Sutter |first1=Herb |author-link1=Herb Sutter |last2=Alexandrescu |first2=Andrei |author-link2=Andrei Alexandrescu |year=2005 |chapter= |title=C++ Coding Standards |url=https://archive.org/details/isbn_0321113586 |url-access=limited |series=C++ In-Depth Series |publisher=Addison-Wesley |publication-date= |page=[https://archive.org/details/isbn_0321113586/page/n54 24] |isbn=978-0-321-11358-0 }}</ref> used in several [[Object-oriented programming language|object-oriented]], languages[[Statically-typed programming language|statically typed]] programming languages to describe a particular language behavior. In RAII, holding a resource is a [[class invariant]], and is tied to [[object lifetime]]:. [[Resource allocation (computer)|resourceResource allocation]] (or acquisition) is done during object creation (specifically initialization), by the [[Constructor (object-oriented programming)|constructor]], while resource deallocation (release) is done during object destruction (specifically finalization), by the [[Destructor (computer programming)|destructor]]. In other words, resource acquisition must succeed for initialization to succeed. Thus, the resource is guaranteed to be held between when initialization finishes and finalization starts (holding the resources is a class invariant), and to be held only when the object is alive. Thus, if there are no object leaks, there are no [[resource leak]]s.

RAII is associated most prominently with [[C++]], where it originated, but also [[DAda (programming language)|DAda]],<ref>{{cite [[Adaweb (programming|title=Gem #70: The Scope Locks Idiom language)|Ada]],url=https://www.adacore.com/gems/gem-70 |website=AdaCore |access-date=21 May 2021 |language=en}}</ref> [[Vala (programming language)|Vala]],<ref>{{cite web |author1=The Valadate Project |title=Destruction |url=https://naaando.gitbooks.io/the-vala-tutorial/content/en/4-object-oriented-programming/destruction.html |website=The Vala Tutorial version 0.30 |access-date=21 May 2021}}</ref> and [[Rust (programming language)|Rust]].<ref>{{Cite web|title=RAII - Rust By Example|url=https://doc.rust-lang.org/rust-by-example/scope/raii.html|access-date=2020-11-22|website=doc.rust-lang.org}}</ref> The technique was developed for [[Exception safety|exception-safe]] [[resource management (computing)|resource management]] in C++{{sfn|Stroustrup|1994|loc=16.5 Resource Management, pp. 388–89}} during 1984–891984–1989, primarily by [[Bjarne Stroustrup]] and [[Andrew Koenig (programmer)|Andrew Koenig]],{{sfn|Stroustrup|1994|loc=16.1 Exception Handling: Introduction, pp. 383–84}} and the term itself was coined by Stroustrup.{{sfn|Stroustrup|1994|p=389|ps=. I called this technique "resource acquisition is initialization."}} RAII is generally pronounced as an [[initialism]], sometimes pronounced as "R, A, double I".<ref>{{cite web

| url=https://stackoverflow.com/a/99986

| title=How do you pronounce RAII?

| author=Michael Burr

| date=2008-09-19

| publisher=[[Stack Overflow]]

| accessdate=2019-03-09}}</ref>

Other names for this idiom include ''Constructor Acquires, Destructor Releases'' (CADRe)<ref>{{Cite web

Line 23 ⟶ 18:

| work=ISO C++ Standard - Future Proposals

| publisher=[[Google Groups]]

| accessdateaccess-date=2019-03-09}}</ref> and one particular style of use is called ''Scope-based Resource Management'' (SBRM).<ref>{{Cite web

| url=http://allenchou.net/2014/10/scope-based-resource-management-raii/

| title=Scope-Based Resource Management (RAII)

Line 29 ⟶ 24:

| last=Chou

| date=2014-10-01

| accessdateaccess-date=2019-03-09}}</ref> This latter term is for the special case of [[automatic variable]]s. RAII ties resources to object ''lifetime,'' which may not coincide with entry and exit of a scope. (Notably variables allocated on the [[Heap (programming)|free store]] have lifetimes unrelated to any given scope.) However, using RAII for automatic variables (SBRM) is the most common use case.

==C++11 example==

The following [[C++11]] example demonstrates usage of RAII for file access and [[mutex]] locking:

<sourcesyntaxhighlight lang=cpp>

#include <fstream>

#include <iostream>

Line 57 ⟶ 52:

// |file| will be closed first when leaving scope (regardless of exception)

// |mutex| will be unlocked second (from |lock| destructor) when leaving scope

// (regardless of exception).

}

</syntaxhighlight>

</source>

This code is exception-safe because C++ guarantees that all stack objects with automatic storage duration (local variables) are destroyed at the end of the enclosing scope, knownin asthe [[stackreverse unwinding]]. The destructorsorder of both the ''lock'' and ''file'' objects are therefore guaranteed to be called when returning from the function, whether an exception has been thrown ortheir notconstruction.<ref>{{cite web

| url=http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/n4659.pdf

| title=Working Draft, Standard for Programming Language C++

| date=20082017-0903-1921

| author=MichaelRichard BurrSmith

| page=151, section §9.6

| access-date=2023-09-07

}}</ref>

The destructors of both the ''lock'' and ''file'' objects are therefore guaranteed to be called when returning from the function, whether an exception has been thrown or not.<ref>{{cite web

| url=https://isocpp.org/wiki/faq/exceptions#dtors-shouldnt-throw

| title=How can I handle a destructor that fails?

| publisher=Standard C++ Foundation

| accessdateaccess-date=2019-03-09}}</ref>

Local variables allow easy management of multiple resources within a single function: they are destroyed in the reverse order of their construction, and an object is destroyed only if fully constructed&mdash;that is, if no exception propagates from its constructor.<ref>{{cite web

| url=http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/n4659.pdf

| title=Working Draft, Standard for ProgrammingLanguageProgramming Language C++

| date=2017-03-21

| author=Richard Smith

| accessdateaccess-date=2019-03-09}}</ref>

Using RAII greatly simplifies resource management, reduces overall code size and helps ensure program correctness. RAII is therefore highly recommended in C++, and most of the C++by industry-standard library follows the idiom.guidelines,<ref>{{cite web

| url=https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines

| title=C++ Core Guidelines

| date=2020-08-03

| last1=Stroustrup

| first1=Bjarne

| author-link1=Bjarne Stroustrup

| last2=Sutter

| first2=Herb

| author-link2=Herb Sutter

| accessdateaccess-date=20192020-0308-0915}}</ref>

and most of the C++ standard library follows the idiom.<ref>{{cite web

| url=https://isocpp.org/wiki/faq/exceptions#too-many-trycatch-blocks

| title=I have too many try blocks; what can I do about it?

| publisher=Standard C++ Foundation

| accessdateaccess-date=2019-03-09}}</ref>

==Benefits==

The advantages of RAII as a resource management technique are that it provides encapsulation, [[exception safety]] (for stack resources), and locality (it allows acquisition and release logic to be written next to each other).

Encapsulation is provided because resource management logic is defined once in the class, not at each call site. Exception safety is provided for stack resources (resources that are released in the same scope as they are acquired) by tying the resource to the lifetime of a stack variable (a local variable declared in a given scope): if an [[Exception handling|exception]] is thrown, and proper exception handling is in place, the only code that will be executed when exiting the current [[Scope (computer science)|scope]] are the destructors of objects declared in that scope. Finally, locality of definition is provided by writing the constructor and destructor definitions next to each other in the class definition.

Line 89 ⟶ 103:

Comparing RAII with the <code>finally</code> construct used in Java, Stroustrup wrote that “In realistic systems, there are far more resource acquisitions than kinds of resources, so the 'resource acquisition is initialization' technique leads to less code than use of a 'finally' construct.”<ref name="faq"/>

As a class invariant, RAII provides guarantees that an object instance that is supposed to have acquired a resource has in fact done so. This eliminates the need for additional "setup" methods to get a newly-created object into a usable state (all such work is performed in the constructor; similarly, "shutdown" tasks to release resources occur in the object's destructor), and the need to test instances to verify that they have been properly set up before every use.<ref>[https://en.cppreference.com/w/cpp/language/raii.html RAII at cppreference.com]</ref>

==Typical uses==

The RAII design is often used for controlling [[mutex]] locks in [[thread (computing)#Multithreading|multi-threaded]] applications. In that use, the object releases the lock when destroyed. Without RAII in this scenario the potential for [[Deadlock (computer science)|deadlock]] would be high and the logic to lock the mutex would be far from the logic to unlock it. With RAII, the code that locks the mutex essentially includes the logic that the lock will be released when execution leaves the scope of the RAII object.

Another typical example is interacting with files: We could have an object that represents a file that is open for writing, wherein the file is opened in the constructor and closed when execution leaves the object's scope. In both cases, RAII ensures only that the resource in question is released appropriately; care must still be taken to maintain exception safety. If the code modifying the data structure or file is not exception-safe, the mutex could be unlocked or the file closed with the data structure or file corrupted.

Ownership of dynamically allocated objects (memory allocated with <ttcode>new</ttcode> in C++) can also be controlled with RAII, such that the object is released when the RAII (stack-based) object is destroyed. For this purpose, the [[C++11]] standard library defines the [[smart pointer]] classes <code>[[Smart pointer#unique_ptr|std::unique_ptr]]</code> for single-owned objects and <code>[[Smart_pointer#shared_ptr_and_weak_ptr|std::shared_ptr]]</code> for objects with shared ownership. Similar classes are also available through <code>[[auto ptr|std::auto_ptr]]</code> in C++98, and <code>boost::shared_ptr</code> in the [[Boost (C++ libraries)|Boost libraries]].

Also, messages can be sent to network resources using RAII. In this case, the RAII object would send a message to a [[Network socket|socket]] at the end of the constructor, when its initialization is completed. It would also send a message at the beginning of the destructor, when the object is about to be destroyed. Such a construct might be used in a client object to establish a connection with a server running in another process.

== Clang and GCC "cleanup" extension for C ==

Both [[Clang]] and [[GNU Compiler Collection]] implement a non-standard extension to the [[C (programming language)|C]] language to support RAII: the "cleanup" variable attribute.<ref>{{Cite web

== Compiler "cleanup" extensions ==

Both [[Clang]] and the [[GNU Compiler Collection]] implement a non-standard extension to the [[C (programming language)|C]] language to support RAII: the "cleanup" variable attribute.<ref>{{Cite web

| url=https://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html

| title=Specifying Attributes of Variables

| work=Using the GNU Compiler Collection (GCC)

| publisher=[[GNU Project]]

| accessdateaccess-date=2019-03-09}}</ref> The following [[macro (computer science)|macro]] annotates a variable with a given destructor function that it will call when the variable goes out of scope:

<source lang=c>

static inline void fclosep(FILE **fp) { if (*fp) fclose(*fp); }

#define _cleanup_fclose_ __attribute__((cleanup(fclosep)))

</source>

<syntaxhighlight lang=c>

This macro can then be used as follows:

<source lang=c>

void example_usage() {

_cleanup_fclose___attribute__((cleanup(fclosep))) FILE *logfile = fopen("logfile.txt", "w+");

fputs("hello logfile!", logfile);

}

</syntaxhighlight>

</source>

In this example, the compiler arranges for the ''fclosep'' function to be called on ''logfile'' before ''example_usage'' returns.

Line 123 ⟶ 135:

RAII only works for resources acquired and released (directly or indirectly) by stack-allocated objects,

where there ''is'' a well-defined static object lifetime.

[[Heap (programming)|Heap]]-allocated objects which themselves acquire and release resources are common in many languages, including C++. RAII depends on heap-based objects to be implicitly or explicitly deleted along all possible execution paths, in order to trigger its resource-releasing destructor (or equivalent).<ref>{{cite news

| title=Exceptional Situations and Program Reliability

| first1=Westley

Line 133 ⟶ 145:

| issue=2

| year=2008

| url=https://web.eecs.umich.edu/~weimerw/p/weimer-toplas2008.pdf}}</ref>{{rp|8:27}} This can be achieved by using [[smart pointer]]s to manage all heap objects, with weak- pointers for cyclically referenced objects.

In C++, stack unwinding is only guaranteed to occur if the exception is caught somewhere. This is because "If no matching handler is found in a program, the function terminate() is called; whether or not the stack is unwound before this call to terminate() is implementation-defined (15.5.1)." (C++03 standard, §15.3/9).<ref>{{cite web

Line 141 ⟶ 153:

| date=2011-04-05

| publisher=Stack Overflow

| accessdateaccess-date=2019-03-09}}</ref> This behavior is usually acceptable, since the operating system releases remaining resources like memory, files, sockets, etc. at program termination.{{citation needed|date=January 2020}}

At the 2018 Gamelab conference, [[Jonathan Blow]] claimed that use of RAII can cause [[Fragmentation (computing)|memory fragmentation]] which in turn can cause [[CPU cache#Cache miss|cache misses]] and a 100 times or worse hit on [[Computer performance|performance]].<ref>{{YouTube |id=uZgbKrDEzAs |t=614 |title=Gamelab2018 - Jon Blow's Design decisions on creating Jai a new language for game programmers}}</ref>

== Reference counting ==

Line 149 ⟶ 163:

| work=Extending and Embedding the Python Interpreter

| publisher=[[Python Software Foundation]]

| accessdateaccess-date=2019-03-09}}</ref> and [[PHP]]<ref>{{Cite web

| url=https://stackoverflow.com/a/4938780

| title=Does PHP support the RAII pattern? How?

| author=hobbs

| date=2011-02-08

| accessdateaccess-date=2019-03-09}}</ref> manage object lifetime by [[reference counting]], which makes it possible to use RAII. Objects that are no longer referenced are immediately destroyed or finalized and released, so a [[Destructor (computer programming)|destructor]] or [[finalizer]] can release the resource at that time. However, it is not always idiomatic in such languages, and is specifically discouraged in Python (in favor of [[context manager]]s and ''finalizers'' from the ''weakref'' package).{{fact|date=June 2022}}

However, object lifetimes are not necessarily bound to any scope, and objects may be destroyed non-deterministically or not at all. This makes it possible to accidentally leak resources that should have been released at the end of some scope. Objects stored in a [[static variable]] (notably a [[global variable]]) may not be finalized when the program terminates, so their resources are not released; CPython makes no guarantee of finalizing such objects, for instance. Further, objects with [[circular referencesreference]]s will not be collected by a simple reference counter, and will live indeterminately long; even if collected (by more sophisticated garbage collection), destruction time and destruction order will be non-deterministic. In CPython there is a cycle detector which detects cycles and finalizes the objects in the cycle, though prior to CPython 3.4, cycles are not collected if any object in the cycle has a finalizer.<ref>{{cite web

| url=https://docs.python.org/3/library/gc.html

| title=gc — Garbage Collector interface

| work=The Python Standard Library

| publisher=Python Software Foundation

| accessdateaccess-date=2019-03-09}}</ref>

== References ==

Line 174 ⟶ 188:

| last = Stroustrup

| first = Bjarne

| authorlinkauthor-link = Bjarne Stroustrup

| year = 1994

| publisher = Addison-Wesley

Line 184 ⟶ 198:

{{wikibooks|More C++ Idioms|Resource Acquisition Is Initialization}}

* Sample Chapter: "[https://www.informit.com/articles/article.aspx?p=30642&seqNum=8 Gotcha #67: Failure to Employ Resource Acquisition Is Initialization]" by Stephen C. Dewhurst

* Interview: "[https://www.artima.com/intv/modern3.html A Conversation with Bjarne Stroustrup]" by Bill Venners

* Article: "[https://www.artima.com/cppsource/bigtwo3.html The Law of The Big Two]" by Bjorn Karlsson and Matthew Wilson

* Article: "[https://web.archive.org/web/20090815095635/http://gethelp.devx.com/techtips/cpp_pro/10min/2001/november/10min1101.asp Implementing the 'Resource Acquisition is Initialization' Idiom]" by Danny Kalev

* Article: "[https://www.codeproject.com/Articles/10141/RAII-Dynamic-Objects-and-Factories-in-C RAII, Dynamic Objects, and Factories in C++]" by Roland Pibinger

* RAII in Delphi: "[http://blog.barrkel.com/2010/01/one-liner-raii-in-delphi.html One-liner RAII in Delphi]" by Barry Kelly

* Guide: [https://www.w3computing.com/articles/resource-acquisition-is-initialization-raii-in-cpp/ RAII in C++] by W3computing

{{C++ programming language}}

{{Design Patterns patterns}}

[[Category:Articles with example C++ code]]

[[Category:Object-oriented programming]]

[[Category:Software design patterns]]

[[Category:Programming idioms]]

[[Category:C++]]