0. Context​

The original pop_view<A>::operator* returned a copy (value_type), the supported container shape was fixed to pop() + top()/front() (i.e. only stack, queue, priority_queue), and size()/sized_range was deliberately left unimplemented. A reviewer pointed out that all three of these were more conservative than necessary. Each point below was checked independently — against the actual wording of the relevant concepts, and against a compiled, sanitizer-clean test — before being adopted.

1. operator* doesn't need to copy​

The claim. pop_iterator only models input_iterator. Nothing in that concept requires a previous *it result to remain valid once the iterator has been incremented — that guarantee belongs to forward_iterator, not input_iterator. So operator* can return an rvalue reference straight into the container instead of a copy, the same technique std::move_iterator uses for the same reason.

Why the claim holds up. The concept that actually constrains operator*'s return type is indirectly_readable, via iter_reference_t. It requires common_reference_with relationships between iter_reference_t, iter_value_t&, and iter_rvalue_reference_t — it does not require iter_reference_t to be a prvalue, and std::move_iterator is a standing precedent for returning an rvalue reference and still satisfying every iterator concept it claims to model. There's no requirement anywhere in input_iterator's definition that a dereferenced value keep being valid across ++.

The change:

// before
value_type operator*() const {
    return peek(*adaptor_);
}

// after
decltype(auto) operator*() const {
    return std::move(peek(*adaptor_));
}

What this changes for callers. auto v = *it; (including a range-based for's auto v) now selects v's move constructor instead of its copy constructor, whenever the underlying peek function (top()/front()/back()) returns a mutable reference. const auto& v = *it; or auto&& v = *it; read the element in place with no copy or move at all, same as before.

The one case that doesn't change: priority_queue. Its top() is const-qualified — it has to be, since mutating the top element in place could break the heap invariant that guarantees the top actually is the largest (or smallest, per the comparator) element. std::move() applied to a const T& still only binds to a copy constructor (a move constructor takes a non-const rvalue reference), so exactly one copy per element remains structurally unavoidable for priority_queue specifically — not a shortcoming of pop_range.

Measured proof. An instrumented probe type (counting copies and moves separately in its constructors) confirmed the following, with the counters reset immediately before draining (so numbers exclude the pushes that built the container):

2. Generalizing beyond the three container adaptors​

The claim. The same pattern works for anything exposing pop_front() and/or pop_back(), not just the pop()+top()/front() shape that stack, queue, and priority_queue share — so std::vector, std::deque, and std::list could be drained the same way.

The change. The concept was widened from one recognized shape to three, with a strict, shared priority order so that a type satisfying more than one shape (e.g. deque and list, which have both ends) can't have the "peek" half and the "consume" half of the code disagree about which end is in play:

template <typename A>
concept poppable_adaptor =
    requires(A& a) {
        typename A::value_type;
        { a.empty() } -> std::convertible_to<bool>;
    } &&
    ((has_nullary_pop<A> && (has_top<A> || has_front<A>)) ||
     (has_pop_front<A> && has_front<A>) ||
     (has_pop_back<A> && has_back<A>));

template <poppable_adaptor A>
decltype(auto) peek(A& a) {
    if constexpr (has_nullary_pop<A> && has_top<A>)        return a.top();
    else if constexpr (has_nullary_pop<A> && has_front<A>) return a.front();
    else if constexpr (has_pop_front<A> && has_front<A>)   return a.front();
    else                                                     return a.back();
}

template <poppable_adaptor A>
void consume(A& a) {
    if constexpr (has_nullary_pop<A>)                      a.pop();
    else if constexpr (has_pop_front<A> && has_front<A>)   a.pop_front();
    else                                                     a.pop_back();
}

The priority order (nullary pop() first, then pop_front(), then pop_back()) means: the three original adaptors are unaffected; vector — which only ever has pop_back() — drains from the back; deque/list — which have both — drain FIFO from the front by default, since pop_front() is checked before pop_back().

Measured proof.

vector (back()/pop_back(), LIFO order):  5 4 3 2 1
deque (front()/pop_front(), FIFO order): 1 2 3 4 5
list (front()/pop_front(), FIFO order):  1 2 3 4 5

All three drained to empty() afterward, as expected.

3. sized_range was more available than the original design assumed​

The claim. sized_range's requirement that ranges::size(t) be well-defined independent of evaluating ranges::begin(t) is scoped, in the standard's own wording, to types that also model forward_range. pop_view deliberately doesn't model forward_range. So that stability requirement never actually constrains pop_view, and there's no real obstacle to giving it a size().

Why the original design got this wrong. The first draft avoided size() out of a blanket worry that a shrinking, mutation-sensitive count would violate sized_range's contract in some general sense. On rereading the concept's actual definition, that concern is specifically tied to forward_range — for a plain, single-pass input_range, there's no such invariance clause to violate. "How many elements are left to pop right now" is exactly the semantics sized_range expects from a non-forward range.

The change:

[[nodiscard]] auto size() const
    requires requires(const A& a) { a.size(); }
{
    using size_type = decltype(std::declval<const A&>().size());
    return ptr_ ? static_cast<size_type>(ptr_->size()) : size_type{0};
}

Constrained with a requires clause on the member itself, so pop_view<A> only gains size() — and only models sized_range — for an A that actually has a .size() member (true for all of stack, queue, priority_queue, vector, deque, list).

Measured proof. For a stack<int> with 4 elements: view.size() == 4 before any iteration. After manually advancing the iterator twice (popping two elements): view.size() == 2. Extended the concept static_asserts to confirm sized_range<pop_view<std::stack<int>>> and sized_range<pop_view<std::vector<int>>> both hold, alongside the pre-existing input_iterator/input_range/view/!forward_range checks, which are unaffected.

4. Net result​

All three changes were verified together — not just individually — by compiling and running the full test suite (g++ 13.3.0, -std=c++20 and -std=c++23, -Wall -Wextra -fsanitize=address,undefined) after all three were applied: zero warnings, zero sanitizer reports, all assertions passing, including the new copy/move counters, the three new container types, and the two new sized_range static_asserts.

5. Where to find the updated code​

The revised pop_range.hpp and its expanded main.cpp test suite (reflecting all three changes above) are the versions delivered alongside this addendum. The original design document remains the reference for the library's overall history, motivation, and rationale sections, which are unaffected by this round of changes.

std::stack, std::queue, and std::priority_queue are container adaptors: thin wrappers around an underlying sequence container (vector, deque, list) that expose a deliberately restricted interface — push, pop, top/front, empty, size. None of them expose begin()/end(). This is not an oversight; it is a design decision inherited from the original SGI STL, whose documentation states outright that priority_queue "does not allow iteration through its elements." The rationale is that the adaptor's whole contract is "you may only ever see the current top/front element," and exposing arbitrary iteration would leak the underlying container's storage order (vector's heap layout, in the case of priority_queue), which is not part of the abstraction.

The consequence is that these three types cannot participate in the modern iteration and composition idioms C++ has accumulated since C++11 — range-based for, and since C++20, the <ranges> view/pipe machinery — because both require some notion of begin()/end(). This document describes pop_range, a small header-only library that closes that gap by giving these adaptors a well-defined, honestly-named destructive view: iterating it doesn't just read the adaptor, it drains it, one pop() per increment.

2. A Short History of Iteration Idioms in C++​

It's worth being precise about which feature arrived when, since the two headline features referenced in this document — range-based for and the pipe operator — are often conflated with the wrong standard versions.

2.1 C++11 — the range-based for loop​

Range-based for (for (auto& x : container) ...) was introduced in C++11 (originally proposed as N2930). It desugars to roughly:

{
    auto&& __range = range_expression;
    for (auto __it = begin(__range), __end = end(__range); __it != __end; ++__it) {
        auto&& x = *__it;
        loop_statement
    }
}

The requirement, as originally specified, was that begin(__range) and end(__range) produce values of the same type, because the loop compares them directly with operator!=. This is a strict requirement: the "end" has to be an actual iterator of the same type as "begin," not merely something comparable to it.

2.2 C++17 — generalizing range-based for (sentinels)​

C++17 didn't introduce range-based for — it generalized it, via P0184R0, "Generalizing the Range-Based For Loop". The requirement that begin() and end() return the same type was relaxed to only require that they be comparable with !=. This is what allows an end() to be a lightweight sentinel — a distinct type carrying no state, or carrying just enough state to answer "are we done?" — instead of a full iterator.

This sounds like a small wording change, but it's the piece of infrastructure that later made the C++20 ranges model possible: a sentinel_for<S, I> no longer has to be an I. It's also directly used in this project's own iterator: pop_iterator's "end" is std::default_sentinel_t, a stateless tag type, compared against the iterator via a friend operator==. Without the C++17 relaxation, we'd have had to give the sentinel the same type as the iterator (e.g., by giving pop_iterator a null/"end" state and constructing two of them), which is exactly the kind of awkwardness sentinels exist to avoid.

2.3 C++20 — <ranges>, views, concepts, and the pipe operator​

C++20 (via P0896R4, "The One Ranges Proposal") introduced the <ranges> library proper:

• A hierarchy of range/iterator concepts (range, view, input_iterator, forward_range, sized_range, common_range, ...) that formally describe what guarantees a given range provides, rather than just "it has begin/end."
• Views: lightweight, non-owning (or cheaply-movable), lazily-evaluated ranges, distinguished from containers by the view concept.
• Range adaptors (views::filter, views::transform, views::take, ...) and the pipe operator (|) for composing them: data | views::filter(p) | views::transform(f).

The pipe operator is not magic — it's operator| overloaded for a range on the left and an adaptor closure object on the right, which simply calls the adaptor with the range as its argument. Built-in adaptors like views::filter have supported | since C++20. What C++20 did not provide was a public, standard base class that lets user-defined adaptors opt into | for free — that arrived a version later.

2.4 C++23 — range_adaptor_closure and friends​

C++23 added std::ranges::range_adaptor_closure<D>, a CRTP base class that gives a user's own closure type the | operator automatically, plus ranges::to<Container>() for materializing a view into a concrete container, views::zip, and a few other conveniences. This is directly relevant here: our own views::pop needed operator| hand-written, because targeting plain C++20 meant range_adaptor_closure wasn't available (confirmed by compiling against libstdc++ 13: the type doesn't exist under -std=c++20, only under -std=c++23).

2.5 Summary table​

The common thread: every one of these features assumes the underlying type already exposes some notion of iteration. stack, queue, and priority_queue are conspicuous holdouts — by design, not oversight — which is the gap pop_range targets.

3. Design Goals​

1. Honesty about semantics. Iterating must visibly and unambiguously consume the adaptor. The name pop was chosen specifically so nobody mistakes this for a peek-only, repeatable view.
2. Minimal surface, maximal reuse. One adaptor should work for stack, queue, priority_queue, and any user type with the same shape — via a concept, not three copy-pasted specializations.
3. Correct concept membership. The result should satisfy exactly the concepts its behavior supports: input_range and view, and not forward_range, because a forward_range is required to let you traverse the same elements more than once, which is structurally impossible here.
4. Interoperability. It must compose with existing standard range adaptors (views::take, views::filter, ranges-based algorithms, etc.) without special-casing.
5. Two ownership modes. Adapting an existing, named container adaptor in place (pop(my_stack)), and adapting a temporary that the view itself should own (pop(make_stack())), so the pattern is convenient at a call site as well as reusable on an existing variable.
6. Plain C++20 portability, with graceful use of C++23 facilities where available, rather than a hard C++23 requirement.

4. Implementation​

4.1 The adaptor concept​

template <typename A>
concept poppable_adaptor =
    requires(A& a) {
        typename A::value_type;
        { a.empty() } -> std::convertible_to<bool>;
        a.pop();
    } && (requires(A& a) { a.top(); } || requires(A& a) { a.front(); });

This is the entire "interface requirement." It's deliberately structural (duck-typed via requires), not a stack/queue/priority_queue allow-list, so any type shaped like a container adaptor — including user-defined ones — is automatically supported. A small helper dispatches to whichever of top()/front() the type actually has:

template <poppable_adaptor A>
decltype(auto) peek(A& a) {
    if constexpr (requires { a.top(); })
        return a.top();
    else
        return a.front();
}

4.2 The iterator: single-pass, destructive, forward-only-in-motion​

pop_iterator<A> models std::input_iterator — the weakest of the standard iterator concepts, and the only choice here. Key points:

• operator*() returns a copy of the element (value_type, not a reference). top()/front() return a reference into the adaptor's storage, which becomes dangling the instant pop() runs — so the iterator must copy out the value before it can be safely incremented.
• operator++() calls A::pop() and then checks empty(); once empty, the iterator's internal pointer is set to nullptr, which is also the "end" state.
• Comparison against the end is against std::default_sentinel_t — a stateless tag from <iterator> — rather than another pop_iterator. This is the sentinel model that C++17's relaxation of range-based for made legal, and which C++20 ranges formalize via the sentinel_for concept.
• operator++(int) (postfix) returns void. This looks unusual coming from classic STL iterators, but it's conformant: std::weakly_incrementable (which every iterator concept builds on) only requires postfix ++ to be a valid expression, not that it return anything in particular — a carve-out that exists precisely to accommodate input iterators like this one, which have nothing meaningful to return a copy of after the value has been consumed.

template <poppable_adaptor A>
class pop_iterator {
public:
    using value_type       = typename A::value_type;
    using difference_type  = std::ptrdiff_t;
    using iterator_concept = std::input_iterator_tag;

    pop_iterator() = default;
    explicit pop_iterator(A* adaptor) noexcept : adaptor_(adaptor) {
        if (adaptor_ && adaptor_->empty()) adaptor_ = nullptr;
    }

    value_type operator*() const { return peek(*adaptor_); }

    pop_iterator& operator++() {
        adaptor_->pop();
        if (adaptor_->empty()) adaptor_ = nullptr;
        return *this;
    }
    void operator++(int) { ++(*this); }

    friend bool operator==(const pop_iterator& it, std::default_sentinel_t) noexcept {
        return it.adaptor_ == nullptr;
    }

private:
    A* adaptor_ = nullptr;
};

4.3 The view: reference or ownership, stable across moves​

pop_view<A> derives from std::ranges::view_interface<pop_view<A>> (for the usual free functions like empty()/front() that view_interface derives from begin()/end()), and supports two constructors:

• pop_view(A&) — adapt an existing, named adaptor. The caller keeps ownership and must keep it alive for as long as the view/iterators are used (an ordinary borrowing convention, same as std::span).
• pop_view(A&&) — take ownership of a temporary. The adaptor is moved into a std::unique_ptr<A>, specifically so that its address stays stable even if the view itself is later moved — iterators hold a raw pointer to the adaptor, not to the view, so a unique_ptr indirection is what prevents those iterators from dangling across a view move.

The view is move-only. It deliberately has no copy constructor: copying it would either have to deep-copy the entire underlying container (surprising and expensive for something that looks like a lightweight view) or alias the same adaptor from two independent views that would then race to pop() it. Move-only is the only model that doesn't quietly misbehave.

template <poppable_adaptor A>
class pop_view : public std::ranges::view_interface<pop_view<A>> {
public:
    pop_view() = default;
    explicit pop_view(A& adaptor) noexcept : ptr_(&adaptor) {}
    explicit pop_view(A&& adaptor)
        : owned_(std::make_unique<A>(std::move(adaptor))), ptr_(owned_.get()) {}

    pop_view(pop_view&&) = default;
    pop_view& operator=(pop_view&&) = default;
    pop_view(const pop_view&) = delete;
    pop_view& operator=(const pop_view&) = delete;

    pop_iterator<A> begin() const { return pop_iterator<A>(ptr_); }
    std::default_sentinel_t end() const noexcept { return std::default_sentinel; }

    [[nodiscard]] bool empty() const noexcept { return ptr_ == nullptr || ptr_->empty(); }

private:
    std::unique_ptr<A> owned_;
    A* ptr_ = nullptr;
};

pop_view is explicitly opted into enable_view:

template <typename A>
inline constexpr bool std::ranges::enable_view<pop_range::pop_view<A>> = true;

and is not a forward_range — this falls out naturally, since pop_iterator only satisfies input_iterator, and forward_range requires forward_iterator, which in turn requires that copies of the iterator be independently incrementable and still compare equal to each other where appropriate — a guarantee that's fundamentally incompatible with "advancing consumes the shared, singular underlying container."

4.4 views::pop: call syntax and pipe syntax, C++20-portable​

struct pop_fn {
    template <poppable_adaptor A>
    [[nodiscard]] auto operator()(A& adaptor) const { return pop_view<A>(adaptor); }

    template <poppable_adaptor A>
    [[nodiscard]] auto operator()(A&& adaptor) const { return pop_view<A>(std::move(adaptor)); }
};
inline constexpr pop_fn pop{};

template <poppable_adaptor A>
[[nodiscard]] auto operator|(A& adaptor, pop_fn) { return pop_view<A>(adaptor); }

template <poppable_adaptor A>
[[nodiscard]] auto operator|(A&& adaptor, pop_fn) { return pop_view<A>(std::move(adaptor)); }

As noted in §2.4, std::ranges::range_adaptor_closure would give | "for free," but it's a C++23 addition; verified directly by compiling a minimal check against libstdc++ 13 under both standards:

$ g++ -std=c++20 -fsyntax-only check.cpp   # error: 'range_adaptor_closure' does not name a type
$ g++ -std=c++23 -fsyntax-only check.cpp   # compiles

Hand-writing operator| sidesteps that dependency entirely, so the library works unmodified under -std=c++20.

5. Semantics and Guarantees​

A worked example of composability: pop(pq) | std::views::take(2) pops exactly two elements and stops — the other three elements are left completely untouched in the underlying priority_queue, confirmed by checking pq.size() afterward. This is only possible because views::take only asks its underlying range for input_range, which pop_view genuinely provides — nothing in the pipeline over-reads or over-pops beyond what was requested.

6. Testing​

The header (pop_range.hpp) and a demo/test program (main.cpp) were compiled and run with g++ 13.3.0:

• -std=c++20 and -std=c++23, both with -Wall -Wextra, zero warnings.
• -fsanitize=address,undefined for the full test run — no ASan/UBSan reports.
• Coverage: stack (LIFO order), queue (FIFO order), priority_queue (descending heap order), pipe syntax, composition with views::take (verifying partial-drain leaves the remainder untouched), ownership of an rvalue-returned adaptor, std::ranges::fold_left over the view, an empty container producing begin() == end(), and static_asserts pinning down the exact concept membership (input_iterator yes, input_range yes, view yes, forward_range no).
• A second, header-only smoke test confirmed the library compiles and runs correctly under plain -std=c++20 with no -std=c++23 dependency.

All cases passed.

7. Prior Art​

No published library implementing this exact pattern was found. The closest related material:

• The C++ standard library's own documentation is explicit that priority_queue "does not allow iteration through its elements" — the restriction this project works around is by design, not a gap anyone considers a bug.
• P1425, "Iterators pair constructors for stack and queue" addresses the opposite direction: constructing a stack/queue from a range, not extracting a range back out of one.
• A similar design tension shows up outside C++: a dart-lang/collection GitHub issue debates adding non-destructive, linear-time iteration to a priority queue, with a maintainer explicitly weighing (and being wary of) a destructive-iteration API — the same tradeoff this project resolves by naming the operation pop rather than pretending it's a peek.
• The general folk pattern in day-to-day C++ code is simply while (!pq.empty()) { use(pq.top()); pq.pop(); } written out by hand at each call site, rather than generalized into a reusable view — plausibly why nothing like pop_range shows up as an established library.

8. Limitations and Future Work​

• Not thread-safe. No synchronization is attempted; concurrent push/pop from other code while the view is being iterated is undefined behavior, same as it would be for the raw adaptor.
• operator* copies. For expensive-to-copy value_types, this is an inherent cost of the design (the alternative — returning a reference — is unsound, as noted in §4.2). Move-extraction is possible if A exposes a method to move the top element out before popping, but std::stack, std::queue, and std::priority_queue don't offer one, and the exercise intentionally targeted the standard adaptors as-is.
• No size()/sized_range. Deliberately omitted: since consuming elements changes size() while iterating, exposing it risks implying a stronger guarantee (like sized_range's expectation that size doesn't change under const, unmutated access) than is actually true.
• Possible extension: an explicit non-owning "peek view" (read-only, repeatable, requires a container that actually supports iteration, e.g., by exposing the underlying c member for stack/queue via the protected-inheritance trick some codebases use) would be a legitimate, complementary addition — but it is a fundamentally different, non-destructive contract and was out of scope here.

Appendix A: Full Source​

The complete, tested implementation is in pop_range.hpp, with a demonstration/test suite in main.cpp (both delivered alongside this document).

• The problem: preloading several ExoPlayer instances so playback can start instantly hits the VPU's shared decoder admission budget — creating too many MediaCodec hardware decoders concurrently gets rejected (OMX_ErrorInsufficientResources / MediaCodec.CodecException, ExoPlayer error codes 4001/4003) — even though only one video is ever actually playing at a time.
• Why it happens: ExoPlayer sets KEY_OPERATING_RATE to the real content frame rate — effectively "1x," the actual playback rate — on every decoder it creates, whether that decoder is actively playing or just sitting preloaded and idle (Section 5), and it never sets MediaFormat.KEY_PRIORITY at all (confirmed absent from MediaCodecRenderer.java/MediaCodecVideoRenderer.java). The net effect: the VPU's admission accounting has no signal telling it "this decoder isn't playing yet" and treats every created instance as if it needs guaranteed real-time decode throughput the moment it's created, not just once it's actually feeding frames. (Qualcomm's own kernel driver control technically defaults KEY_PRIORITY to non-realtime — Section 3.5 — but the resource exhaustion this document exists to solve is consistent with the vendor's closed-source Codec2/OMX HAL layer not preserving that default in practice; unverified from here, flagged as a caveat throughout.)
• The fix: explicitly set KEY_PRIORITY = 1 (non-realtime) and a low KEY_OPERATING_RATE on every decoder in the preload pool while it's idle, then flip both to realtime / full rate only on the one instance that's actually about to play (Section 6). Non-realtime load is charged at roughly resolution × 1 instead of resolution × fps in the admission math (Sections 3.1–3.3), and non-realtime instances are excluded entirely from the per-core clock-fit check that gates new decoder admission (Section 3.6). For 30fps video, that's roughly a 30× difference in admission cost between an idle non-realtime decoder and one actively playing at realtime priority (worked example, Section 3.4) — meaning, in principle, on the order of 30× more preloaded decoder instances can coexist in the same hardware budget than the naive "every decoder is realtime by default" approach allows.

1. The problem​

An app wants to preload several videos so playback can start instantly when the user picks one — but only one video ever plays at a time. The naive approach (create and start() a fully warm MediaCodec hardware decoder for every preloaded ExoPlayer instance) runs into a hard limit: the device's video decode block (VPU) rejects new decoder instances once the platform's admission-control accounting decides the combined load would exceed hardware capacity. This shows up as "insufficient resources" / codec creation failures once enough decoders are open concurrently, even though only one is ever actually decoding frames at once.

The real optimization target is hardware decoder component init latency — creating, configure()-ing, and start()-ing a MediaCodec against a HW codec is what's slow (tens of ms and up). Prefetching network/container data alone doesn't remove that latency; only having an already-initialized decoder does.

2. What the "MPS limit" actually is​

There's no single standardized "MPS limit" in AOSP. Two different things are easy to conflate:

• MediaCodecInfo.VideoCapabilities (getMacroblocksPerSecond(), isSizeAndRateSupported()) describes what one codec instance can sustain. This is public API and standardized.
• The shared, cross-instance VPU budget that rejects a new decoder once too many are open is enforced by the vendor's resource manager (Qualcomm, MediaTek, etc.), not by the Android framework. It's undocumented, implementation-specific, and can differ across SoC vendors, chipset generations, and even firmware/Android version updates on the same chipset.

Everything below was reverse-engineered from Qualcomm's msm-vidc kernel driver (the Venus/Iris video decode block used on Snapdragon devices). It is a case study, not a platform guarantee — see Section 8.

3. The core mechanism (Qualcomm case study)​

3.1 The load formula​

From msm_vidc_common.c (drivers/media/platform/msm/vidc/msm_vidc_common.c):

static int msm_comm_get_mbs_per_sec(struct msm_vidc_inst *inst)
{
    int output_port_mbs, capture_port_mbs;
    int fps;

    output_port_mbs = NUM_MBS_PER_FRAME(inst->prop.width[OUTPUT_PORT],
                                         inst->prop.height[OUTPUT_PORT]);
    capture_port_mbs = NUM_MBS_PER_FRAME(inst->prop.width[CAPTURE_PORT],
                                          inst->prop.height[CAPTURE_PORT]);

    if ((inst->clk_data.operating_rate >> 16) > inst->prop.fps)
        fps = (inst->clk_data.operating_rate >> 16) ?: 1;
    else
        fps = inst->prop.fps;

    return max(output_port_mbs, capture_port_mbs) * fps;
}

NUM_MBS_PER_FRAME(w, h) is (w × h) / (16 × 16) — macroblocks per frame. This per-instance value is summed across every open instance of a given type (msm_comm_get_load(), which iterates core->instances and adds msm_comm_get_mbs_per_sec() for each) and checked against a platform-defined max_load on codec creation and clock-scaling recalculation. That sum is the actual admission gate.

3.2 What KEY_OPERATING_RATE really does to that formula​

The critical detail: fps in the formula is max(configured frame-rate, operating_rate) — not the frame-rate alone. KEY_FRAME_RATE sets inst->prop.fps at configure() time; KEY_OPERATING_RATE sets clk_data.operating_rate.

This means declaring a low KEY_FRAME_RATE for idle/preloaded decoders and later raising KEY_OPERATING_RATE right before playback does not quietly bypass accounting — the moment operating rate goes up on an instance, that instance's contribution to the aggregate load recomputes to the real value too. The technique only works because the total is a sum across instances: as long as (N−1 idle instances × low load) + (1 active instance × full load) ≤ max_load, admission still succeeds. It requires bringing operating rate back down (or releasing/recreating the codec) once an instance stops being the active one — leaving it elevated defeats the "cheap while idle" premise.

3.3 Realtime vs. non-realtime sessions — the more robust lever​

The same file defines a documented split for exactly this pattern, in a comment directly above the load-calc logic:

                 | OPERATING RATE SET   | OPERATING RATE NOT SET |
-----------------|----------------------|------------------------|
REALTIME         | load = res * op_rate |  load = res * fps      |
                 | clk  = res * op_rate |  clk  = res * fps      |
-----------------|----------------------|------------------------|
NON-REALTIME     | load = res * 1 fps   |  load = res * 1 fps    |
                 | clk  = res * op_rate |  clk  = res * fps      |
-----------------|----------------------|------------------------|

For a non-realtime session (is_realtime_session(inst) false, gated by the LOAD_CALC_IGNORE_NON_REALTIME_LOAD quirk), the admission load stays pinned near the bare macroblock count (effectively "1 fps") regardless of operating rate, while the clk (actual achievable decode throughput) still scales with operating rate. In other words: a non-realtime-priority decoder can be clocked to real-time decode speed via KEY_OPERATING_RATE while still contributing almost nothing to the shared admission budget. This looks like the intended, driver-supported way to do what the frame-rate trick only approximates.

3.4 Worked example: four concurrent decoders​

The diagram above traces the full path — MediaFormat.KEY_PRIORITY → C2_PARAMKEY_PRIORITY (Codec2 vendor HAL) → is_realtime_session(inst) (msm-vidc kernel driver) → which branch of the load formula from Section 3.3 applies — and then applies it to four example MediaCodec instances: three preloaded/idle decoders configured non-realtime (KEY_PRIORITY = 1), and one actively-playing decoder configured realtime (KEY_PRIORITY = 0, the default). All numbers are illustrative, not a real device's certified budget.

Each instance's MPS (macroblocks per second) is NUM_MBS_PER_FRAME(w, h) × fps, where NUM_MBS_PER_FRAME rounds each dimension up to the nearest 16-pixel macroblock boundary before multiplying — this is why 1080p uses a height of 1088 (1080 isn't a multiple of 16; the hardware pads to 68 macroblock rows instead of 67.5) while 720p, whose dimensions are already multiples of 16, needs no rounding:

• Decoder A (non-realtime, idle): 1920×1088 → 120 × 68 = 8,160 mb/frame. Non-realtime forces fps = 1 for the load calculation regardless of the real content frame rate, so load = 8,160 × 1 = 8,160 MPS.
• Decoder B (non-realtime, idle): 1280×720 → 80 × 45 = 3,600 mb/frame. Same non-realtime rule: load = 3,600 × 1 = 3,600 MPS.
• Decoder C (non-realtime, idle): same resolution as A → load = 8,160 MPS.
• Decoder D (realtime, actively playing): 1920×1088 → 8,160 mb/frame. Realtime uses fps = max(configured_fps, operating_rate) = max(30, 30) = 30, so load = 8,160 × 30 = 244,800 MPS — roughly 30× more expensive than the same resolution sitting idle as non-realtime.

Summed: 8,160 + 3,600 + 8,160 + 244,800 = 264,720 MPS. Against the example MAX_LOAD ≈ 300,000 budget, that fits with roughly 35,000 MPS of headroom. The callout in the diagram shows why this matters: if all four decoders had instead been left at the realtime default while merely sitting idle (i.e. no KEY_PRIORITY override at all, each still counted at its full configured/operating fps), the sum would be 8,160×30 + 3,600×30 + 8,160×30 + 8,160×30 = 842,400 MPS — nearly 3× the same budget, and the fourth decoder would fail to admit. That gap is the entire value of the non-realtime-while-idle pattern from Sections 3.2–3.3.

3.5 Qualcomm's actual default, and what CTS actually tests​

Two directly-grounded findings, closing gaps left open above.

Qualcomm's driver-level default is non-realtime. In msm_vdec.c, the V4L2_CID_MPEG_VIDC_VIDEO_PRIORITY control's default_value is V4L2_MPEG_MSM_VIDC_DISABLE, and the DISABLE case inside msm_vdec_s_ctrl() clears VIDC_REALTIME (inst->flags &= ~VIDC_REALTIME). Since is_realtime_session() is !!(inst->flags & VIDC_REALTIME) and inst starts zero-initialized, a session that never touches KEY_PRIORITY is non-realtime by default at the kernel driver level — cheap (mb/frame × 1) rather than expensive (mb/frame × fps). This is grounded independently of, and matches, the generic AOSP contract quoted below. Caveat: this is the kernel control's default specifically; the vendor Codec2/OMX HAL sitting above it could still explicitly override it during its own init sequence, and that layer is closed-source and unverifiable from here.

What CTS actually tests isn't priority-specific MPS accounting — it's the resource-exhaustion contract. From AOSP's SoC vendor dependencies for media resource manager:

An Android Compatibility Test Suite (CTS) test exists to allocate, configure and start each codec repeatedly until catching OMX_ErrorInsufficientResources (pass) or any other error (fail).

There's no CTS assertion that a KEY_PRIORITY = 1 session gets any specific MPS discount — that math is vendor-internal policy, explicitly framed in the same doc as a "hint... for resource planning." What's actually certified is narrower: once a device's shared decoder budget is exhausted (however the vendor accounts for it), the component must fail with a clean, structured error — OMX_ErrorInsufficientResources, or its Codec2 equivalent C2_NO_MEMORY — rather than hang, crash, or ANR. CCodec.cpp carries that status up to the Java layer as MediaCodec.CodecException (the 0xfffffff4 / -12 / ENOMEM error reported against real devices in the wild, and the same failure class behind ExoPlayer's error codes 4001/4003 noted in Section 1). That's the behavior to design a retry/fallback path around when a preload pool actually does exceed budget on a given device — not graceful silent degradation.

The practical CTS-relevant bar for C2_PARAMKEY_PRIORITY itself is just that a compliant component must accept config()/query() on it without error (no C2_BAD_INDEX/unsupported-param failure) — CTS doesn't verify what the component does with the value internally.

3.6 The actual clk/core admission mechanism — and why it's realtime-aware by construction​

A natural follow-up question: is a resource-exhaustion failure (ENOMEM/OMX_ErrorInsufficientResources) triggered by load (the MPS-sum admission gate from Section 3.1) or by clk (the clock-scaling value from Section 3.3's table)? The honest answer is that they aren't two separate mechanisms — clk is load converted into hardware cycles, and the actual hard-failure path lives in msm_vidc_clocks.c, in msm_vidc_decide_core_and_power_mode():

if (current_inst_load + min_load < max_freq) {
    inst->clk_data.core_id = min_core_id;
    ...
} else if (current_inst_lp_load + min_load < max_freq) {
    ...
} else if (current_inst_lp_load + min_lp_load < max_freq) {
    ...
} else {
    rc = -EINVAL;
    dprintk(VIDC_ERR, "Sorry ... Core Can't support this load\n");
    return rc;
}

current_inst_load is msm_comm_get_inst_load(inst, ...) × vpp_cycles / work_route — the same REALTIME/NON-REALTIME-gated load value from Section 3.3's table (res×fps or res×1), converted to cycles/sec via a codec-specific cycles-per-macroblock constant. max_freq is allowed_clks_tbl[0].clock_rate — the fastest clock rate the SoC's VPU cores can run at. Failing every branch above returns -EINVAL ("Core Can't support this load") — the mechanism behind the resource-exhaustion failures discussed in 3.5.

The side of the comparison that matters most for this document is how "how full is this core already" gets computed — get_core_load(core, core_id, lp_mode, real_time), which filters:

real_time_mode = inst->flags & VIDC_REALTIME ? true : false;
...
if (real_time_mode != real_time)
    continue;

msm_vidc_decide_core_and_power_mode() always calls this with real_time = true — meaning only already-open realtime instances count toward how full a core is when deciding whether a new instance fits. Non-realtime instances are invisible to this sum entirely, and — because a non-realtime instance's own current_inst_load is computed at the "×1" rate — it barely registers its own demand either. This is the most direct, mechanistic confirmation in this document of the non-realtime-while-idle strategy from Sections 3.2–3.4: it isn't just cheap in the abstract MPS-sum math, it's specifically excluded from the exact code path that decides whether new decoders get admitted or rejected on a given core.

4. The three MediaFormat keys involved​

Recommended pattern given the driver behavior above: set KEY_PRIORITY = 1 at configure() time for every decoder in your preload pool, and toggle KEY_OPERATING_RATE dynamically per-instance — raise it right before feeding real frames to the instance that's about to play, lower it again once that instance goes back to being merely "preloaded."

Update on KEY_PRIORITY mutability: frameworks/av/media/codec2/sfplugin/CCodecConfig.cpp (the modern Codec2-based SDK→component mapping layer) maps KEY_PRIORITY to C2_PARAMKEY_PRIORITY with no domain restriction (Domain::ALL, which includes the IS_PARAM bit used for setParameters()), unlike KEY_OPERATING_RATE, which is explicitly restricted to D::PARAM | D::CONFIG and marked // write-only. In other words, the framework does not treat KEY_PRIORITY as configure-only — a live setParameters() call carrying it will be forwarded to the component. Whether the specific vendor Codec2 component actually honors a live priority change once running (vs. silently ignoring it) is component-specific and wasn't verifiable from this generic layer — test it directly: toggle KEY_PRIORITY via setParameters() on a running, idle decoder and watch the vendor's resource-manager/vidc logs to see whether its accounted load actually changes. If it does work live, you may not need a separate configure-only pool at all — you could flip a single decoder's priority down while idle and back up right before promoting it to active playback, alongside the operating-rate toggle.

5. What ExoPlayer / Media3 does out of the box​

Checked directly against the androidx/media source (release branch):

• MediaFormat.KEY_PRIORITY is never set anywhere in MediaCodecRenderer.java (the shared base class for all codec-backed renderers) or MediaCodecVideoRenderer.java. Every codec ExoPlayer creates gets whatever the platform/vendor default priority is (typically realtime, 0). ExoPlayer's own rendererPriority / MSG_SET_PRIORITY / PriorityQueue are an unrelated, ExoPlayer-internal renderer-scheduling concept — not the codec-level priority.
• KEY_OPERATING_RATE is actively managed. MediaCodecVideoRenderer.getCodecOperatingRateV23() computes it as the highest frame rate among the current adaptive stream formats × target playback speed. MediaCodecRenderer applies it at initial configure() and also updates it live later via codecParameters.putFloat(MediaFormat.KEY_OPERATING_RATE, newCodecOperatingRate) — confirming operating rate really is adjustable post-configure through setParameters(), both per Android's own docs and in ExoPlayer's actual implementation.
• The injection point for a custom KEY_PRIORITY/operating-rate policy already exists: MediaCodecVideoRenderer.getMediaCodecConfiguration() is protected and overridable, and ExoPlayer itself mutates the MediaFormat there before returning it (e.g. maybeSetKeyAllowFrameDrop() sets KEY_ALLOW_FRAME_DROP). A subclass can add mediaFormat.setInteger(MediaFormat.KEY_PRIORITY, 1) the same way.
• Caveat: getCodecOperatingRateV23()'s default logic derives operating rate from the real content frame rate regardless of whether the renderer is actually started or just sitting idle post-configure(). Left unmodified, a "preloaded but not yet playing" ExoPlayer instance will still request the real operating rate by default — you need to override this too so idle/preloaded instances ask for a low rate, and only the promoted "about to play" instance asks for the real one.

Note: Media3's PreloadMediaSource / DefaultPreloadManager (added ~1.4, extended through 1.8) is not a solution to this problem. It preloads MediaSource extraction/parsing/buffered sample data, and its shared RenderersFactory use is explicitly to check format compatibility "without creating the full renderers." It does not warm an actual MediaCodec decoder instance, so it doesn't touch decoder-init latency at all — the thing this whole exercise is trying to optimize.

6. Recommended design​

1. Maintain a bounded pool of ExoPlayer instances (or raw MediaCodec decoders) sized to fit your target devices' real admission budget — not "as many as the user might preload."
2. Subclass MediaCodecVideoRenderer (via a custom RenderersFactory) to override:
   • getMediaCodecConfiguration() — inject KEY_PRIORITY = 1 at configure() time for every decoder in the pool. Treat this as the safe default; if on-device testing (Section 7) confirms your target vendor's component honors live setParameters() priority changes, you can instead toggle it dynamically alongside operating rate rather than only setting it once.
   • getCodecOperatingRateV23() — return a low value while an instance is idle/preloaded; return the real value (content frame rate × speed) only once that instance is promoted to "about to actively play."
3. When promoting an instance to active playback, raise its operating rate (this can ride ExoPlayer's existing dynamic-update path); when demoting it back to idle, lower it again. Don't leave operating rate elevated on instances that aren't currently playing.
4. Don't rely on KEY_FRAME_RATE spoofing as the primary lever — treat KEY_PRIORITY (non-realtime) as the intended mechanism, and KEY_OPERATING_RATE as the real-time throughput control.

6.1 Concrete hook points: onStarted() / onStopped()​

BaseRenderer (the root of ExoPlayer's renderer hierarchy) exposes onStarted() and onStopped() lifecycle callbacks, fired when a renderer transitions to/from actually being started (i.e. playWhenReady and the player is in STATE_STARTED). MediaCodecRenderer.java already overrides both (currently no-ops, just present "to remove throws clause"), confirming these are legitimate, safe override points in a subclass — this is the natural place to promote/demote priority, separate from getMediaCodecConfiguration() which only runs once at codec creation.

As the diagram shows: getMediaCodecConfiguration() sets KEY_PRIORITY = 1 once, at configure() time, before the decoder ever plays anything. Overriding onStarted() is where you promote — call codec.setParameters() with KEY_PRIORITY = 0 and the real operating rate right as the renderer actually starts pushing frames. Overriding onStopped() is the mirror — drop back to KEY_PRIORITY = 1 and a low operating rate the moment the renderer stops being active (paused, ended, or the user swipes to a different preloaded item).

This isn't a new mechanism to build from scratch: MediaCodecRenderer.java already has a live parameter-update pipeline wired up — handleMessage(MSG_SET_CODEC_PARAMETERS) calls codec.setParameters(activeCodecParameters.toBundle()) — which is exactly how ExoPlayer pushes KEY_OPERATING_RATE changes to a running codec today. Extending the same Bundle to also carry KEY_PRIORITY from your onStarted()/onStopped() overrides reuses infrastructure that's already proven to work for live parameter changes on a running codec — the only open question (Section 7) is whether the vendor's Codec2 component actually acts on KEY_PRIORITY specifically, versus KEY_OPERATING_RATE, once it arrives.

7. Validation checklist (do this before shipping)​

• Confirm on each target chipset family (Qualcomm, MediaTek, Exynos, Unisoc, etc.) — the load formula above is Qualcomm-specific; other vendors have different resource managers with different, likely undocumented, logic.
• Watch adb logcat / kernel debug logs for the vendor's resource manager while creating decoders (ResourceManager, Codec2, OMX, vidc, "insufficient resource" strings) to see the actual summed load per instance and confirm it tracks KEY_PRIORITY/KEY_OPERATING_RATE as expected.
• Confirm whether the vendor's Codec2 component actually applies a live KEY_PRIORITY change sent via setParameters() on an already-running codec. The framework-level mapping (CCodecConfig.cpp) does forward it, but component-side acceptance is vendor/implementation-specific — this determines whether an idle-pool decoder can be "promoted" via a live priority flip or needs a reconfigure/recreate step instead.
• Verify actual decode is glitch-free (no dropped/late frames) the moment an idle, non-realtime instance is promoted and fed real frames at full operating rate — confirm the clock ramp-up doesn't introduce a startup stutter.
• Re-run all of the above after any OEM firmware or Android version bump on your test devices; this is implementation-defined behavior, not a platform contract, and can silently change.

8. Caveats​

• Everything under Sections 3–4 beyond the generic MediaFormat key documentation is grounded in one Qualcomm kernel driver source tree (msm-vidc, Nougat-era omx_vdec / msm_vidc_common.c). Modern devices largely run Codec2 rather than OMX, and the exact parameter path from MediaFormat.KEY_PRIORITY down to is_realtime_session() on a current Codec2-based Qualcomm stack was not directly traced in this session — it needs on-device confirmation.

• MediaTek: the mainline/upstream open-source MediaTek decoder driver (drivers/media/platform/mediatek/vcodec/, used mainly on ChromeOS devices — MT8173/8183/8186/8188/8192/8195) has no equivalent to Qualcomm's is_realtime_session()/MPS-load-formula anywhere in its structures (mtk_vcodec_dec_drv.h). Its resource model looks architecturally different: a fixed hardware-core count (MTK_VDEC_HW_MAX) with per-core mutexes (dec_mutex[]), not a summed numeric budget across instances. MediaTek's actual production Android phone Codec2 HAL (Dimensity/Helio) is closed-source and not published in AOSP, so its internal accounting can't be directly inspected the way Qualcomm's was.

  That said, AOSP's own SoC vendor dependencies for media resource manager documentation specifies OMX_IndexConfigPriority / C2_PARAMKEY_PRIORITY as a hook every SoC vendor — MediaTek included — is expected to implement for Android's media resource manager, backed by a CTS test that repeatedly allocates/configures/starts codecs until it catches OMX_ErrorInsufficientResources. So priority-based resource planning is a platform requirement, not a Qualcomm-only quirk. What's unconfirmed is whether MediaTek's internal accounting resembles Qualcomm's MPS-sum formula or something closer to the mainline driver's fixed-core model (which would behave differently under the "declare many non-realtime, promote one" pattern — worth testing directly on Dimensity/Helio hardware before relying on it).

  One more thing surfaced by that same AOSP doc, independent of the preload-pool question: it states priority defaults to non-realtime (1) unless explicitly configured to 0, and warns implementers not to assume realtime priority unless it's set. Section 5 confirmed ExoPlayer never sets KEY_PRIORITY at all — and Section 3.5 confirms, directly from msm_vdec.c, that Qualcomm's own kernel driver default agrees: the V4L2_CID_MPEG_VIDC_VIDEO_PRIORITY control defaults to DISABLE, which clears VIDC_REALTIME. So on Qualcomm at least, an ExoPlayer decoder that never sets KEY_PRIORITY should land non-realtime by default at the driver level — though whether the vendor's Codec2/OMX HAL layer above the kernel driver preserves that default, rather than overriding it during its own init, remains unverified (that layer is closed-source).

• Exynos, Unisoc, and other vendor resource managers were not investigated at all. Assume nothing about their behavior without separately confirming it.

• This entire approach is an unofficial technique riding on vendor implementation details, not a documented Android platform capability. It should be validated per target device and treated as something that can regress on firmware updates.

9. Sources​

• msm_vidc_common.c — realme5-kernel-source (Qualcomm msm-vidc driver)
• CCodecConfig.cpp — platform/frameworks/av (AOSP, SDK↔Codec2 key mapping)
• CCodecConfig.h — platform/frameworks/av (AOSP, Domain bitmask definitions)
• MediaFormat — Android Developers reference
• MediaFormat.java — platform/frameworks/base (AOSP)
• MediaCodecVideoRenderer.java — androidx/media (release branch)
• MediaCodecRenderer.java — androidx/media (release branch)
• MediaCodecInfo.java — androidx/media (release branch)
• Elevating media playback: Introducing preloading with Media3 — Part 1 (Android Developers Blog)
• Elevating media playback: A deep dive into Media3's PreloadManager — Part 2 (Android Developers Blog)
• PreloadMediaSource.java — androidx/media (release branch)
• mtk_vcodec_dec_drv.h — torvalds/linux mainline (MediaTek decoder driver)
• SoC vendor dependencies for media resource manager — Android Open Source Project
• msm_vdec.c — realme5-kernel-source (Qualcomm msm-vidc driver, V4L2_CID_MPEG_VIDC_VIDEO_PRIORITY control default)
• CCodec.cpp — platform/frameworks/av (AOSP, Codec2↔MediaCodec status/error mapping)
• msm_vidc_clocks.c — realme5-kernel-source (Qualcomm msm-vidc driver, per-core clock/load admission — msm_vidc_decide_core_and_power_mode(), get_core_load())