Code

Source code is available here

Documentation

User documentation can be found here

Description

This project aims to ease the use of clock in complex environments, especially distributed environments where latencies measurement has to be precise and reproductible when running unit tests. PhoenixClock provide PGenericClock, a template classe which takes two arguments : - The main clock backend (could be clock, PClockNs for nanoseconds, etc) - A mock of a clock, PClockMock, which can play, register and replay a sequence of clock calls

These clocks are activated with a mode PClockMode::PClockMode which can be : - PClockMode::NO_MOCK : for a normal usage - PClockMode::MOCK : when the mock the desired clock is played - PClockMode::MOCK_RECORD : when the real clock backend is used but the clock mock is recording (could be usefull for debugging or to desing new unit tests quickly)

#include "phoenix_clock.h"

...
///Example of PGenericClock usage
void callingClock(){
    PGenericClock<PClockBackend, PClockMock> myClock;
    //Let's use the normal mode
    myClock.setMode(PClockMode::NO_MOCK);
    //We can get the current time with
    clock.now();    //Returns a time_t such as clock()

    //Once we have a mock file 'clock.clockmock',
    //we can replay it with the same API
    myClock.setMode(PClockMode::MOCK);
    clock.now();    //Returns a time_t such as clock(),
    //but this time, it is from the recorded times in the mock

    //Let's have an example of the recording
    myClock.setMode(PClockMode::MOCK_RECORD);
    clock.now();    //Returns a time_t such as clock(),
    //but this time, it is from the real clock backend but is
    //recorded at the same time in the mock
}

Requirements

c++ compiler (tested with g++ 11,12,13,14,15 and clang 14)
PhoenixCMake
cmake > 3
make

Installation for Users

Install packages using pixi conda manager

Each Phoenix package is packaged using pixi, a modern and fast conda package manager. Pixi simplifies environment management and installation, ensuring reproducible builds and easy dependency handling. Phoenix packages are hosted on prefix.dev, with two dedicated channels: - phoenix for stable releases. - phoenix-dev for development packages. These packages are build from the latest developments in the Phoenix projects, they can be deleted at any moment. Using pixi is recommended for people that get started using or developing Phoenix packages. It will speed up your setup, handle the dependencies resolution and updates, and allow you to use the tasks defined for common development operations (run test, build doc, etc.)

To install the package in a globally accessible location and exposes its command line applications:

pixi global install -c conda-forge -c https://prefix.dev/phoenix phoenixclock

Using this command you can specify : - the channel where the package is located: https://prefix.dev/phoenix - the version you want to install, for instance "phoenixclock==0.8.0"

To use this library as a dependency in your own pixi projects, you must add the dependency into your workspace. First, add the Phoenix channel into your workspace:

[workspace]
channels = [
    "https://prefix.dev/phoenix"
]

then add the dependency on the library. For instance to add the library in your default environment:

pixi add phoenixclock

Install from sources using pixi

To develop the library using a pixi installation, download the sources and then you will be able to run tasks define in the pixi.toml file using pixi:

git clone https://gitlab.in2p3.fr/CTA-LAPP/PHOENIX_LIBS2/PhoenixClock.git
cd PhoenixClock
pixi install -a 
pixi run test # task defined in the pixi.toml used to run the tests

The basic available tasks in the pixi.toml are : | | Objective | Inputs | Outputs | |-----------------------|:-----------------------------------------------------:|:----------------------------------------------------------:|:-------------------:| | pixi run test | Run the tests of the current package | - | - | | pixi run coverage | Generate the coverage report of the current project. | Output folder for coverage reports. Default is coverage | coverage folder | | pixi run doc | Generate documentation of the current project | docDir Output folder for documentation | docDir folder |

Install from sources

git clone https://gitlab.in2p3.fr/CTA-LAPP/PHOENIX_LIBS2/clock/PhoenixClock.git
cd PhoenixClock
./install.sh

Then PhoenixClock is installed in your $HOME/usr.

If you prefer a customized install path you can do :

git clone https://gitlab.in2p3.fr/CTA-LAPP/PHOENIX_LIBS2/clock/PhoenixClock.git
cd PhoenixClock
./install.sh /your/install/path

If you prefer a customized install path with custom compilation you can do :

git clone https://gitlab.in2p3.fr/CTA-LAPP/PHOENIX_LIBS2/clock/PhoenixClock.git
cd PhoenixClock
mkdir -p build
cd build
cmake .. $(phoenixcmake-config --cmake)
make -j `nproc`
make install -j `nproc`

The nproc gives the number of cores of the computer. If you want a build on one core you can just type :

make
make install

Update PhoenixClock

If you want to update the software :

git clone https://gitlab.in2p3.fr/CTA-LAPP/PHOENIX_LIBS2/clock/PhoenixClock.git
cd PhoenixClock
./update.sh

If you want to update the software with a custom install path :

git clone https://gitlab.in2p3.fr/CTA-LAPP/PHOENIX_LIBS2/clock/PhoenixClock.git
cd PhoenixClock
./update.sh /your/install/path