RAII: Cleanup You Cannot Forget

// raii_basics.cpp - a cleanup that every path out of a function runs
#include <cstdio>

// A shared bus, and a count of who holds it: 0 means free.
static int bus_holders = 0;
static void bus_lock() { bus_holders++; }
static void bus_unlock() { bus_holders--; }

// The C way: every way out of the function must remember to unlock.
static int read_sensor_c(int channel) {
    bus_lock();
    if (channel > 3) {
        return -1;                  // this path forgets bus_unlock()
    }
    int value = channel * 100;
    bus_unlock();
    return value;
}

// The C++ way: the unlock lives in a destructor, and every way out runs it.
class BusLock {
public:
    BusLock() { bus_lock(); }
    ~BusLock() { bus_unlock(); }
};

static int read_sensor(int channel) {
    BusLock lock;
    if (channel > 3) {
        return -1;                  // the destructor runs here too
    }
    return channel * 100;
}

// The call has finished before report() runs, so bus_holders is read afterwards.
static void report(const char *who, int channel, int result) {
    std::printf("%-4s channel %d: returned %4d, bus holders afterwards %d\n", who, channel, result, bus_holders);
}

int main() {
    report("C", 2, read_sensor_c(2));
    report("C", 9, read_sensor_c(9));
    bus_holders = 0;
    report("C++", 2, read_sensor(2));
    report("C++", 9, read_sensor(9));
    return 0;
}

// irq_lock.cpp - a critical section that cannot be left open, and nests safely
#include <cstdint>
#include <cstdio>

// The chip's interrupt mask, faked for the PC: 1 means interrupts are off.
// On an Arm Cortex-M chip these four are CMSIS's __get_PRIMASK(), __set_PRIMASK(),
// __disable_irq() and __enable_irq().
static uint32_t primask = 0;
static uint32_t get_primask() { return primask; }
static void set_primask(uint32_t value) { primask = value; }
static void disable_irq() { primask = 1; }
static void enable_irq() { primask = 0; }

// Save the old state, switch interrupts off, and put the old state back at the end.
class InterruptLock {
public:
    InterruptLock() : saved_(get_primask()) { disable_irq(); }
    ~InterruptLock() { set_primask(saved_); }
    InterruptLock(const InterruptLock &) = delete;              // no copies: see 3.4
    InterruptLock &operator=(const InterruptLock &) = delete;

private:
    uint32_t saved_;
};

// The mistake: switch interrupts back on at the end, whatever they were before.
class BlindLock {
public:
    BlindLock() { disable_irq(); }
    ~BlindLock() { enable_irq(); }
};

static uint32_t total = 0;

static void add_reading(uint32_t reading) {
    InterruptLock lock;
    total = total + reading;
}

static void add_reading_blind(uint32_t reading) {
    BlindLock lock;
    total = total + reading;
}

static const char *irq() { return get_primask() ? "off" : "on"; }

int main() {
    std::printf("at the start:                   interrupts %s\n", irq());
    add_reading(10);
    std::printf("after add_reading:              interrupts %s\n", irq());
    {
        InterruptLock outer;
        std::printf("outer lock taken:               interrupts %s\n", irq());
        add_reading(20);
        std::printf("after a nested InterruptLock:   interrupts %s\n", irq());
        add_reading_blind(30);
        std::printf("after a nested BlindLock:       interrupts %s\n", irq());
    }
    std::printf("after the outer lock:           interrupts %s\n", irq());
    std::printf("total = %u\n", static_cast<unsigned>(total));
    return 0;
}

// irq_copy.cpp - trying to copy an InterruptLock
#include <cstdint>

class InterruptLock {
public:
    InterruptLock();
    ~InterruptLock();
    InterruptLock(const InterruptLock &) = delete;
    InterruptLock &operator=(const InterruptLock &) = delete;

private:
    uint32_t saved_;
};

void update() {
    InterruptLock lock;
    InterruptLock second = lock;
}

// chip_select.cpp - an SPI chip select that is released on every path out of a transfer
#include <cstdint>
#include <cstdio>

// A cut-down output pin, standing in for the OutputPin class from Volume 02.
class OutputPin {
public:
    void set() { high_ = true; }
    void clear() { high_ = false; }
    bool is_set() const { return high_; }

private:
    bool high_ = true;
};

// Chip select is active low: pulled low for the whole transfer, high again after it.
class ChipSelect {
public:
    explicit ChipSelect(OutputPin &cs) : cs_(cs) { cs_.clear(); }
    ~ChipSelect() { cs_.set(); }
    ChipSelect(const ChipSelect &) = delete;
    ChipSelect &operator=(const ChipSelect &) = delete;

private:
    OutputPin &cs_;
};

static OutputPin sensor_cs;
static bool sensor_present = true;

// A fake SPI exchange: a missing device answers 0xFF, as a floating data line would.
static uint8_t spi_exchange(uint8_t out) {
    if (!sensor_present) {
        return 0xFF;
    }
    std::printf("  exchanged 0x%02X while CS is %s\n", static_cast<unsigned>(out),
                sensor_cs.is_set() ? "high" : "low");
    return static_cast<uint8_t>(out + 1);
}

static int read_register(uint8_t reg) {
    ChipSelect select(sensor_cs);
    if (spi_exchange(reg) == 0xFF) {
        return -1;                      // no device: leave early, and CS still goes high
    }
    return spi_exchange(0x00);
}

int main() {
    int value = read_register(0x0F);
    std::printf("device present: read %d, CS is now %s\n", value, sensor_cs.is_set() ? "high" : "low");
    sensor_present = false;
    value = read_register(0x0F);
    std::printf("device missing: read %d, CS is now %s\n", value, sensor_cs.is_set() ? "high" : "low");
    return 0;
}

// clock_enable.cpp - a peripheral clock that stays on while anyone is using it
#include <cstdint>
#include <cstdio>

static uint32_t fake_clock_enable_reg = 0;      // one bit per peripheral clock, as on most chips
constexpr uint32_t ADC_CLOCK = 1u << 8;          // the bit for the ADC, in this made-up chip

class AdcClock {
public:
    AdcClock() {
        if (users_ == 0) {
            fake_clock_enable_reg = fake_clock_enable_reg | ADC_CLOCK;     // first user: clock on
        }
        users_++;
    }
    ~AdcClock() {
        users_--;
        if (users_ == 0) {
            fake_clock_enable_reg = fake_clock_enable_reg & ~ADC_CLOCK;    // last user gone: clock off
        }
    }
    AdcClock(const AdcClock &) = delete;
    AdcClock &operator=(const AdcClock &) = delete;

private:
    static inline uint32_t users_ = 0;
};

static const char *adc_clock() { return (fake_clock_enable_reg & ADC_CLOCK) ? "on" : "off"; }

static void check_battery() {
    AdcClock clock;
    std::printf("  check_battery: ADC clock %s\n", adc_clock());
}

static void log_temperature() {
    AdcClock clock;
    std::printf("  log_temperature: ADC clock %s\n", adc_clock());
    check_battery();                    // a second user, nested inside the first
    std::printf("  back in log_temperature: ADC clock %s\n", adc_clock());
}

int main() {
    std::printf("at the start: ADC clock %s\n", adc_clock());
    log_temperature();
    std::printf("afterwards: ADC clock %s\n", adc_clock());
    return 0;
}

// double_release.cpp - a class that releases something in its destructor, copied by accident
#include <cstdio>

// A tiny pool of four DMA channels, which reports a channel released twice.
static bool channel_in_use[4] = {false, false, false, false};

static int dma_claim() {
    for (int i = 0; i < 4; i++) {
        if (!channel_in_use[i]) {
            channel_in_use[i] = true;
            return i;
        }
    }
    return -1;
}

static void dma_release(int ch) {
    if (!channel_in_use[ch]) {
        std::printf("ERROR: channel %d released twice\n", ch);
        return;
    }
    channel_in_use[ch] = false;
    std::printf("channel %d released\n", ch);
}

class DmaChannel {
public:
    DmaChannel() : ch_(dma_claim()) { std::printf("channel %d claimed\n", ch_); }
    ~DmaChannel() {
        if (ch_ >= 0) {
            dma_release(ch_);
        }
    }
    int number() const { return ch_; }

private:
    int ch_;
};

static void log_channel(DmaChannel ch) {        // by value: the caller's object is copied
    std::printf("logging channel %d\n", ch.number());
}

int main() {
    DmaChannel tx;
    log_channel(tx);
    std::printf("back in main\n");
    return 0;
}

// no_copy.cpp - the same mistake, once copying has been deleted
class DmaChannel {
public:
    DmaChannel();
    ~DmaChannel();
    DmaChannel(const DmaChannel &) = delete;
    DmaChannel &operator=(const DmaChannel &) = delete;
    int number() const { return ch_; }

private:
    int ch_;
};

void log_channel(DmaChannel ch);

void send() {
    DmaChannel tx;
    log_channel(tx);
}

// by_reference.cpp - copying deleted, and the function takes a reference instead
#include <cstdio>

static bool channel_in_use[4] = {false, false, false, false};

static int dma_claim() {
    for (int i = 0; i < 4; i++) {
        if (!channel_in_use[i]) {
            channel_in_use[i] = true;
            return i;
        }
    }
    return -1;
}

static void dma_release(int ch) {
    channel_in_use[ch] = false;
    std::printf("channel %d released\n", ch);
}

class DmaChannel {
public:
    DmaChannel() : ch_(dma_claim()) { std::printf("channel %d claimed\n", ch_); }
    ~DmaChannel() {
        if (ch_ >= 0) {
            dma_release(ch_);
        }
    }
    DmaChannel(const DmaChannel &) = delete;
    DmaChannel &operator=(const DmaChannel &) = delete;
    int number() const { return ch_; }

private:
    int ch_;
};

static void log_channel(const DmaChannel &ch) {     // a reference: nothing is copied
    std::printf("logging channel %d\n", ch.number());
}

int main() {
    DmaChannel tx;
    log_channel(tx);
    std::printf("back in main\n");
    return 0;
}

// rule_of_zero.cpp - a class that writes none of the special functions
#include <array>
#include <cstdint>

class DmaChannel {
public:
    DmaChannel();
    ~DmaChannel();
    DmaChannel(const DmaChannel &) = delete;
    DmaChannel &operator=(const DmaChannel &) = delete;

private:
    int ch_;
};

// Rule of zero: its members look after themselves, so it declares no special functions.
class UartReceiver {
private:
    DmaChannel dma_;
    std::array<uint8_t, 64> buffer_;
};

void start() {
    UartReceiver rx;
    UartReceiver copy = rx;
}