RAII Introduction

Joe Linhoff

RAII, or Resource Acquisition is Initialization, is a programming idiom that originally came out of the C++ community. However, it’s a powerful approach that can be used in many languages, including old-fashioned C.

In this blog post, I’ll introduce the RAII concept and examine the guarantees it provides in C++. A subsequent post will demonstrate a way to do RAII in C that makes the same guarantees.

RAII was named by Bjarne Stroustrup, the father of C++. In his 1994 book The Design and Evolution of C++, he introduced the concept, to help the programmer “ensure that the resource is correctly released upon exit even if an exception occurs.”

The main idea behind RAII is to bind a resource (such as a file descriptor, a UART port, or so forth) to an object. The resource is held for exactly as long as the object exists. Therefore, as long as the object is valid, the resource is usable, and when the object is destroyed, the resource is released.

The concept is particularly powerful because if offers a way to ensure resources don’t leak when exceptions are triggered. That’s a productive guarantee that allows developers to reason about the validity of their code.

Guarantees

RAII is a structural idiom. Following this idiom, the structure of your code provides a number of guarantees.

RAII provides:

  • Protection from leaking resources: Resource accounting is managed by the object. The constructor and destructor work together to prevent leaks.
  • Assumption of validity: While the object is alive, the resource is assumed to be usable. (Although with some resources, such as a network socket, the resource may have become lost or unusable while the object still exists—for instance because the network went down. In these cases, the object’s code will need to test the resource before each access.)

Exception-safe resource management: Exceptions (in any language that has them) can cause the program to skip normal user-code. Thrown exceptions back out of functions, and, if provided, through matching try-catch blocks, in a process known as unwinding. The compiler-generated unwinding code guarantees calls to destructors on objects that are going out-of-scope. RAII piggybacks on the guaranteed call to the object’s destructor to ensure that the resource is released or destroyed when it needs to be.

These are structural guarantees: When you properly implement RAII, your code is guaranteed to handle resources correctly. Further, this correctness can be validated through inspection of your code.

As discussed below, there are a number of ways to write the constructor and destructor to achieve RAII. The right choice depends on the resource and the needs of the program.

Building RAII

All of the guarantees provided by RAII are set up during initialization, in the constructor.

RAII Constructor

When designing your constructor, take into account the dynamic contours of your resource. Generally, the way you setup your constructor will fall into one of three cases:

  • Previous allocation — pass ownership into constructor
  • Allocation inside the constructor
  • Later allocation — clear the reference in the constructor

I’ll discuss each of these cases below.

Case 1: Previous Allocation (Pass Resource Ownership In)

In this first case, the resource is already allocated or in existence before the constructor is called. Our RAII object keeps an accounting and wraps access, but doesn’t allocate the resource. Ownership of the resource is given to the RAII object, which, depending on the implementation, may be responsible for destroying the resource, or simply relinquishing ownership upon destruction.

Example 1.1: Fixed hardware resources, such as access to a UART, can be managed by passing a reference into the constructor. In this case, the resource becomes owned and managed by the RAII-object. All access to the UART is done through the object. The destructor relinquishes ownership.

Example 1.2: Dynamic message buffers may be passed to your program from the OS, a callback, or other external entity. Pass ownership of the message into the constructor of an RAII-object. All access to the message should be through this object. The destructor releases the message.

This approach makes sense when you are managing ownership and access, and not necessarily allocating or acquiring resources yourself.

Case 2: Allocation in Constructor

In the second case, the resource is allocated inside the constructor. An exception is thrown if the allocation fails. Once allocated, the resource is guaranteed usable until our destructor frees the resource.

Example 2.1: Allocate a block of memory, such as an audio frame buffer. When you need to allocate a block of memory for your program to operate, and this allocation should never fail, you may choose to make the allocation in the constructor. Professional programming dictates you check to make sure the allocation was successful, and that you throw an exception in the unlikely event that the allocation fails. Your destructor frees the allocation.

Example 2.2: Open a file or resource that should never fail. You may choose to open a needed configuration file in your constructor. Although there may be many reasons to believe this file will be successfully opened, you still must check the result of the file-open command. If the file-open fails, and there is no in-constructor workaround, you must throw an exception. Your destructor closes the file.

Example 2.3: The canonical case here is std::lock_guard<mutex>. The constructor for the lock_guard, which is an RAII-object takes an already-instantiated mutex object and calls mutex-lock. This call may or may not block, but it cannot fail. The lock_guard’s destructor calls mutex-unlock.

This approach makes sense when you need to allocate or acquire a resource, and the allocation or acquisition should never fail. If your constructor fails, you must throw an exception.

When implementing this case, take into account that destructors will not be called on objects that throw exceptions during their construction. Destructors are only called on objects that have been completely constructed.

Case 3: Later Allocation (Clear Reference in Constructor)

In the third case, the reference to the resource is cleared in the constructor. Resource allocation is done later. This is best for resources that are dynamic or transient.

Example 3.1: When you open a file on an external drive, you must take care. First off, the initial file-open may fail, and another attempt may be made later. Second, if the file opens successfully, the external drive may be disconnected at any time, and the file reference lost. We handle this transient nature by clearing the reference in the constructor and moving all the opening, closing, and reopening code into the object’s methods. All access to the resource first checks the validity of the resource. The destructor must check the reference before closing it.

Example 3.2: There is no guarantee when it comes to opening network connections. Even if successfully opened, a connection may drop at any time for any number of reasons. Handle this by simply clearing the reference to the connection in the constructor. All the opening and connection-handling code should be written in the RAII-object’s methods, outside the constructor and handle failures. All access to the connection must first check for a valid connection. The destructor must check the reference to the connection before closing it.

Example 3.3: As all allocations may fail, code that allocates buffers can be safely written this way. Clear the references to allocations in the constructor. Attempt the allocations later, outside the constructor and handle failures in an appropriate way. The destructor must check each reference, and free the allocated resources.

This approach makes sense for most dynamic and transient resources. RAII objects built with this approach are flexible and responsive to the dynamic nature of their resources. Likewise, program code that uses these objects must handle the additional cases.

RAII Destructor

The destructor follows through on the design choices you’ve made for your constructor. Write the destructor to cleanly handle the release, destruction, or accounting of the resource. The key is to balance the work done in the constructor.

Looking at the three types of constructors, here are considerations for the destructors:

Case 1: Previous Allocation

In the first case, the resource was pre-allocated and passed into our object’s constructor, we need to look to the ownership of the resource to determine how to return ownership.

Here are some possibilities:

  • If the resource was passed in as a smart pointer or object parameter, then, because the parameter-object will have its own destructor called, our object doesn’t have to explicitly make any calls.
  • If the resource is fixed, like a hardware port, we may not need to do anything.
  • If the resource needs freeing, or has another way it must be released, we need to release it here.

In this case, the reference to the resource is guaranteed to be valid in the destructor as it was pre-allocated or is fixed.

Case 2: Allocation in Constructor

In the second case, the resource was allocated in the constructor and we need to free that resource in the destructor. Here are some possibilities:

  • If the constructor created a thread, the destructor destroys the thread.
  • If the constructor opened a file, the destructor should close the file.
  • If the constructor connects to another resource, the destructor should disconnect.

The reference to the resource is guaranteed to be valid in the destructor. If the constructor threw an exception, this destructor will not be called.

Case 3: Later Allocation

The third case handles resources that are allocated after the constructor. This case also handles dynamic and transient resources acquired during the life of the object.

In this case, the constructor cleared the reference and did not allocate the resource. When the destructor runs, the reference will be valid if the resource was allocated, and remains allocated. Our destructor must check and free the resource if the reference is valid.

For example, in an RAII-object that holds a file reference, the constructor clears the reference. If a file was opened during program operation, and remains open, the reference will be set, and the destructor must close the file.

This is a powerful and simple case which many programmers likely consider standard practice.

Summary

RAII is an important C++ idiom for resource management. Notably, RAII provides a structural idiom for proper resource management with exceptions.

The power of the idiom is in the guarantees it provides. Properly used, the destructor for your RAII-object is guaranteed to be called to allow you to free resources.

In a future post, I’ll look at how to make the same guarantees in C.

Categories: RAII

Cardinal Peak
Learn more about our Audio & Video capabilities.

Dive deeper into our IoT portfolio

Take a look at the clients we have helped.

We’re always looking for top talent, check out our current openings. 

Contact Us

Please fill out the contact form below and our engineering services team will be in touch soon.

fake yeezys
We rely on Cardinal Peak for their ability to bolster our patent licensing efforts with in-depth technical guidance. They have deep expertise and they’re easy to work with.
Diego deGarrido Sr. Manager, LSI
Cardinal Peak has a strong technology portfolio that has complemented our own expertise well. They are communicative, drive toward results quickly, and understand the appropriate level of documentation it takes to effectively convey their work. In…
Jason Damori Director of Engineering, Biamp Systems
We asked Cardinal Peak to take ownership for an important subsystem, and they completed a very high quality deliverable on time.
Matt Cowan Chief Scientific Officer, RealD
Cardinal Peak’s personnel worked side-by-side with our own engineers and engineers from other companies on several of our key projects. The Cardinal Peak staff has consistently provided a level of professionalism and technical expertise that we…
Sherisse Hawkins VP Software Development, Time Warner Cable
Cardinal Peak was a natural choice for us. They were able to develop a high-quality product, based in part on open source, and in part on intellectual property they had already developed, all for a very effective price.
Bruce Webber VP Engineering, VBrick
We completely trust Cardinal Peak to advise us on technology strategy, as well as to implement it. They are a dependable partner that ultimately makes us more competitive in the marketplace.
Brian Brown President and CEO, Decatur Electronics
The Cardinal Peak team started quickly and delivered high-quality results, and they worked really well with our own engineering team.
Charles Corbalis VP Engineering, RGB Networks
We found Cardinal Peak’s team to be very knowledgeable about embedded video delivery systems. Their ability to deliver working solutions on time—combined with excellent project management skills—helped bring success not only to the product…
Ralph Schmitt VP, Product Marketing and Engineering, Kustom Signals
Cardinal Peak has provided deep technical insights, and they’ve allowed us to complete some really hard projects quickly. We are big fans of their team.
Scott Garlington VP Engineering, xG Technology
We’ve used Cardinal Peak on several projects. They have a very capable engineering team. They’re a great resource.
Greg Read Senior Program Manager, Symmetricom
Cardinal Peak has proven to be a trusted and flexible partner who has helped Harmonic to deliver reliably on our commitments to our own customers. The team at Cardinal Peak was responsive to our needs and delivered high quality results.
Alex Derecho VP Professional Services, Harmonic
Yonder Music was an excellent collaboration with Cardinal Peak. Combining our experience with the music industry and target music market, with Cardinal Peak’s technical expertise, the product has made the mobile experience of Yonder as powerful as…
Adam Kidron founder and CEO, Yonder Music
The Cardinal Peak team played an invaluable role in helping us get our first Internet of Things product to market quickly. They were up to speed in no time and provided all of the technical expertise we lacked. They interfaced seamlessly with our i…
Kevin Leadford Vice President of Innovation, Acuity Brands Lighting
We asked Cardinal Peak to help us address a number of open items related to programming our systems in production. Their engineers have a wealth of experience in IoT and embedded fields, and they helped us quickly and diligently. I’d definitely…
Ryan Margoles Founder and CTO, notion