std::clock(3)

💖 std::clock(3) — the C++ Standard Library glow-up 💖

okay so bestie, this is the manual page for std::clock from the C++ Standard Library, and I'm literally obsessed with explaining it to you ✨

---

🌸 NAME 🌸

std::clock — yes, that's the whole name, no cap 💅

---

✨ Synopsis ✨

Defined in header <ctime>
std::clock_t clock();

so this function returns the approximate processor time used by the process since the beginning of an implementation-defined era related to the program's execution. To convert the result value to seconds, just divide it by CLOCKS_PER_SEC. 🫶

but here's the thing: only the difference between two values returned by different calls to std::clock is meaningful, because the beginning of the std::clock era does not have to coincide with the start of the program. Also, std::clock time may advance faster or slower than the wall clock, depending on the execution resources given to the program by the operating system. like, if the CPU is shared by other processes, std::clock time may advance slower than wall clock. on the other hand, if the current process is multithreaded and more than one execution core is available, std::clock time may advance faster than wall clock. wild, right? 🦋

---

🎀 Parameters 🎀

(none) — literally nothing, bestie. no arguments. periodt. 💅

---

🌈 Return value 🌈

Processor time used by the program so far, or std::clock_t(-1) if that information is unavailable or its value cannot be represented. so if you get -1, it's giving "I don't know, girl" energy 😭

---

💀 Exceptions 💀

Throws nothing. not a single throw. iconic. 🙈

---

🔥 Notes 🔥

On POSIX-compatible systems, clock_gettime with clock id CLOCK_PROCESS_CPUTIME_ID offers better resolution. so like, if you want more precision, that's the move, iykyk 💅

also, the value returned by clock() may wrap around on some non-conforming implementations. for example, on such an implementation, if std::clock_t is a signed 32-bit integer and CLOCKS_PER_SEC is 1'000'000, it will wrap after about 2147 seconds (about 36 minutes). so yeah, watch out for that on janky systems 💀

---

🧚 Example 🧚

This example demonstrates the difference between clock() time and real time. so cute, right? let's break it down.

// Run this code

#include <chrono>
#include <ctime>
#include <iomanip>
#include <iostream>
#include <thread>

// The function f() does some time-consuming work.
void f()
{
    volatile double d = 0;
    for (int n = 0; n < 10000; ++n)
        for (int m = 0; m < 10000; ++m)
        {
            double diff = d * n * m;
            d = diff + d;
        }
}

int main()
{
    const std::clock_t c_start = std::clock();
    auto t_start = std::chrono::high_resolution_clock::now();
    std::thread t1(f);
    std::thread t2(f); // f() is called on two threads
    t1.join();
    t2.join();
    const std::clock_t c_end = std::clock();
    const auto t_end = std::chrono::high_resolution_clock::now();

    std::cout << std::fixed << std::setprecision(2) << "CPU time used: "
              << 1000.0 * (c_end - c_start) / CLOCKS_PER_SEC << "ms\n"
              << "Wall clock time passed: "
              << std::chrono::duration<double, std::milli>(t_end - t_start) << '\n';
}

and that's the whole thing. it starts a clock, starts a wall clock, runs f() on two threads, joins them, stops both clocks, and prints the CPU time used and the wall clock time passed. simple but slay ✨

Possible output:

CPU time used: 1590.00ms
Wall clock time passed: 808.23ms

so you might get something like this, but your mileage may vary, bestie 💖

---

🌟 See also 🌟

• ctime converts a std::time_t object to a textual representation (function) — so like, it turns time into a string, cute.
• time returns the current time of the system as time since epoch (function) — classic, iconic.
• C documentation for clock — yeah, there's a C version too, iykyk.

---

that's it, bestie! this page is from http://cppreference.com, version 2024.06.10, and it's for std::clock(3). now go out there and measure some processor time like the main character you are 👑💖