==================
TimeTagger Classes
==================

The Time Tagger classes represent the different time-tag sources for your measurements and analysis.
These objects are created by factory functions in the :ref:`Time Tagger library <time-tagger-library-functions>`:

    Time Tagger
        The :cpp:class:`TimeTagger` represents a hardware device and allows access to hardware settings.
        To connect to a hardware Time Tagger and to get a :cpp:class:`TimeTagger` object, use :cpp:func:`createTimeTagger`.
    Virtual Time Tagger
        The :cpp:class:`TimeTaggerVirtual` allows replaying files created with the :cpp:class:`FileWriter`.
        To create a :cpp:class:`TimeTaggerVirtual` object, use :cpp:func:`createTimeTaggerVirtual`.
    Network Time Tagger
        The :cpp:class:`TimeTaggerNetwork` allows the (remote) access to a Time Tagger made available via :cpp:func:`~TimeTagger::startServer`.
        The :cpp:class:`TimeTaggerNetwork` object is created with :cpp:func:`createTimeTaggerNetwork` which also establishes a client connection to the server.

All these objects share a common interface defined by the :cpp:class:`TimeTaggerBase` and :cpp:class:`TimeTaggerSource` classes.
In addition, hardware-specific methods, for use with :cpp:class:`TimeTagger` and :cpp:class:`TimeTaggerNetwork` objects, are defined in the :cpp:class:`TimeTaggerHardware` class.

General Time Tagger features
----------------------------

.. doxygenclass:: TimeTaggerSource

.. py:class:: TimeTaggerBase
    :no-typesetting:

.. doxygenclass:: TimeTaggerBase


Time Tagger
--------------------

.. doxygenclass:: TimeTaggerHardware

.. doxygenclass:: TimeTagger

.. _time-tagger-virtual:

The TimeTaggerVirtual class
---------------------------

.. doxygenclass:: TimeTaggerVirtual


.. _time-tagger-network:

The TimeTaggerNetwork class
---------------------------

The *Network Time Tagger* enables sending the time-tag stream to other applications and even remote computers for independent processing.
You can use it with any Time Tagger hardware device by starting the time-tag stream server with :cpp:func:`~TimeTagger::startServer()`.
Once the server is running, the clients can connect to it by calling :cpp:func:`createTimeTaggerNetwork` and specifying the server address.
Starting with version 2.18, a `TimeTaggerNetwork` client can connect to multiple servers and merge their time tag streams,
provided the servers are synchronized (e.g. using the White Rabbit protocol).
Once the servers are running, the clients can connect to them by calling :cpp:func:`createTimeTaggerNetwork` and specifying the servers addresses.
A client can be any computer that can access the servers over the network or another process on the same computer.
Servers and clients can run on different operating systems or use different programming languages.

.. admonition:: Note on Performance

    The Network Time Tagger server sends a time-tag stream in a compressed format requiring about 4 bytes per time tag.
    Every client receives the data only from the channels required by the client.
    The maximum achievable data rate will depend on multiple factors, like server and client CPU performance, operating system,
    network adapter used, and network bandwidth, as well as the whole network infrastructure.

    In a 1 Gbps Ethernet network, it is possible to achieve about 26 MTags/second of the total outgoing data rate from the server.
    Note that this bandwidth is shared among all clients connected.
    Likewise, a 10 Gbps Ethernet network allows reaching higher data rates while having more clients.
    In our tests, we reached up to 40 MTags/s per client.

    When you run the server and the client on the same computer, the speed of the network adapters installed on your system becomes irrelevant.
    In this case, the operating system sends the data directly from the server to the client.


.. doxygenclass:: TimeTaggerNetwork


The :cpp:class:`TimeTaggerServer` class contains all relevant control methods present in :cpp:class:`TimeTaggerBase` and :cpp:class:`TimeTaggerHardware`.

:cpp:class:`TimeTaggerServer` objects allow control of a TimeTagger in server mode, provided has been created with :cpp:enumerator:`AccessMode::Control` privileges.
However, unlike :cpp:class:`TimeTaggerBase`, :cpp:class:`TimeTaggerServer` cannot be used to perform measurements.
    
.. doxygenclass:: TimeTaggerServer

Additional classes
------------------

.. doxygenstruct:: ReferenceClockState

.. doxygenstruct:: SoftwareClockState


