RAII File Wrapper

The Unsafe C-Style Approach

As you know from your C background, handling files involves a disciplined pairing of fopen() and fclose(). While simple in theory, it's brittle in practice within C++.

Consider this function:

#include <cstdio>
#include <stdexcept>

void write_log(const char* message) {
    FILE* log_file = fopen("log.txt", "a"); // "a" for append
    if (log_file == nullptr) {
        // Can't open the file, maybe return or throw
        return;
    }

    if (message == nullptr) {
        fprintf(log_file, "Error: Received null message.\n");
        // Oops, we returned without closing the file!
        fclose(log_file); // We have to remember this here.
        return;
    }

    fprintf(log_file, "Log: %s\n", message);
    
    // What if fprintf fails and throws an exception? fclose is skipped.

    fclose(log_file); // And we have to remember it here.
}

Every exit path requires a manual fclose(). Forgetting one, or having an unexpected exception thrown, results in a resource leak. Over time, your program could run out of available file descriptors. RAII is designed to eliminate this entire class of bugs.

Building a Production-Quality RAII Wrapper

Instead of manually juggling the FILE*, we will encapsulate it in a C++ class that automatically manages its lifetime. Let's start by studying a complete implementation.

Deconstructing the FileHandle Wrapper

That example contains all the ingredients for a correct and safe RAII class. Let's break down its essential components.

1. Acquisition and Release (Constructor & Destructor)

The core of RAII is the constructor/destructor pair.

• Constructor: FileHandle(const char* filename, const char* mode) acquires the resource by calling fopen. Critically, it immediately checks if the acquisition succeeded. If fopen returns nullptr, the constructor cannot create a valid object, so it signals failure by throwing an exception. This is the standard C++ way to handle errors during construction.

• Destructor: ~FileHandle() noexcept releases the resource. It checks if m_handle is valid before calling fclose. The noexcept is vital: destructors should almost never throw exceptions. If an exception is already being handled (during stack unwinding), a second exception from a destructor will cause the program to immediately call std::terminate.

The C++ FAQ reinforces this idea, explaining that throwing from a constructor is the primary mechanism for reporting failure and that RAII objects ensure cleanup happens correctly.

2. Managing Ownership (The Rule of Five)

What should happen if you try to copy a FileHandle?

FileHandle fh1("log.txt", "w");
FileHandle fh2 = fh1; // What does this mean?

If the compiler generated a default copy, both fh1 and fh2 would contain the same FILE*. When fh2 goes out of scope, it would close the file. Then, when fh1 goes out of scope, it would try to close the same file handle again, resulting in undefined behavior.

To prevent this, we must define the object's ownership semantics. Since a file handle represents a unique resource, our wrapper should have unique ownership.

• Disallow Copying: We explicitly delete the copy constructor and copy assignment operator. This tells the compiler that FileHandle objects cannot be copied, preventing the double-close bug at compile time.

  FileHandle(const FileHandle&) = delete;
  FileHandle& operator=(const FileHandle&) = delete;
  

• Allow Moving: While copying is disallowed, transferring ownership is safe and useful. This is done with a move constructor and move assignment operator. The move constructor "steals" the resource (the FILE*) from the source object and sets the source's handle to nullptr. This ensures the source object's destructor won't try to release the resource, as only the new object owns it now. This is essential for returning RAII objects from functions.

These five functions (destructor, copy/move constructors, copy/move assignment operators) are known as the special member functions. The "Rule of Five" states that if you need to implement any of them, you should probably consider all five.

An Alternative: std::unique_ptr with a Custom Deleter

Building a custom RAII class is powerful, but C++ provides a generic tool for exactly this purpose when dealing with pointer-like resources: std::unique_ptr. You can think of std::unique_ptr as a pre-built, general-purpose RAII wrapper. By default, it calls delete on the pointer it owns, but we can customize this behavior with a custom deleter.

As the video showed, we can create a std::unique_ptr that owns a FILE* and knows to call fclose instead of delete when it's destroyed.

Here's how you'd do it in code:

#include <cstdio>
#include <memory>
#include <stdexcept>

// Define a custom deleter as a function object
struct FileCloser {
    void operator()(FILE* f) const {
        if (f) {
            fclose(f);
            // In a real application, you might log that the file is being closed.
        }
    }
};

// Create a convenient type alias for our RAII file handle
using UniqueFileHandle = std::unique_ptr<FILE, FileCloser>;

void use_unique_ptr_wrapper() {
    // Acquire the resource. The UniqueFileHandle now owns the FILE*.
    UniqueFileHandle log_file(fopen("log.txt", "a"));

    if (!log_file) {
        throw std::runtime_error("Failed to open log file.");
    }

    // Use the resource via the .get() method
    fprintf(log_file.get(), "Hello from a unique_ptr-managed file!\n");

    // No need to call fclose!
    // When log_file goes out of scope, its deleter (FileCloser) is automatically called.
}

This approach gives you all the benefits of RAII (automatic cleanup, exception safety, unique ownership) without having to write a full class every time. This is a powerful and very common pattern in modern C++.

// Creates a texture and returns a handle.
TextureHandle* create_texture(int width, int height);

// Destroys a texture. Must be called for every handle from create_texture.
void destroy_texture(TextureHandle* handle);

class ScopedTexture {
private:
    TextureHandle* m_handle;

public:
    // Constructor: Acquires the resource.
    explicit ScopedTexture(int width, int height) {
        m_handle = create_texture(width, height);
        if (!m_handle) {
            throw std::runtime_error("Failed to create texture");
        }
    }

    // Destructor: Releases the resource.
    ~ScopedTexture() noexcept {
        if (m_handle) {
            destroy_texture(m_handle);
        }
    }

    // --- Ownership Semantics (Rule of Five) ---

    // 1. Disallow copying
    ScopedTexture(const ScopedTexture&) = delete;
    ScopedTexture& operator=(const ScopedTexture&) = delete;

    // 2. Allow moving
    ScopedTexture(ScopedTexture&& other) noexcept : m_handle(other.m_handle) {
        other.m_handle = nullptr; // Leave the source object empty
    }
    ScopedTexture& operator=(ScopedTexture&& other) noexcept {
        if (this != &other) {
            if (m_handle) {
                destroy_texture(m_handle); // Release our own resource first
            }
            m_handle = other.m_handle;
            other.m_handle = nullptr;
        }
        return *this;
    }

    // Provide access to the underlying handle
    TextureHandle* get() const { return m_handle; }
};

Conclusion

In this lesson, you have moved from the theory of RAII to its practical implementation. You now know how to take an unsafe C-style API and wrap it in a robust, exception-safe C++ class that automates resource management.

Key Takeaways:

• An RAII wrapper class encapsulates a raw handle or pointer to a resource.
• The constructor is responsible for acquiring the resource and must signal failure by throwing an exception.
• The destructor is responsible for releasing the resource and should be marked noexcept.
• Correct ownership semantics are crucial. For unique resources like file handles, you should follow the Rule of Five: implement a destructor, delete the copy operations, and implement move operations to allow safe ownership transfer.
• For pointer-like resources, std::unique_ptr with a custom deleter provides a ready-made, powerful RAII solution.

What's Next?

We've now seen what RAII is and how to implement it. In the next lesson, we will take a deeper dive into stack unwinding. We will analyze the precise step-by-step process the C++ runtime follows when an exception is thrown, tracing how it destroys objects on the stack. This will give you a low-level, mechanical understanding of why RAII is the pillar of exception safety in C++.