Let’s explore how uvw manages the lifetime of asynchronous handles—particularly why user-created std::shared_ptr<TcpHandle> instances remain alive beyond thier lexical scope. This behavior is central to the library’s event-driven design and hinges on deliberate internal reference retention.

How Handles Persist Beyond Local Scope

Consider this typical usage pattern:

void start_server(uvw::Loop& loop) {
    auto server = loop.resource<uvw::TcpHandle>();
    server->on<uvw::ErrorEvent>([](const auto&) { /* ... */ });
    server->on<uvw::ListenEvent>([](const auto&) { /* ... */ });
    server->bind("0.0.0.0", "8080");
    server->listen();
}

void start_client(uvw::Loop& loop) {
    auto client = loop.resource<uvw::TcpHandle>();
    client->on<uvw::ConnectEvent>([](const auto&) { /* ... */ });
    client->connect("127.0.0.1", "8080");
}

int main() {
    auto loop = uvw::Loop::getDefault();
    start_server(*loop);
    start_client(*loop);
    loop->run();
}

At first glance, both server and client are local variables—yet they survive function returns and continue processing events. Why?

The answer lies not in the Loop storing them, but in self-retention: each handle captures a strong referance to itself during initialization.

Initialization Flow

Calling loop.resource<uvw::TcpHandle>() triggers the overload for types derived from BaseHandle:

template<typename R, typename... Args>
std::enable_if_t<std::is_base_of_v<BaseHandle, R>, std::shared_ptr<R>>
resource(Args&&... args) {
    auto ptr = R::create(shared_from_this(), std::forward<Args>(args)...);
    ptr = ptr->init() ? ptr : nullptr;
    return ptr;
}

This calls TcpHandle::init(), which internally invokes uv_tcp_init(). Upon success, Handle::initialize() is invoked—and that’s where the key step happens:

template<typename F, typename... Args>
bool initialize(F&& f, Args&&... args) {
    if (!this->self()) {
        const int err = std::forward<F>(f)(this->parent(), this->get(), std::forward<Args>(args)...);
        if (err) {
            this->publish(ErrorEvent{err});
        } else {
            this->leak(); // ← Critical: retains 'this' in member
        }
    }
    return this->self();
}

leak() stores this->shared_from_this() into a private member sPtr:

void leak() noexcept {
    sPtr = this->shared_from_this();
}

This creates a circular reference: the handle holds a shared_ptr to itself, preventing destruction until the underlying libuv handle is closed and the self-reference is explicitly cleared.

Verifying the Reference Count

A minimal reproduction confirms the mechanism:

struct SelfRetaining : std::enable_shared_from_this<SelfRetaining> {
    std::shared_ptr<SelfRetaining> self_ref;

    void retain() {
        self_ref = shared_from_this();
        std::cout << "Ref count after retain: " << self_ref.use_count() << "\n";
    }

    ~SelfRetaining() { std::cout << "Destroyed\n"; }
};

int main() {
    auto obj = std::make_shared<SelfRetaining>();
    std::cout << "Initial ref count: " << obj.use_count() << "\n";
    obj->retain(); // → ref count becomes 2
} // 'obj' goes out of scope → ref count drops to 1 → object stays alive

Output:

Initial ref count: 1
Ref count after retain: 2
Destroyed

The destructor runs only when the program exits—because self_ref keeps the object alive.

Why Not Store Handles in Loop?

One might ask: why not simply store all handles in a std::vector<std::shared_ptr<void>> inside Loop? While feasible, it would introduce unnecessary coupling, complicate ownership semantics, and require manual cleanup or weak-pointer bookkeeping. The self-retention model instead aligns with libuv’s native handle lifecycle: a handle lives as long as its underlying uv_handle_t is active—and uvw mirrors that contract at the C++ level.

C++ Language Deep Dives

Custom Deleters with std::unique_ptr

In Loop::getDefault(), uv_default_loop() returns a raw pointer that must not be freed via delete. Instead, uvw uses a custom deleter:

using Deleter = void(*)(uv_loop_t*);
auto def = uv_default_loop();
auto ptr = std::unique_ptr<uv_loop_t, Deleter>{def, [](uv_loop_t*){}};

This ensures no accidental deletion while still enabling RAII-style management. Similar patterns appear elsewhere—for example, wrapping FILE* with fclose:

auto fp = std::unique_ptr<std::FILE, decltype(&std::fclose)>{
    std::fopen("data.txt", "r"),
    &std::fclose
};

SFINAE via std::enable_if_t

The two overloads of resource() use std::enable_if_t to dispatch based on inheritance:

• If R inherits from BaseHandle, the first overload applies and calls init().
• Otherwise, the second overload skips initialization—suitible for non-handle resources like uvw::TimerHandle or custom wrappers.

This enables compile-time specialization without runtime branching or base-class virtual dispatch.

Design Implications

This self-retaining idiom makes uvw robust against accidental early destruction, but also requires users to explicitly close handles (e.g., via handle->close()) to break the cycle. Failure to do so leads to resource leaks—not memory leaks per se, but dangling libuv handles that prevent clean loop shutdown.

The pattern reflects a broader principle: when bridging C-style callback APIs with modern C++ abstractions, explicit ownership modeling often trumps implicit assumptions—even if it means holding a reference to oneself.