--- name: "systemclock" section: "3bobcat" platform: "linux" package: "libbobcat-dev" version: "6.07.01-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/systemclock" --- # systemclock(3bobcat) classes wrapping std::chrono::\*\_clock facilities ## NAME FBB::\*Clock - classes wrapping std::chrono::\*\_clock facilities ## SYNOPSIS **#include \**\ **#include \**\ **#include \**\ **#include \**\ Each of these files also includes the *std::chrono* header file. ## DESCRIPTION The **C++** *std::chrono* namespace defines clock-types and their operations. The **bobcat** *\*Clock* classes define wrappers around the four standard **C++** clock-types offering interfaces which are easier to handle than the standard *std::chrono* clocks. - o **FileClock** wraps *std::chrono::file\_clock*; - o **HighResolutionClock** wraps *std::chrono::high\_resolution\_clock*;\ - o **SteadyClock** wraps *std::chrono::steady\_clock*;\ - o **SystemClock** wraps *std::chrono::system\_clock*, and is the commonly used clock type. Member names of the **bobcat** clock-classes don’t use underscores. Names consisting of multiple words are \`camel-cased’ (like *timePoint*). Note: The type *std::chrono::file\_clock* (and therefore **FileClock**) is available since the *C++-2a* standard: specify the *--std=c++2a* (or more recent) compiler option when using **FileClock**. ## NAMESPACE **FBB**\ All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace **FBB**. ## INHERITS FROM *FBB::ClockTypes*\ *FBB::ClockBase*\ *FBB::HighSysClock*\ these are internally used only classes; their facilities are covered in this man-page. ## TYPEDEFS AND ENUMS - o The *std::chrono* types *nanoseconds, microseconds, milliseconds,* *seconds, minutes* and *hours* are also available in the namespace *FBB*; **Clock Types:** - o *FBB::FileClock* provides the *std::chrono::file\_clock* facilities; - - o *FBB::HighResolutionClock* provides the *std::chrono::high\_resolution\_clock* facilities; - - o *FBB::SteadyClock* provides the *std::chrono::steady\_clock* facilities; - - o *FBB::SystemClock* provides the *std::chrono::system\_clock* facilities. **Sub-types:** - o *Duration*: each clock type defines the type *Duration* as *std::chrono::duration\*; - - o *Period*: the sub-type *period* of the *Duration* type. In practice its subtypes *den (DenType)* and *num (NumType)* are used; - - o *DenType*: the denominator type of the *ratio* type used by the clock type (see also the static member *den*); - - o *NumType*: the numerator type of the *ratio* type used by the clock type (see also the static member *num*); ## CONSTRUCTORS The constructors are illustrated for *SystemClock* but are also available for the other clock types. - o **SystemClock(SystemClock::TimePoint = SystemClock::now())**:\ each clock-constructor can be initialized with a time point. By default the clock’s time point is initialized by the time point returned by the clock type’s static *now* member; - - o **SystemClock(Clock const &otherClock)**:\ each clock type can be initialized with another clock type object (except for a *SteadyClock* type object): when constructed they refer to the same points in time. Copy and move constructors (and assignment operators) are available. ## OVERLOADED OPERATORS Using *DurationType* to represent *std::chrono::duration\*, where *Ratio* is a *std::ratio* type (for clocks *Ratio* equals *nano*). - o **ClockType &operator+=(DurationType const &amount)**:\ adds *amount* to the current clock’s *TimePoint*. E.g., ``` SystemClock sc; sc += 1h; ``` - - o **ClockType &operator+=(int secs);**:\ adds *secs* seconds to the current clock’s *TimePoint*; - - o **ClockType &operator-=(DurationType const &amount);**:\ subtracts *amount* from the current clock’s *TimePoint*. Not available for *SteadyClock*; - - o **ClockType &operator-=(int secs);**:\ subtracts *secs* seconds from the current clock’s *TimePoint*; - - o **SteadyClock &operator-=(SteadyClock const &rhs)**:\ only available for class *SteadyClock*: *rhs.elapsed()* is subtracted from the current object’s time-point. See also the functions *since* and *countSince* below. - - o **std::ostream &operator\<\<(std::ostream &out, ClockType const &clock)**:\ not available for *SteadyClock*; *clock’s* (UTC) *TimePoint* is inserted into *out*. E.g., ``` cout << SystemClock{}; // could insert // 2025-01-04 08:25:10.035509381 ``` - - o **ClockType operator+(Type1 const &lhs, Type2 const &rhs)**:\ not available for *SteadyClock*. Either *Type1* or *Type2* must be an **FBB** Clock type (like *SystemClock*). The other type can either be an *int* (representing number of seconds) or a *DurationType* (like *seconds, hours*). A clock object of the same type as the *Clock* argument is returned, whose *TimePoint* is initialized to the sum of the argument’s *TimePoint* and the value of the other argument; - - o **ClockType operator-(ClockType const &lhs, Type const &rhs)**:\ both argument types can be *SteadyClock*. As *SteadyClock* objects are used for timing purposes this operator returns a *SteadyClock* object whose time specification is equal to the difference of the *lhs* and *rhs* time specifications (see also the functions *since* and *countSince* below).\ Otherwise the *lhs* argument must be an **FBB** Clock type (like *SystemClock*), and *Type* can either be an *int* (representing number of seconds) or a *DurationType* (like *seconds, hours*), returning a clock object whose *TimePoint* is initialized to the difference of the *lhs’s* *TimePoint* and the *rhs* value; ## FREE FUNCTIONS - o **auto toClock\(ClockType const &clock)**:\ returns the *DestClock::TimePoint* corresponding to the *TimePoint* of *clock*. It is not available for conversions from or to the *SteadyClock* type. E.g., ``` FileClock fc; cout << toClock(fc) << ’\n’; ``` - - o **double toDouble\(ClockType const &src)**:\ returns the *double* value corresponding to *ClockType’s* *std::chrono::duration* converted to the *Duration* *std::chrono::duration*. E.g., ``` toDouble(90min); // returns 1.5 ``` - - o **Dest toDuration(Src const &src)**:\ returns *src’s Duration* converted to the (at least as precise) *Dest* duration. E.g., ``` toDuration(1min).count(); // returns 60 ``` ## ADDITIONAL STEADYCLOCK FREE FUNCTIONS The *SteadyClock* type is primarily used for timing purposes. The following two functions are available for *SteadyClock* objects: - o **SteadyClock::Duration since(SteadyClock const &time0)**:\ The difference in nanoseconds (*Durations*) of a local *SteadyClock* object and *time0* is returned. E.g., ``` SteadyClock start; // do something cout << "Elapsed time: " << since(start) << ’\n’; ``` - - o **size\_t countSince(SteadyClock const &time0)**:\ Same as the previous function, but the number of nanoseconds are returned as a *size\_t* value. ## MEMBER FUNCTIONS All of the following members are available for each of **bobcat’s** clock types: - o **long int count()**:\ returns *timePoint’s value*. The clock types have members *timePoint()*: this member returns the number of nano seconds as an integral value since the beginning of the clock’s era. E.g., ``` FileClock{}.clock(); // returns, e.g., // -4701673791896351066 ``` - - o **static long int ClockTypes::count(TimePoint const &timePoint)**:\ returns *timePoint’s value*. This function can also be used for *SteadyClock* objects. E.g., ``` ClockTypes::count(SteadyClock::now()); // returns, e.g., // 8310904806233 ``` - - o **static DenType::den()**:\ returns the denominator of the *ratio* used by the clocks (= 1’000’000’000); - - o **Duration elapsed() const**:\ returns the *Duration* value of the current *Clock* object (= number of nano-seconds since the beginning of the clock’s era). E.g., ``` SystemClock{}.elapsed(); // returns, e.g., // 1735989478991599467ns ``` - - o **static Duration ClockTypes::elapsed(TimePoint const &timePoint)**:\ returns *timePoint’s Duration*. Clock types have members *timePoint()* returning the clock’s time point; - - o **static TimePoint max()**:\ returns the *TimePoint* of the used clock type corresponding to the clock’s maximum (UTC) time. E.g., ``` cout << SystemClock::max(); // inserts: // 2262-04-11 23:47:16... ``` - - o **static TimePoint min()**:\ returns the *TimePoint* of the used clock type corresponding to the clock’s minimum (UTC) time; - - o **static TimePoint now()**:\ returns the *TimePoint* of the used clock type corresponding to the current (UTC) time. E.g., ``` cout << SystemClock::now() << ’\n’; ``` - - o **static NumType::num()**:\ returns the numerator of the *ratio* used by the clocks (= 1); - - o **static Period period()**:\ returns the clock’s *Period* (having members *den* and *num*); - - o **TimePoint const &timePoint() const**:\ returns the object’s *TimePoint*; - - o **double toDouble\() const**:\ returns the *double* value corresponding to the object’s *std::chrono::duration* converted to the *Dest* *std::chrono::duration*. E.g., ``` SystemClock{}.toDouble(); // returns, e.g., 482221 ``` - - o **static Duration zero()**:\ returns the clock’s *Duration* representing 0 nanoseconds; ## ADDITIONAL SYSTEM / HIGHRESOLUTION CLOCK MEMBERS Primarily for displaying the clock’s time the *SystemClock* and *HighResolutionClock* classes support these members: - o **std::time\_t timeT() const**:\ returns the object’s *TimePoint* converted to *time\_t* (cf. [**time**(3)](/time/3.md)); - - o **Clock &setTime(std::time\_t seconds)**:\ returns the current object after resetting its *TimePoint* to its *time\_t* argument; - - o **Clock const &operator()(char const \*putTime,** **bool localTime = true) const**:\ prepares the current object for the next insertion operator, using the *putTime* specification to configure the *std::put\_time* manipulator (cf. *C++ Annotations*, section 6.4.4 (The \`put\_time’ manipulator)). By default the time is displayed using the local time. When the 2nd argument is *false* the time is displayed in *UTC*. When the current object is inserted into a *std::ostream* after calling this member the *put\_time* manipulator is used only once. By calling this member again *put\_time* is repeatedly used. E.g., ``` SystemClock sc; cout << // inserts, e.g., sc("%Y") << ’\n’ << // 2025 sc("%y") << ’\n’ << // 25 sc << ’\n’; // 2025-01-04 14:18:47... ``` ## EXAMPLE ``` #include #include #include #include #include #include #include using namespace std; using namespace FBB; int main() { SystemClock sysNow{ }; cout << "system clock at " << sysNow << "\n" "elapsed: " << sysNow.elapsed() << "\n\n"; // same timespec, elapsed ns. FileClock fileNow{ sysNow }; // is clock-specific cout << "file clock at " << fileNow << "\n" "elapsed: " << fileNow.elapsed() << "\n\n"; SystemClock sysNow2{ fileNow }; cout << "system clock at " << sysNow2 << "\n" "elapsed: " << sysNow2.elapsed() << "\n\n"; cout << sysNow2("%Y %b %d, %H:%M:%S") << "\n" "\n" "minimum time: " << sysNow2.min() << "\n" "maximum time: " << SystemClock::max() << "\n\n"; // conversion to less precise time specification: cout << "100 minutes is " << toDouble(100min) << " hours\n\n"; HighResolutionClock hrc{ fileNow }; cout << "high resolution clock at " << hrc << "\n\n"; SteadyClock sc0; // computing ’since’ itself takes several auto passed = since(sc0); // (variable) hundred nano seconds cout << "sc0 since: " << passed << ’\n’; SteadyClock sc; this_thread::sleep_for(1s); cout << "ELAPSED: " << since(sc) << ’\n’ << "(small delay...)\n" "as count: " << countSince(sc) << "\n\n"; } ``` ## FILES *bobcat/fileclock*, - the *FileClock* class interface\ *bobcat/highresulutionclock* - the *HighResolutionClock* class interface\ *bobcat/steadyclock* - the *SteadyClock* class interface\ *bobcat/systemclock* - the *SystemClock* class interface\ ## SEE ALSO [**bobcat**(7)](/bobcat/7.md), [**time**(3)](/time/3.md), ## BUGS None Reported. ## BOBCAT PROJECT FILES - o *https://fbb-git.gitlab.io/bobcat/*: gitlab project page; Debian Bobcat project files: - o *libbobcat6*: debian package containing the shared library, changelog and copyright note; - o *libbobcat-dev*: debian package containing the static library, headers, manual pages, and developer info; ## BOBCAT Bobcat is an acronym of \`Brokken’s Own Base Classes And Templates’. ## COPYRIGHT This is free software, distributed under the terms of the GNU General Public License (GPL). ## AUTHOR Frank B. Brokken (**f.b.brokken@rug.nl**).