RAII C++ — Double-Close Bug in Payment Gateway

Resource leaks are the most expensive bugs in systems programming. A database connection left open under an early return. A mutex never unlocked because an exception fired mid-function. A heap allocation living past its pointer. These aren't theoretical — they've crashed payment gateways and cost teams weeks of debugging. C++ doesn't have a garbage collector, but it has something better: deterministic destruction.

RAII — Resource Acquisition Is Initialization — solves this class of problems in one elegant move. Acquire a resource inside a constructor, release it inside the destructor. Because C++ guarantees the destructor runs when the object leaves scope — normal flow, early return, or exception — you get automatic, exception-safe cleanup for free.

This isn't a library feature or a keyword. It's a design principle baked into C++ lifetimes. By the end you'll know how to write RAII wrappers from scratch, why the standard library uses this pattern everywhere, what happens at the ABI level during stack unwinding, how to handle move semantics correctly in RAII types, and the production gotchas that even experienced C++ developers step on.

What is RAII in C++?

RAII is a design pattern that binds the lifecycle of a resource to the lifetime of a local object. The constructor acquires the resource, the destructor releases it. Because C++ destructors are deterministic — they fire exactly when the object goes out of scope — you get predictable cleanup without manual close() or free() calls.

Here's a minimal RAII wrapper for a file. Note how the destructor is called automatically, even if the read throws. That's the whole point.

#include <fstream>
#include <stdexcept>
#include <string>

namespace io::thecodeforge {

class FileGuard {
public:
    explicit FileGuard(const std::string& path)
        : file_(path, std::ios::in) {
        if (!file_.is_open()) {
            throw std::runtime_error("Failed to open: " + path);
        }
    }

    ~FileGuard() {
        if (file_.is_open()) {
            file_.close();
        }
    }

    // No copy — resource ownership can't be duplicated
    FileGuard(const FileGuard&) = delete;
    FileGuard& operator=(const FileGuard&) = delete;

    // Move transfers ownership
    FileGuard(FileGuard&& other) noexcept
        : file_(std::move(other.file_)) {}

    std::string read_line() {
        std::string line;
        if (!std::getline(file_, line)) {
            throw std::runtime_error("Read failed");
        }
        return line;
    }

private:
    std::ifstream file_;
};

} // namespace io::thecodeforge

// Usage — no manual close, even if read_line throws
void process_config(const std::string& path) {
    auto guard = io::thecodeforge::FileGuard(path);
    auto line = guard.read_line();
    // ... do work ...
    // ~FileGuard runs here
}

Destructors and Scope: The Guarantee That Makes It Work

The entire RAII pattern rests on one C++ guarantee: the destructor of a local object is called when the object leaves scope — for any reason. Normal return? Destructor fires. Early return from a guard clause? Destructor fires. Exception thrown mid-function? The stack unwinds and every fully-constructed local object's destructor is called. This is what makes RAII exception-safe by default.

Contrast with manual cleanup. A function that opens a file, acquires a lock, and then calls a function that might throw: if you forget to close or unlock in every path, you leak. With RAII, each resource is wrapped, and the destructor fires automatically. The compiler generates the cleanup code for you, woven into the stack unwinding logic.

#include <iostream>
#include <stdexcept>

namespace io::thecodeforge {

class ScopedPrinter {
public:
    explicit ScopedPrinter(const char* msg) : msg_(msg) {
        std::cout << "Acquire: " << msg_ << "\n";
    }
    ~ScopedPrinter() {
        std::cout << "Release: " << msg_ << "\n";
    }
private:
    const char* msg_;
};

void might_throw(bool should) {
    ScopedPrinter p("lock");    // acquires
    ScopedPrinter q("file");   // acquires
    if (should) {
        throw std::runtime_error("something bad");
    }
    // p and q destroyed here (if no throw) or during unwind
}

} // namespace io::thecodeforge

int main() {
    try {
        io::thecodeforge::might_throw(true);
    } catch (...) {
        std::cout << "Caught exception\n";
    }
    // Output:
    // Acquire: lock
    // Acquire: file
    // Release: file
    // Release: lock
    // Caught exception
}

RAII in the Standard Library: unique_ptr, lock_guard & fstream

The C++ standard library is built on RAII. Every resource-managing class you use daily follows this pattern. std::unique_ptr owns a heap-allocated object and deletes it when the unique_ptr goes out of scope. std::lock_guard locks a mutex on construction and unlocks it on destruction — no way to forget the unlock. std::ifstream opens a file in its constructor and closes it in its destructor.

Understanding these classes as RAII wrappers changes how you read code. When you see std::unique_ptr<T> p = std::make_unique<T>(args), you know the heap memory is safe. When a function returns a std::unique_ptr, ownership is transferred cleanly. No raw delete calls, no missing unlocks, no dangling file handles.

#include <memory>
#include <mutex>
#include <fstream>
#include <iostream>

namespace io::thecodeforge {

// Use unique_ptr for heap allocation
class Config {
public:
    void load() {
        std::lock_guard<std::mutex> guard(mutex_);  // lock automatically
        // ... parse config ...
        // destructor unlocks mutex_
    }
private:
    std::mutex mutex_;
};

// Factory returns unique_ptr — no ownership confusion
std::unique_ptr<Config> create_config(const std::string& path) {
    auto config = std::make_unique<Config>();
    // No raw new, no delete needed
    return config;
}

// Using an fstream in an RAII context
void process_line(const std::string& path) {
    std::ifstream file(path);  // opens in constructor
    if (!file) {
        throw std::runtime_error("cannot open");
    }
    std::string line;
    std::getline(file, line);
    // ~ifstream closes file automatically
}

} // namespace io::thecodeforge

Move Semantics and RAII: Correct Ownership Transfer

RAII types own resources exclusively. You cannot copy them (or copying would duplicate the resource handle, leading to double-free). But you must be able to move them — otherwise you can't return an RAII wrapper from a function, or pass it into a container. Move semantics solve this: a move constructor transfers the resource from the source to the destination, leaving the source in a valid-but-empty state (typically with a null handle). The source destructor then does nothing because there's nothing to release.

#include <utility>
#include <cstring>

namespace io::thecodeforge {

class Buffer {
public:
    explicit Buffer(size_t size)
        : data_(new char[size]), size_(size) {}

    ~Buffer() {
        delete[] data_;
    }

    // Copy = deleted because we own raw memory
    Buffer(const Buffer&) = delete;
    Buffer& operator=(const Buffer&) = delete;

    // Move constructor: steal the pointer
    Buffer(Buffer&& other) noexcept
        : data_(other.data_), size_(other.size_) {
        other.data_ = nullptr;  // empty state
        other.size_ = 0;
    }

    // Move assignment: release current, steal from other
    Buffer& operator=(Buffer&& other) noexcept {
        if (this != &other) {
            delete[] data_;               // release our old resource
            data_ = other.data_;
            size_ = other.size_;
            other.data_ = nullptr;
            other.size_ = 0;
        }
        return *this;
    }

private:
    char* data_;
    size_t size_;
};

// Returning a local Buffer from a function works because of move
Buffer create_buffer(size_t sz) {
    Buffer b(sz);
    // ... fill ...
    return b;  // move, not copy (even in C++11)
}

} // namespace io::thecodeforge

The Rule of Three, Five, and Zero

RAII ties directly to C++'s resource management rules. The Rule of Three says: if you need a custom destructor, copy constructor, or copy assignment, you probably need all three. The Rule of Five extends this to include move constructor and move assignment. The Rule of Zero says: if your class delegates all resource management to RAII members (like unique_ptr or vector), you don't need to write any of these special functions — the defaults work.

Understanding these rules helps you design RAII classes correctly. If you write a destructor but forget copy operations, you get shallow copies leading to double-free. If you write a move constructor but forget move assignment, you get undefined behaviour on assignment. The Rule of Zero is the ideal: let the standard library's RAII classes manage your resources.

Production Gotchas: Exception Safety, Circular References & ABI

Even with RAII, production C++ has traps. Exception safety: if an exception escapes a destructor during stack unwinding, std::terminate is called — your process dies. Always wrap destructor bodies with try-catch and log; never throw. Circular references with shared_ptr: two objects each holding a shared_ptr to the other never reach reference count zero. You get a memory leak that's invisible until the process dies. The fix is weak_ptr for back-pointers.

ABI compatibility: if you expose an RAII type across shared library boundaries, the destructor code must be in a compiled translation unit, not a header, to avoid ODR violations when different compilers link. Also, if the class has virtual functions, the vtable pointer must be the same everywhere.

#include <memory>
#include <iostream>

namespace io::thecodeforge {

// Bad: circular shared_ptr
struct Node {
    std::shared_ptr<Node> next;
    ~Node() { std::cout << "~Node\n"; }
};

void circular_demo() {
    auto a = std::make_shared<Node>();
    auto b = std::make_shared<Node>();
    a->next = b;
    b->next = a;  // circular — destructors never run!
}

// Fix: use weak_ptr for back references
struct Node2 {
    std::shared_ptr<Node2> next;
    std::weak_ptr<Node2> prev;  // weak, not shared
    ~Node2() { std::cout << "~Node2\n"; }
};

void no_circular_demo() {
    auto a = std::make_shared<Node2>();
    auto b = std::make_shared<Node2>();
    a->next = b;
    b->prev = a;  // weak, no cycle
    // both destroyed when original pointers go out of scope
}

// Destructor exception safety
class Risky {
public:
    ~Risky() noexcept(false) {
        // Simulate a failure
        throw std::runtime_error("destructor fail");
    }
};

void risk_demo() {
    try {
        Risky r1;
        Risky r2;  // both destructors will throw on unwind
    } catch (...) {
        // Only one exception escapes; second causes terminate
    }
}

} // namespace io::thecodeforge

RAII with Coroutines and Asynchronous Code

C++20 coroutines introduce a complication: the lifetime of a coroutine frame is controlled by the coroutine handle, not by standard scope. If a RAII object is captured by reference in a coroutine that outlives the object's scope, you get a dangling reference and undefined behaviour. The solution is to move the RAII object into the coroutine by value, or use shared_ptr to extend lifetime. Another gotcha: the promise_type object's destructor runs when the coroutine completes, not when it suspends. If the promise_type itself holds an RAII resource, ensure it's released correctly.

#include <coroutine>
#include <memory>
#include <iostream>

namespace io::thecodeforge {

struct Resource {
    ~Resource() { std::cout << "~Resource\n"; }
};

struct Task {
    struct promise_type {
        std::unique_ptr<Resource> res = std::make_unique<Resource>();
        Task get_return_object() { return {std::coroutine_handle<promise_type>::from_promise(*this)}; }
        std::suspend_never initial_suspend() { return {}; }
        std::suspend_always final_suspend() noexcept { return {}; }
        void return_void() {}
        void unhandled_exception() { std::terminate(); }
    };
    std::coroutine_handle<promise_type> handle;
    ~Task() { if (handle) handle.destroy(); }
};

Task example() {
    // Resource is owned by promise_type, destructor runs when coroutine completes
    co_return;
}

} // namespace io::thecodeforge

int main() {
    auto t = io::thecodeforge::example();
    // t's destructor calls handle.destroy(), which destroys promise and thus Resource
}

RAII With Acquisition Error Handling

Here's the flaw the competitors gloss over: what happens when the constructor fails? In C++, constructors have no return type. If open() returns -1, your Logger object is constructed with an invalid file descriptor, and the destructor will blindly close(-1). That's undefined behavior waiting to bite you in production. The fix is to throw an exception in the constructor when resource acquisition fails. This ensures the object is never fully constructed, so the destructor never runs. C++ guarantees that if a constructor exits via exception, the object's destructor is not called. But any fully constructed subobjects — like a std::string member — will still be cleaned up correctly. This is the RAII contract done right: either the object fully acquires its resources and is ready for use, or it doesn't exist at all. No zombie objects, no half-initialized state. I've seen production systems crash for weeks because someone checked is_open() instead of throwing. Don't be that team.

// io.thecodeforge
#include <iostream>
#include <string>
#include <unistd.h>
#include <fcntl.h>

class Logger {
public:
    explicit Logger(const std::string& path) 
        : log_fd_(open(path.c_str(), O_RDWR | O_CREAT, 0644)) {
        if (log_fd_ < 0) {
            throw std::runtime_error("Failed to open log file: " + path);
        }
    }

    void Log(const std::string& event) {
        write(log_fd_, event.c_str(), event.size());
    }

    ~Logger() {
        if (log_fd_ >= 0) {
            close(log_fd_);
        }
    }

private:
    int log_fd_;
};

int main() {
    try {
        Logger logger("/tmp/app.log");
        logger.Log("System initialized");
    } catch (const std::exception& e) {
        std::cerr << "Fatal: " << e.what() << '\n';
        return 1;
    }
}

RAII to Automatically Join a Thread

Threads are resources too. Every std::thread must be either joined or detached before destruction, or your program terminates. This is exactly the kind of resource management RAII solves elegantly. Instead of remembering to call join() at every exit path, wrap the thread in a class that joins in its destructor. The guarantee is simple: when the wrapper object goes out of scope — whether through normal flow, a return, or a thrown exception — the thread joins. I've fixed three production crashes in the last year where this pattern was missing. Junior devs forget to join, especially in error paths. The RAII wrapper removes the human factor. Use std::jthread in C++20 if you can update your toolchain, but writing your own scoped thread wrapper teaches you why the approach works. Just make sure to handle the join in the destructor, and explicitly delete copy operations to prevent two wrappers from racing to join the same thread.

// io.thecodeforge
#include <thread>
#include <iostream>

class ScopedThread {
    std::thread t_;
public:
    explicit ScopedThread(std::thread t) : t_(std::move(t)) {}
    
    ~ScopedThread() {
        if (t_.joinable()) {
            std::cout << "[ScopedThread] Joining thread\n";
            t_.join();
        }
    }
    
    ScopedThread(const ScopedThread&) = delete;
    ScopedThread& operator=(const ScopedThread&) = delete;
};

int main() {
    ScopedThread st(std::thread([]{
        std::cout << "Worker thread running\n";
    }));
    // No explicit join needed
}