NAME

FBB::*Clock - classes wrapping std::chrono::*_clock facilities

SYNOPSIS

#include <bobcat/fileclock>
#include <bobcat/highresolutionclock>
#include <bobcat/steadyclock>
#include <bobcat/systemclock>

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:

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

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<int64_t, std::nano>;

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<int64_t, Ratio>, 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<DestClock>(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<SystemClock>(fc) << ’\n’;


 

o

double toDouble<Duration>(ClockType const &src):
returns the double value corresponding to ClockType’s std::chrono::duration converted to the Duration std::chrono::duration. E.g.,

    


    toDouble<hours>(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<seconds>(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<Dest>() const:
returns the double value corresponding to the object’s std::chrono::duration converted to the Dest std::chrono::duration. E.g.,

    SystemClock{}.toDouble<hours>(); // 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));

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 <iostream>
#include <string>
#include <thread>
#include <bobcat/fileclock> 
#include <bobcat/highresolutionclock> 
#include <bobcat/steadyclock> 
#include <bobcat/systemclock> 
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<hours>(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), time(3),

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).