DEV Community: llzzz

Deep dive into the C++ Passkey idiom

llzzz — Sun, 25 Oct 2026 09:36:52 +0000

1. Motivation: The Problem with `friend`

In C++, friend is a double-edged sword. If you allow your friend to touch you inappropriately, that would be hurt. If class A befriends another class B, then everything in A becomes visible to B. friend grants all-or-nothing access — which is rarely what you actually want. You usually want your friend to only able to touch a portion of you.

Consider the following scenario. You have a Widget class that must be created through a factory, because the constructor needs to perform some privileged setup (registering with a resource manager, validating invariants, logging, and so on). But the constructor itself has to be public for std::make_unique or for the factory to reach it. The moment it is public, anyone can construct a Widget — and that is a correctness bug waiting to happen.

You might reach for friend:


class WidgetFactory;

class Widget {
    friend class WidgetFactory;   // grants access to EVERYTHING
public:
    Widget(int x) : x_{x} {}
private:
    int x_{};
};

class WidgetFactory {
public:
    static std::unique_ptr<Widget> create(int x) {
        return std::make_unique<Widget>(x);
    }
};

int main()
{
    auto w = WidgetFactory::create(42);   // ok
    // auto bad = std::make_unique<Widget>(42); // also ok! constructor is public, but you dont want this...
}

This "works," but it is a blunt instrument. WidgetFactory now has access to every private member of Widget, not just the constructor. As Widget grows, so does the accidental attack surface. And if you later need to grant the same narrow access to a Debugger class, you add another friend, and the surface widens again.

The question this idiom answers is:

How can I let a specific class touch only a specific portion of my class — and nothing else?

And then now let me introduce the PassKey Idiom.

2. The Classic Solution: A Nested PassKey

The core idea is to make a public function that requires an argument nobody else can construct. That argument is the passkey.

class Widget {
public:
    class PassKey {
        friend class Widget;
        PassKey() = default; // this constructor is private
    };

    Widget(PassKey, int x)
        : x_{x}
    {}

    static std::unique_ptr<Widget> create(int x)
    {
        return std::make_unique<Widget>(PassKey{}, x);
    }

private:
    int x_{};
};

int main()
{
    // auto w1 = Widget{Widget::PassKey{}, 42}; // compile error! cannot access private constructor
    auto w2 = Widget::create(42); // ok
}

A few things are worth calling out:

The constructor PassKey() = default; is implicitly private (it is a member of a class whose default access is private), and Widget is its only friend.
Widget's constructor is public, so it satisfies the syntactic requirements of std::make_unique. But it is only callable by code that can produce a PassKey — which, in practice, means only Widget itself (or whatever Widget chooses to befriend).
In main, the direct construction fails to compile because Widget::PassKey is private. The only way in is through create.

This is a clean, zero-boilerplate solution for a single class. But it does not scale. If you have Widget, Gadget, and Sprocket, you must replicate this nested-class boilerplate in every one of them. Worse, the authorized "friend" is baked into the nested definition, so if you want Widget's constructor callable by both a Factory and a Debugger, you either befriend both inside PassKey or duplicate the pattern. How to solve this? we can use a template!

3. Scaling Up: The Templated PassKey

The templated PassKey decouples the mechanism from the class it protects. You define it once, and any class can use it:

template <typename T>
class Passkey {
    friend T;             // only T can construct a Passkey<T>
    Passkey() = default;  // private: no one else can create one
};

Now the authorized class can create a passkey, and unauthorized code cannot:

class WidgetFactory;
class WidgetDebugger;

class Widget {
public:
    // Public constructor, but only callable by whoever can make a Passkey<WidgetFactory>
    Widget(Passkey<WidgetFactory>, int x)
        : x_{x}
    {}

    // A separate, narrower door for the debugger
    void dump(Passkey<WidgetDebugger>) const { /* ... */ }

private:
    int x_{};
};

class WidgetFactory {
public:
    static std::unique_ptr<Widget> create(int x) {
        return std::make_unique<Widget>(Passkey<WidgetFactory>{}, x);
    }
};

class WidgetDebugger {
public:
    void inspect(const Widget& w) {
        w.dump(Passkey<WidgetDebugger>{});
    }
};

int main()
{
    auto w = WidgetFactory::create(42);   // ok
    WidgetDebugger{}.inspect(*w);          // ok

    // auto bad = std::make_unique<Widget>(Passkey<WidgetFactory>{}, 1); // error
    // WidgetDebugger{}.inspect(...) can't call Widget's ctor; Factory can't call dump()
}

The design now has two key properties:

Per-function granularity. Widget's constructor admits only WidgetFactory. Widget::dump admits only WidgetDebugger. Neither can use the other's door. No friend grants blanket access.
Reusable mechanism. Passkey<T> is written once and works for any number of classes. There is no nested-class boilerplate to copy.

A subtle but important point: std::make_unique cannot construct the Passkey for you. The authorized class must explicitly pass Passkey<WidgetFactory>{} into the constructor call. That is by design — make_unique is not the privileged party; the caller is.

Improvement you can made if you are using C++20

C++20 does not fundamentally change the PassKey mechanism. There is no concept that replaces it, because concepts constrain types, whereas PassKey constrains who can produce a token. The two compose nicely, though: if you are building a generic system where the set of authorized callers is itself parameterized, you can write

#include <type_traits>

// Marker: only types deriving from this may be a Caller.
struct Privileged {};

// Passkey<T> only exists if T is privileged.
template <typename T>
    requires std::is_base_of_v<Privileged, T>
class Passkey {
    friend T;
    Passkey() = default;
};

class Widget {
public:
    Widget(Passkey<class Factory>, int x) : x_{x} {}
private:
    int x_{};
};

// Factory opts in — so it can make a Passkey<Factory>.
class Factory : Privileged {
public:
    static Widget create(int x) { return Widget(Passkey<Factory>{}, x); }
};

// Sneaky does NOT opt in — so Passkey<Sneaky> won't compile.
class Sneaky {
public:
    // Widget w{Passkey<Sneaky>{}, 1};  // error: constraint not satisfied
};

That's the whole idea. Widget's constructor is public, but the only way to call it is to hand it a Passkey<Factory> — and only Factory can construct one, because Factory is the friend. The requires clause adds one extra guarantee: you can't even write Passkey<X> unless X derives from Privileged, so unauthorized types fail at the template level instead of at the friend level.

4. Group Permissions: Variadic Friends (C++26)

The templated PassKey has one remaining friction point. Suppose a single function should be callable by several authorized classes — say a Factory, a Debugger, and a Serializer. Before C++26, you cannot write friend Ts...; expanding a parameter pack in a friend declaration is ill-formed. The workarounds are ugly: manual overloads, a combined passkey type, or a chain of nested friends.

C++26 fixes this with variadic friends (P2893R3). You can now expand a pack directly:

#include <iostream>

// C++26: variadic friends — one passkey authorizes a whole pack of types.
template <typename... Ts>
class Passkey {
    friend Ts...;
    Passkey() = default;
};

class Factory;
class Debugger;
class Serializer;

class Widget {
public:
    // Only Factory, Debugger, and Serializer can call this.
    void secretInit(Passkey<Factory, Debugger, Serializer>) {
        std::cout << "Widget initialized\n";
    }
};

// Each authorized type can build the passkey — and thus call secretInit.
class Factory {
public:
    void make(Widget& w) { w.secretInit(Passkey<Factory, Debugger, Serializer>{}); }
};

class Debugger {
public:
    void poke(Widget& w) { w.secretInit(Passkey<Factory, Debugger, Serializer>{}); }
};

class Serializer {
public:
    void save(Widget& w) { w.secretInit(Passkey<Factory, Debugger, Serializer>{}); }
};

// Not in the pack — cannot construct the passkey.
class Intruder {
public:
    // void tryIt(Widget& w) { w.secretInit(Passkey<Factory, Debugger, Serializer>{}); }
    //   ^ error: Passkey ctor is private; Intruder is not a friend.
};

int main()
{
    Widget w;
    Factory{}.make(w);        // ok
    Debugger{}.poke(w);       // ok
    Serializer{}.save(w);     // ok
}

This makes the "group permission" case a one-liner and removes the need for the combined-type hack. It is a small language feature, but for the PassKey idiom it is a meaningful ergonomic win: the passkey now expresses "these N types, and no others" directly in the type system.

5. Performance and Trade-offs

Runtime cost

In theory, passing an empty object by value could cost a register or a stack slot. In practice, in optimized builds, it is a zero-cost abstraction. Because Passkey has no data members and the parameter is unnamed, the optimizer elides it entirely at -O1 and above. There is no runtime check, no branch, no token comparison — the entire mechanism lives in the type system and disappears in the emitted code.

The one caveat

If the protected function is not inlined (defined in a separate translation unit, and LTO is disabled), the calling convention may still require passing a byte for the empty class to satisfy the ABI. This is a minor, usually irrelevant cost. For header-only or inlined usage — which is the common case — there is no overhead at all.

Compile-time cost

Slightly more template instantiation (one specialization per authorized type), and slightly longer function signatures. This is the real price, but it is usually trivial.

Readability trade-offs

Signatures get noisier: Widget(Passkey<Factory>, int) is visually heavier than Widget(int).
The unnamed parameter convention (see below) is what keeps it readable; without it, reviewers wonder what the argument is for.
The mechanism is compile-time enforced, so the compiler error when someone tries to bypass it is clear — but the reason the parameter exists is not obvious to a reader seeing the class for the first time. A brief comment on the constructor is worth the cost.

6. Idiomatic Usage and Best Practices

Leave the parameter unnamed. Write void foo(Passkey<T>), not void foo(Passkey<T> key). The unnamed parameter signals "this is a token, not data — it carries no information and is never used in the body."
Mark the constructor explicit if you are being defensive. explicit Passkey() = default; is not strictly required — the private access already blocks unauthorized construction — but it guards against brace-initialization surprises and makes intent explicit. It is harmless and recommended for older-standard compatibility (C++17 or earlier).
Prefer the templated form. The nested form is fine as a teaching example, but the templated form is the one to use in production.
Document the contract. A one-line comment — // only Factory may construct Widget — saves future readers from reverse-engineering the idiom.

8. Summary

friend is all-or-nothing; the PassKey idiom gives you per-function, per-caller access control.
The nested PassKey is the minimal teaching form; the templated Passkey<T> is the idiomatic production form.
C++26 variadic friends (friend Ts...) turns "group permissions" into a one-liner, removing the last piece of friction.
It is a zero-cost abstraction in optimized builds; the cost is compile-time and readability, not runtime.
Use it for restricted constructors and sensitive methods; use Attorney-Client when you need to expose members instead.

Happy coding!

Why prefer std::make_unique over new in std::unique_ptr?

llzzz — Sat, 24 Oct 2026 03:20:58 +0000

In modern C++, when you need a std::unique_ptr, the idiomatic way to create it is:

auto ptr = std::make_unique<MyClass>();

rather than manually new-ing the object inside the unique_ptr constructor:

std::unique_ptr<MyClass> ptr{new MyClass()};

std::make_unique was introduced in C++14 to fill a gap that std::make_shared had already covered for shared ownership. It is a small function template, but it carries several important advantages. This article walks through every reason to prefer it, notes what changed in C++17 and C++20, and covers the cases where you still need the raw new form.

the implementation of std::make_unique is roughly the following:

namespace std
{
    template<typename T, typename... Args>
    std::unique_ptr<T> make_unique(Args... args) noexcept
    {
        return std::unique_ptr<T>(new T{std::forward<Args>(args)...});
    }
}

1. Exception Safety

This is traditionally cited as the main reason for make_unique. Before C++17, the order in which function arguments are evaluated was unspecified. If you constructed a unique_ptr with new as one argument among several, a leak could occur if another argument threw after the new expression completed but before the unique_ptr constructor took ownership of the raw pointer.

Here is an example:

class T {};

struct U {
    U()
    {
        throw std::runtime_error("boom");
    }
};

int main()
{
    foo(std::unique_ptr<T>{new T{}}, std::unique_ptr<U>{new U{}});
}

Before C++17, a compiler was permitted to evaluate new T{} first, then evaluate new U{}, and only then call the unique_ptr constructors. If new U{} threw, the memory allocated for T had not yet been handed to a unique_ptr, so it leaked.

std::make_unique closes this hole because the allocation and the ownership transfer happen inside a single function call. The temporary unique_ptr is fully constructed before the surrounding expression continues, so if a later argument throws, stack unwinding destroys the already-constructed unique_ptr and frees the memory.

What changed in C++17

C++17 tightened the evaluation-order rules. In a function call, each argument expression is now fully evaluated before the next argument is evaluated, although the order in which the arguments are evaluated relative to each other is still unspecified. Because of this, the manual new form is no longer leak-prone in the exact multi-argument scenario above: once new T{} completes and its unique_ptr temporary is constructed, that temporary is a fully formed object, and an exception from another argument will destroy it correctly.

So if you are compiling as C++17 or later, the exception-safety motivation for make_unique is largely historical. The remaining reasons below are still valid.

2. Reduced Redundancy and `auto` Type Deduction

Using make_unique lets you write the type name once and rely on auto:

std::unique_ptr<MyClass>(new MyClass(args)); // MyClass written twice
auto ptr = std::make_unique<MyClass>(args);  // written once

Beyond brevity, this eliminates a class of bugs where the two type names drift apart during refactoring: one is changed but the other is not, producing a mismatched or ill-formed expression. The C++ Core Guidelines encode this as R.23: Use make_unique() to make unique_ptrs, citing both conciseness and exception safety.

Polymorphism caveat

make_unique does not perform polymorphic type erasure automatically. With auto, you get exactly the unique_ptr<T> corresponding to the template argument:

struct Base {
    virtual ~Base() = default;
};
struct Derived : Base {};

auto p1 = std::make_unique<Base>();    // std::unique_ptr<Base>
auto p2 = std::make_unique<Derived>(); // std::unique_ptr<Derived>, not unique_ptr<Base>

If you want a base-class handle, you must state the target type explicitly:

std::unique_ptr<Base> p = std::make_unique<Derived>();

This works because unique_ptr<Derived> converts to unique_ptr<Base> when Derived* converts to Base*. Also note the virtual destructor on Base: without it, deleting a Derived through a Base* is undefined behavior.

3. Enforcing a "No Raw `new`" Discipline

Every occurrence of new in application code must be audited for lifetime correctness: is it deleted exactly once, through the correct type, with the correct delete form? make_unique removes that audit burden from the call site. If the owning object has a correct lifetime, the unique_ptr it produces has a correct lifetime.

This lets you adopt a simple, mechanically checkable rule: do not write new in your codebase except inside the implementation of a factory or a low-level container. As Scott Meyers and others have put it, make_unique teaches “never say new/delete” without disclaimers.

4. Array Safety

make_unique distinguishes scalar and array types and returns the appropriate unique_ptr:

auto a = std::make_unique<int[]>(10); // std::unique_ptr<int[]>
auto b = std::make_unique<int>(42);   // std::unique_ptr<int>

With the manual constructor, nothing prevents you from writing a mismatched pair such as std::unique_ptr<int>(new int[10]) or std::unique_ptr<int[]>(new int(42)), both of which lead to undefined behavior when the default deleter uses the wrong delete form.

(make_unique<T[N]> for a fixed bound N is also permitted, but it is almost always a mistake because unique_ptr<T[N]> does not have array-covariant behavior in the way you might expect.)

5. Consistency with `make_shared` and Easy Switching

You should already be using std::make_shared for shared ownership (it performs a single combined allocation, unlike shared_ptr<T>(new T)). Using make_unique gives your codebase a uniform creation syntax:

auto u = std::make_unique<T>(args);
auto s = std::make_shared<T>(args);

This consistency pays off when requirements change. Switching between exclusive and shared ownership becomes a one-token edit:

auto p = std::make_unique<T>(args); // change to std::make_shared<T>(args)

With the manual form, that switch requires rewriting the declaration, removing new, and reconciling the deleter.

6. `std::make_unique_for_overwrite` (C++20)

C++20 added std::make_unique_for_overwrite for the case where you want to allocate an object without value-initializing it:

auto buffer = std::make_unique_for_overwrite<char[]>(size);
auto obj    = std::make_unique_for_overwrite<MyPod>();

For scalar types, make_unique<T>() value-initializes (T()), which zero-initializes fundamental types. For large buffers this can be an unnecessary cost. make_unique_for_overwrite performs default-initialization instead, matching what new T does for fundamental types, while preserving all the ownership and exception-safety benefits of the factory function.

When Not to Use `std::make_unique`

There are two well-defined cases where the manual constructor is still required.

Custom deleters

make_unique always uses std::default_delete<T>, which calls delete (or delete[]). It cannot accept a custom deleter, because its variadic template parameters are forwarded to the object constructor, not to the unique_ptr constructor. If you are wrapping a C API handle or a resource that is not released with delete, construct the unique_ptr directly:

std::unique_ptr<FILE, decltype(&fclose)> file{std::fopen("data.bin", "rb"), &fclose};

A common workaround is to define your own make_unique overload for the resource type in your own namespace.

Private or protected constructors

std::make_unique is not a friend of your class, so it cannot invoke a private or protected constructor. If a class restricts construction to factory member functions, the factory must construct the raw pointer internally and pass it to a unique_ptr:

class Widget {
private:
    Widget();
public:
    static std::unique_ptr<Widget> create() {
        return std::unique_ptr<Widget>(new Widget());
    }
};

or you can use the PassKey idiom if you really want to use std::make_unique

class Widget {
public:
    class Key {
    private:
        // this constructor is private
        Key() = default;
        friend class Widget;   // only this class can make a Key
    };

    // "Public" constructor, but requires a Key you can't forge.
    Widget(Key, int size) : size_(size) {}

    static std::unique_ptr<Widget> create(int size) {
        return std::unique_ptr<Widget>(new Widget(Widget::Key{}, size));
    }
private:
    int size_;
};

int main()
{
    Widget w(Widget::Key{}, 5);   // error: Key's constructor is private
}

but the passkey idiom is a topic for a separate post, so we won't expand on it here.

Summary

Default to std::make_unique. Its headline selling point — exception safety — has lost some of its bite since C++17 tightened the evaluation-order rules, so consider the famous leak example a historical artifact rather than a live threat. The other arguments, though, are still pulling their weight: it writes the type once instead of twice, it plays nicely with auto, it keeps your arrays and scalars from getting their deletes crossed, and it lets you adopt a clean "no raw new" policy without asterisks.

Reach for the manual unique_ptr constructor only when make_unique genuinely can't help you: custom deleters (it always uses default_delete) and constructors that are private or protected. Everywhere else, let make_unique do the new-ing so you don't have to.