std::packaged_task(3)

💅 std::packaged_task(3) — C++ Standard Libary, bestie 💅

okay so welcome to the iconic std::packaged_task page from the C++ Standard Libary manual. Yes, the header spells it like that — we're keeping the vibes 💀. This is the full page, no details skipped, periodt.

🌸 NAME 🌸

std::packaged_task — literally std::packaged_task. That's the name, bestie.

✨ Synopsis ✨

Defined in header <future>:

Defined in header <future>
template< class > class packaged_task; //not defined (1) (since C++11)
template< class R, class ...ArgTypes >               (2) (since C++11)
class packaged_task<R(ArgTypes...)>;

The class template std::packaged_task wraps any Callable target (function, lambda expression, bind expression, or another function object) so that it can be invoked asynchronously. Its return value or exception thrown is stored in a shared state which can be accessed through std::future objects.

Just like std::function, std::packaged_task is a polymorphic, allocator-aware container: the stored callable target may be allocated (until C++17) on heap or with a provided allocator. slay.

🛠️ Member functions 🛠️

• constructor — constructs the task object (public member function)
• destructor — destructs the task object (public member function)
• operator= — moves the task object (public member function)
• valid — checks if the task object has a valid function (public member function)
• swap — swaps two task objects (public member function)

🎁 Getting the result 🎁

• get_future — returns a std::future associated with the promised result (public member function)

🏃 Execution 🏃

• operator() — executes the function (public member function)
• make_ready_at_thread_exit — executes the function ensuring that the result is ready only once the current thread exits (public member function)
• reset — resets the state abandoning any stored results of previous executions (public member function)

🫶 Non-member functions 🫶

• std::swap(std::packaged_task) — specializes the std::swap algorithm (C++11) (function template)

🧰 Helper classes 🧰

• std::uses_allocator<std::packaged_task> — specializes the std::uses_allocator type trait (C++11) (until C++17) (class template specialization)
• Deduction guides(since C++17) 🫶

🧪 Example 🧪

// Run this code — go off, bestie:

        #include <cmath>
        #include <functional>
        #include <future>
        #include <iostream>
        #include <thread>

        // unique function to avoid disambiguating the std::pow overload set
        int f(int x, int y) { return std::pow(x, y); }

        void task_lambda()
        {
            std::packaged_task<int(int, int)> task([](int a, int b)
            {
                return std::pow(a, b);
            });
            std::future<int> result = task.get_future();

            task(2, 9);

            std::cout << "task_lambda:\t" << result.get() << '\n';
        }

        void task_bind()
        {
            std::packaged_task<int()> task(std::bind(f, 2, 11));
            std::future<int> result = task.get_future();

            task();

            std::cout << "task_bind:\t" << result.get() << '\n';
        }

        void task_thread()
        {
            std::packaged_task<int(int, int)> task(f);
            std::future<int> result = task.get_future();

            std::thread task_td(std::move(task), 2, 10);
            task_td.join();

            std::cout << "task_thread:\t" << result.get() << '\n';
        }

        int main()
        {
            task_lambda();
            task_bind();
            task_thread();
        }

Output

        task_lambda: 512
        task_bind:   2048
        task_thread: 1024

🩹 Defect reports 🩹

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• DR LWG 3117 — applied to C++17; behavior as published: deduction guides for packaged_task were missing; correct behavior: added.

👀 See also 👀

• future — waits for a value that is set asynchronously (C++11) (class template)

---

okay that's the whole page, bestie. Source/version: http://cppreference.com, dated 2024.06.10 — mwah 💖✨