detinfo::ElecClock Class Reference

Class representing the time measured by an electronics clock. More...

#include <ElecClock.h>

Public Member Functions
	ElecClock (double const time, double const frame_period, double const frequency)
	Constructor: sets all values. More...
constexpr ElecClock	WithTime (double const time) const noexcept
constexpr ElecClock	WithTick (int const tick, int const frame=0) const noexcept
constexpr ElecClock	AdvanceTimeBy (double const time) const noexcept
constexpr ElecClock	AdvanceTicksBy (int const ticks) const noexcept
constexpr double	Time () const noexcept
	Current time (as stored) in microseconds. More...
constexpr double	Time (int const sample, int const frame) const noexcept
	Returns the absolute time of the start of the specified sample. More...
constexpr double	Time (double const time) const noexcept
	Returns the discretized value of the specified time. More...
constexpr double	Time (int const ticks) const noexcept
	Returns the absolute start time of the specified tick. More...
constexpr double	Frequency () const
	Frequency in MHz. More...
constexpr double	FramePeriod () const noexcept
	A single frame period in microseconds. More...
constexpr int	Ticks () const noexcept
	Current clock tick (that is, the number of tick Time() falls in). More...
constexpr int	Ticks (double const time) const noexcept
	Returns the number of tick the specified time falls in. More...
constexpr int	Ticks (int const sample, int const frame) const noexcept
	Returns the number of tick the specified sample falls in. More...
constexpr int	Sample () const noexcept
	Returns number of the sample containing the clock current time. More...
constexpr int	Sample (double const time) const noexcept
	Returns the number of the sample containing the specified time. More...
constexpr int	Sample (int const tick) const noexcept
	Returns the number of the sample containing the specified tick. More...
constexpr int	Frame () const noexcept
	Returns the number of the frame containing the clock current time. More...
constexpr int	Frame (double const time) const noexcept
	Returns the number of the frame containing the specified time. More...
constexpr int	Frame (int const tick) const noexcept
	Returns the number of the frame containing the specified tick. More...
constexpr unsigned int	FrameTicks () const noexcept
	Number ticks in a frame. More...
constexpr double	TickPeriod () const noexcept
	A single tick period in microseconds. More...
constexpr bool	operator< (const ElecClock &rhs) const noexcept
constexpr bool	operator> (const ElecClock &rhs) const noexcept
constexpr bool	operator<= (const ElecClock &rhs) const noexcept
constexpr bool	operator>= (const ElecClock &rhs) const noexcept

Private Member Functions
constexpr	ElecClock (double const time, double const frame_period, double const frequency, std::nothrow_t) noexcept

Private Attributes
double	fTime {}
	Time in microseconds. More...
double	fFramePeriod {kTIME_MAX}
	Frame period in microseconds. More...
double	fFrequency {1e9}
	Clock speed in MHz. More...

Detailed Description

Class representing the time measured by an electronics clock.

This class represents the status of a running electronics clock. As such, it has:

• tick frequency: how many times the clock ticks in one second
• frame period: the duration of a single frame; clock time is organised into two levels:
  • the time is split into frames
  • each frame is split in samples; the first one of a each frame is sample number 0
• current time of the clock, with respect to the time (always "0") the clock was started at

Note that this object is actually able to manage any (continuous) value of time, and the concepts of frame and sample are not used to store the clock state, which is instead defined by its current time.

All these quantities are stored in real time units as opposed to clock tick counts. The nominal units for all times and frequencies are microseconds and megahertz, respectively, but ElecClock will give consistent results as long as the units of frame period and time are the same, and reciprocal to the frequency unit.

The clock can update its time directly (SetTime()) or through operators.

The clock started at time 0, with the sample 0 of the frame 0 (that is also tick 0). This implies that all times and ticks returned by the clock implicitly have the same reference as the input time specified by the constructors or by the last call to SetTime().

Some usage examples:

// get a clock with a period of 500 ns (2 MHz) and a frame of 1.6 ms
detinfo::ElecClock clock(0.0, 1600.0, 2.0);

std::cout << "New clock:"
  << "\n  current time:      " << clock.Time()       // 0.0 us
  << "\n  samples per frame: " << clock.FrameTicks() // 3200
  << std::endl;

clock.SetTime(1, 20); // sets the time to sample #20 of frame 1
std::cout << "Time set to sample #20 of frame #1:"
  << "\n  current time: " << clock.Time()  // 1610.0 us
  << "\n  current tick: " << clock.Tick()  // 3220
  << std::endl;

clock += 3.7; // add 3.7 us to the current time
std::cout << "Added 3.7 microseconds:"
  << "\n  current time:  " << clock.Time()       // 1613.7 us
  << "\n  current tick:  " << clock.Tick()       // 3227
  << "\n  discrete time: " << clock.Time(Time()) // 1613.5 us
  << std::endl;

clock += 3; // add 3 more ticks (1.5 us) to the current time
std::cout << "Added 3 ticks:"
  << "\n  current time:  " << clock.Time()       // 1615.2 us
  << "\n  current tick:  " << clock.Tick()       // 3230
  << "\n  discrete time: " << clock.Time(Time()) // 1615.0 us
  << std::endl;

Note

Most methods and operators have different behaviour according to whether their argument is of type double, in which case it is interpreted as a time, or int, where it is interpreted as a clock tick. Be especially careful when utilizing data types which are neither int not double, because a conversion to one of them will occur, and you need to be in control of which one.

Definition at line 91 of file ElecClock.h.

Constructor & Destructor Documentation

detinfo::ElecClock::ElecClock ( double const  time, double const  frame_period, double const  frequency  )

inline

Constructor: sets all values.

Parameters

time	starting time of the clock [s]
frame_period	period of the clock [s]
frequency	clock frequency [MHz]

Definition at line 100 of file ElecClock.h.

      : ElecClock{time, frame_period, frequency, std::nothrow}
    {
      if (fFrequency <= 0)
        throw detinfo::DetectorClocksException("Only positive frequency allowed.");
    }

constexpr detinfo::ElecClock::ElecClock ( double const  time, double const  frame_period, double const  frequency, std::nothrow_t    )

inlineprivatenoexcept

Definition at line 381 of file ElecClock.h.

      : fTime(time), fFramePeriod(frame_period), fFrequency(frequency)
    {}

Member Function Documentation

constexpr ElecClock detinfo::ElecClock::AdvanceTicksBy ( int const  ticks ) const

inlinenoexcept

Definition at line 126 of file ElecClock.h.

    {
      return {fTime + Time(ticks), fFramePeriod, fFrequency, std::nothrow};
    }

constexpr ElecClock detinfo::ElecClock::AdvanceTimeBy ( double const  time ) const

inlinenoexcept

Definition at line 120 of file ElecClock.h.

    {
      return {fTime + time, fFramePeriod, fFrequency, std::nothrow};
    }

constexpr int detinfo::ElecClock::Frame ( ) const

inlinenoexcept

Returns the number of the frame containing the clock current time.

See Also

Frame(double)

The returned value is the number of the frame which the current clock time falls in.

Definition at line 304 of file ElecClock.h.

    {
      return Frame(fTime);
    }

constexpr int detinfo::ElecClock::Frame ( double const  time ) const

inlinenoexcept

Returns the number of the frame containing the specified time.

Parameters

time	a clock time [s]

Returns

number of the frame containing the specified time

See Also

Sample(double)

The returned value is the number of the frame which the specified time falls in.

The result is not related to the current time of the clock.

Definition at line 321 of file ElecClock.h.

    {
      return static_cast<int>(time / fFramePeriod);
    }

constexpr int detinfo::ElecClock::Frame ( int const  tick ) const

inlinenoexcept

Returns the number of the frame containing the specified tick.

Parameters

tick	a clock tick number

Returns

number of the frame containing the specified tick

See Also

Frame(int)

The returned value is the number of the frame the specified tick belongs to.

The result is not related to the current time of the clock.

Definition at line 338 of file ElecClock.h.

    {
      return (tick / static_cast<int>(FrameTicks()));
    }

constexpr double detinfo::ElecClock::FramePeriod ( ) const

inlinenoexcept

A single frame period in microseconds.

Definition at line 198 of file ElecClock.h.

    {
      return fFramePeriod;
    }

constexpr unsigned int detinfo::ElecClock::FrameTicks ( ) const

inlinenoexcept

Number ticks in a frame.

Definition at line 345 of file ElecClock.h.

    {
      return static_cast<unsigned int>(fFramePeriod * fFrequency);
    }

constexpr double detinfo::ElecClock::Frequency ( ) const

inline

Frequency in MHz.

Definition at line 191 of file ElecClock.h.

    {
      return fFrequency;
    }

constexpr bool detinfo::ElecClock::operator< ( const ElecClock &  rhs ) const

inlinenoexcept

Definition at line 360 of file ElecClock.h.

    {
      return fTime < rhs.Time();
    }

constexpr bool detinfo::ElecClock::operator<= ( const ElecClock &  rhs ) const

inlinenoexcept

Definition at line 370 of file ElecClock.h.

    {
      return fTime <= rhs.Time();
    }

constexpr bool detinfo::ElecClock::operator> ( const ElecClock &  rhs ) const

inlinenoexcept

Definition at line 365 of file ElecClock.h.

    {
      return fTime > rhs.Time();
    }

constexpr bool detinfo::ElecClock::operator>= ( const ElecClock &  rhs ) const

inlinenoexcept

Definition at line 375 of file ElecClock.h.

    {
      return fTime >= rhs.Time();
    }

constexpr int detinfo::ElecClock::Sample ( ) const

inlinenoexcept

Returns number of the sample containing the clock current time.

See Also

Sample(double)

The returned value is the number of the sample within a frame, which the current clock time falls in. The number of the frame is not returned. To univocally define the sample, the number of the frame must also be obtained, e.g. via Frame().

Definition at line 253 of file ElecClock.h.

    {
      return Sample(fTime);
    }

constexpr int detinfo::ElecClock::Sample ( double const  time ) const

inlinenoexcept

Returns the number of the sample containing the specified time.

Parameters

time	a clock time [s]

Returns

number of the sample containing the specified time

See Also

Frame(double)

The returned value is the number of the sample within a frame, which the specified time falls in. The number of the frame is not returned. To univocally define the sample, the number of the frame must also be obtained, e.g. via Frame(double).

The result is not related to the current time of the clock.

Definition at line 272 of file ElecClock.h.

    {
      return static_cast<int>((time - Frame(time) * fFramePeriod) * fFrequency);
    }

constexpr int detinfo::ElecClock::Sample ( int const  tick ) const

inlinenoexcept

Returns the number of the sample containing the specified tick.

Parameters

tick	a clock tick number

Returns

number of the sample containing the specified tick

See Also

Frame(int)

The returned value is the number of the sample within a frame, of the specified tick. The number of the frame is not returned. To univocally define the sample, the number of the frame must also be obtained, e.g. via Frame(int).

The result is not related to the current time of the clock.

Definition at line 291 of file ElecClock.h.

    {
      return (tick % static_cast<int>(FrameTicks()));
    }

constexpr double detinfo::ElecClock::TickPeriod ( ) const

inlinenoexcept

A single tick period in microseconds.

Definition at line 352 of file ElecClock.h.

    {
      return 1. / fFrequency;
    }

constexpr int detinfo::ElecClock::Ticks ( ) const

inlinenoexcept

Current clock tick (that is, the number of tick Time() falls in).

Definition at line 205 of file ElecClock.h.

    {
      return Ticks(fTime);
    }

constexpr int detinfo::ElecClock::Ticks ( double const  time ) const

inlinenoexcept

Returns the number of tick the specified time falls in.

Parameters

time	time to be converted in ticks [s]

Returns

the number of the tick containing the specified time

The tick number 0 starts at time 0.0 s.

Note

The returned value (number of tick) can wrap if the real number of the tick is beyond the range of the returned data type (int).

Definition at line 221 of file ElecClock.h.

    {
      return static_cast<int>(time * fFrequency);
    }

constexpr int detinfo::ElecClock::Ticks ( int const  sample, int const  frame  ) const

inlinenoexcept

Returns the number of tick the specified sample falls in.

Parameters

sample	number of sample in the specified frame
frame	number of frame the specified sample is in

Returns

the number of the tick containing the specified sample

The sample 0 of frame 0 is the tick number 0.

Note

The returned value (number of tick) can wrap if the real number of the tick is beyond the range of the returned data type (int).

Definition at line 238 of file ElecClock.h.

    {
      return sample + frame * FrameTicks();
    }

constexpr double detinfo::ElecClock::Time ( ) const

inlinenoexcept

Current time (as stored) in microseconds.

Note that this is different than Time(Time()), which is discretized.

Definition at line 137 of file ElecClock.h.

    {
      return fTime;
    }

constexpr double detinfo::ElecClock::Time ( int const  sample, int const  frame  ) const

inlinenoexcept

Returns the absolute time of the start of the specified sample.

Parameters

sample	sample number within the specified frame
frame	number of the frame the specified sample is in

Returns

time [us] corresponding to the start of the specified sample

The sample number is not checked to be actually within the specified frame.

The returned time is not related to the current time of the clock.

Definition at line 154 of file ElecClock.h.

    {
      return (sample / fFrequency + frame * fFramePeriod);
    }

constexpr double detinfo::ElecClock::Time ( double const  time ) const

inlinenoexcept

Returns the discretized value of the specified time.

Parameters

time	a clock time [s]

Returns

discretized time [s] (as a floating point number)

The returned time is the start time of the sample time falls in.

It is not related to the current time of the clock.

Definition at line 169 of file ElecClock.h.

    {
      return Time(Sample(time), Frame(time));
    }

constexpr double detinfo::ElecClock::Time ( int const  ticks ) const

inlinenoexcept

Returns the absolute start time of the specified tick.

Parameters

ticks

a clock time [s]

Returns

discretized time [s] (as a floating point number)

The returned time is the start time of the tick which time falls in.

It is not related to the current time of the clock.

Definition at line 184 of file ElecClock.h.

    {
      return ticks / fFrequency;
    }

constexpr ElecClock detinfo::ElecClock::WithTick ( int const  tick, int const  frame = 0  ) const

inlinenoexcept

Definition at line 114 of file ElecClock.h.

    {
      return {Time(tick, frame), fFramePeriod, fFrequency, std::nothrow};
    }

constexpr ElecClock detinfo::ElecClock::WithTime ( double const  time ) const

inlinenoexcept

Definition at line 108 of file ElecClock.h.

    {
      return {time, fFramePeriod, fFrequency, std::nothrow};
    }

Member Data Documentation

double detinfo::ElecClock::fFramePeriod {kTIME_MAX}

private

Frame period in microseconds.

Definition at line 389 of file ElecClock.h.

double detinfo::ElecClock::fFrequency {1e9}

private

Clock speed in MHz.

Definition at line 390 of file ElecClock.h.

double detinfo::ElecClock::fTime {}

private

Time in microseconds.

Definition at line 388 of file ElecClock.h.

---

The documentation for this class was generated from the following file:

• ElecClock.h