Classes

srs

srs::App

class App

The primary interface class of SRS-Control.

Application class should be instantiated only once during the whole program. Public setter methods should be called before calling the init() method.

Public Functions

App(Config config)

Constructor of the App class.

The constructor contains following actions:

  1. Instantiation of the work guard, which make sure the io_context_ keep accepting new tasks.

  2. Instantiation of strand from the io_context_, which synchronizes the communications among the FECs.

  3. Set the logging format.

  4. Instantiation (memory allocation) of workflow_handler_.

~App() noexcept

Destructor of the App class.

This destructor is called before the destruction of each members. The destructor contains following actions:

  1. Cancel the signal_set_.

  2. Wait for the Status::is_reading to be false, which will be unset from connection::DataReader::close(). The waiting time is set to be common::DEFAULT_STATUS_WAITING_TIME_SECONDS.

  3. Requesting acquisition off to all FEC devices.

  4. Set the Status::is_acq_on to be true.

The exit process of App class also contains the destruction of its member variables. The following order must be kept:

  1. Destruction of connection::DataReader member.

  2. Destruction of workflow::Handler member.

  3. Destruction of internal::AppExitHelper member, which calls end_of_work method.

  4. Destruction of working_thread_ (std::jthread) by waiting for the thread to finish.

  5. Destruction other members. Orders are not important.

  6. Destruction of io_context member. This must be done in the very end.

void init()

Initialization of internal members.

void switch_on()

Establish the communications to the available FECs to start the data acquisition.

void switch_off()

Establish the communications to the available FECs to stop the data acquisition.

void read_data(bool is_non_stop = true)

Start reading the input data stream from the port specified by srs::Config::fec_data_receive_port. If is_non_stop is true, the reading process will not be stopped until an interrupt happens, such as pressing “Ctrl-C” from users. If is_non_stop is false, the reading process will be stopped after one frame of data is read.

Parameters:

is_non_stop – Flag to set non-stop mode.

void start_workflow()

Start data analysis workflow, triggering data conversions.

This function call is executed in the main thread.

inline void wait_for_workflow()

Wait for the workflow process to finish.

inline void set_fec_data_receiv_ports(const std::vector<int> &port_nums)

Set the local listen port numbers for the communications to FEC devices.

inline void add_fec_data_receiv_port(int port_num)

Add a local listen port number for the communications to FEC devices.

void set_print_mode(common::DataPrintMode mode)

Set the print mode.

void set_output_filenames(const std::vector<std::string> &filenames, std::size_t n_lines = 1)

Set the output filenames.

inline void set_options(Config options)

Set the configuration values.

inline void set_runtime_sec(std::size_t runtime_sec)

Set the runtime in seconds.

Private Members

io_context_type io_context_ = {4}

Asio io_context that manages the task scheduling and network IO.

std::size_t runtime_sec_ = {}

Time duration (seconds) to stop the application. If value is zero, the application is in non-stop mode and must be stopped by pressing Ctrl-C.

asio::executor_work_guard<io_context_type::executor_type> io_work_guard_

Asio io_context work guard.

std::vector<udp::endpoint> remote_fec_endpoints_

Remote endpoints of FEC devices.

asio::signal_set signal_set_ = {io_context_, SIGINT, SIGTERM}

User signal handler for interrupts.

asio::steady_timer cancel_timer_ = {io_context_}

Cancelling timer.

asio::strand<io_context_type::executor_type> fec_strand_

FEC communication strand for synchronous communications.

std::jthread working_thread_

Main working thread.

std::jthread workflow_thread_

Main thread to run workflow.

internal::AppExitHelper exit_helper_ = {this}

Exit helper for App class. This is called after calling the destructor.

std::unique_ptr<workflow::AnalysisHandle> workflow_handler_

The handler to the analysis working flow.

std::vector<std::shared_ptr<connection::DataSocket>> data_sockets_

Communication to the main input data stream.

srs::Config

class Config

Main configuration struct.

Public Members

int fec_control_local_port = common::FEC_CONTROL_LOCAL_PORT

The port number of the local network that is used for the communication to FECs.

int fec_control_remote_port = common::DEFAULT_SRS_CONTROL_PORT

The port number of the remote network that is used for the communication to FECs.

std::vector<int> fec_data_receive_ports = common::FEC_DAQ_RECEIVE_PORT

The port number of the local network that is used for reading the data stream from FECs.

std::size_t data_buffer_size = common::LARGE_READ_MSG_BUFFER_SIZE

The size of data buffer to store the incoming UDP frames.

std::vector<std::string> remote_fec_ips = {std::string{common::DEFAULT_SRS_IP}}

Remote IP addresses of FECs.

std::size_t buffer_queue_capacity = common::DEFAULT_DATA_QUEUE_SIZE

Capacity of the buffer queue.

std::vector<std::string> output_filenames

Output file names.

std::size_t output_split = 1

Number of splits from the input data to multiple outputs.

std::size_t time_wait_after_acq_off_ms = 1000

time (milliseconds) to wait after turning off the srs and before stopping data reading

bool enable_frame_counter_check = false

Enable frame counter checking to detect frame drop.

bool warn_if_data_drop = false

Enable warnings when possible data drop occurs.

bool show_thread_id = false

Show thread ID from console printouts.

common::DataPrintMode data_print_mode = srs::common::DataPrintMode::print_speed

Set print mode.

srs::BufferQueue

class BufferQueue

Class to manage the production and consumption of LargeBuffer asynchronously.

A BufferQueue contains two subqueues, implemented by the third party library. The first subqueue, called “valid_buffer_queue”, stores the incoming buffer read the UDP socket, ready to be consumed by the analysis taskflow. The second subqueue, called “trash_buffer_queue” stores the already analyzed buffer from the taskflow, which can be given back to the UDP socket to read further UDP message.

Public Types

using Token = std::pair<moodycamel::ProducerToken, moodycamel::ConsumerToken>

A queue token type used for enqueue and dequeue action. The token type consists of one producer token and one consumer token.

Public Functions

BufferQueue(const Config &config)

Default constructor.

Parameters:

config – Config object

void enqueue_empty(std::size_t bulk_size)

Abort the blocking operation from BufferQueue::pop().

See also

BufferQueue::pop

bool enqueue(LargeBuffer &element, Token &token)

Try to first push a buffer into the valid buffer queue and then replace it with a buffer from the trash buffer queue.

Parameters:

element – The buffer object to be pushed and replaced.

Returns:

True if the pushing succeeds.

void dequeue(LargeBuffer &element, Token &token)

Blocking the current thread by first pushing the element to the trash buffer queue and then replacing it with a buffer from the valid buffer queue.

Parameters:

element – The buffer object to be pushed and replaced.

inline auto size() const

Get the current size in the valid buffer queue.

The size of the valid buffer queue means the number of buffers pushed to the queue.

Returns:

Size of the buffer queue.

inline auto capacity() const

Get the current capacity of the buffer queue.

The capacity represents the maximum number of buffers that can be pushed to the valid buffer queue.

Returns:

Capacity

inline const auto &get_config() const

Getter of the config object.

See also

ref

Returns:

Const reference to the config object.

inline Token get_producer_token()

Get a queue token for a producer. The first value is the producer token for the valid_buffer_queue_ and the second value is the consumer token for the trash_buffer_queue_.

inline Token get_consumer_token()

Get a queue token for a consumer. The first value is the producer token for the trash_buffer_queue_ and the second value is the consumer token for the valid_buffer_queue_.

struct Config

Configuration for the buffer queue class.

Public Members

std::size_t buffer_size = common::LARGE_READ_MSG_BUFFER_SIZE

< The size of each buffer in the buffer queue.

std::size_t reserve_size = 1

The number of buffers to be preallocated in the trash buffer queue.

std::size_t queue_capacity = 10

The maximum number of buffers in both buffer queues.

srs::LargeBuffer

class LargeBuffer

Class for buffer for storing large data.

It has two different length indicators: size and buffer size (capacity). Similar to std::vector, size represents the current amount of valid values and buffer size represents the memory allocated for the buffer. The reason to use LargeBuffer instead of simply std::vector is because the std::vector::resize() also initialize the values when vector grows, while LargeBuffer::resize() just change the size value, without furthering operations. The LargeBuffer is not supposed to grow or reallocated and all the memory should be allocated up front via the constructor LargeBuffer(std::size_t).

Public Functions

LargeBuffer() = default

Default constructor for an empty buffer. This does not allocate any memory.

inline explicit LargeBuffer(std::size_t buffer_size)

Constructor with a buffer size.

The number of the elements pre-allocated is equal to the buffer_size.

Parameters:

buffer_size – Number of element whose memory pre-allocated to the buffer.

explicit LargeBuffer(const LargeBuffer &other) = delete

Default copy constructor. Very slow and should be avoided.

explicit LargeBuffer(LargeBuffer &&other) noexcept = default

Move constructor via swapping.

This “move” constructor does not move the data of the other, but rather perform the swap action with other object.

Parameters:

other – Other LargeBuffer object to be swapped.

LargeBuffer &operator=(const LargeBuffer &other) = delete

Default copy assignment. Very slow and should be avoided.

LargeBuffer &operator=(LargeBuffer &&other) noexcept = default

Move assignment via swapping.

This “move” assignment does not move the data of the other, but rather perform the swap action with other object.

Parameters:

other – Other LargeBuffer object to be swapped.

~LargeBuffer() = default

Default destructor.

inline bool operator==(std::span<char> msg) const

Comparison with a span.

Parameters:

msg – Span data.

Returns:

True if equal

inline bool operator==(std::string_view msg) const

Comparison with a string_view.

Parameters:

msg – string_view data.

Returns:

True if equal

inline std::string_view data() const

Return a string_view with the underlying data and current size.

Returns:

string_view data

inline void resize(std::size_t size)

Change the size of this buffer.

Changing the size to the new size value, without assigning or changing the old data values.

Parameters:

size – New size value.

inline std::size_t get_buffer_size() const

Getter for the buffer size.

Returns:

Buffer size

inline std::size_t get_size() const

Getter for the size.

Returns:

Size of elements in the buffer

inline std::span<char> get_all_data()

Return the total underlying data.

Returns:

Span of the underlying data.

connection

srs::connection::SpecialSocket

class SpecialSocket : public std::enable_shared_from_this<SpecialSocket>

Base socket class for sending and listening messages.

Subclassed by srs::connection::DataSocket, srs::connection::FecCommandSocket

Public Functions

void register_send_action (this auto &&self, asio::awaitable< void > action, const std::shared_ptr< typename std::remove_cvref_t< decltype(self)>::ConnectionType > &connection)

Registering the send action.

Invoke an action corresponding the type of connection specified in the socket class. The connection type should all derive from srs::connection::ConnectionBase class.

Parameters:
  • self – Deduce this self reference

  • action – An asio::awaitable action object.

  • connection – A connection shared pointer.

void listen (this auto &self, io_context_type &io_context)

Listen to any UDP data.

Parameters:
  • self – Deduce this self reference

  • io_context – Reference to the io_context

std::future< void > cancel_listen_after (this auto &&self, io_context_type &io_context, std::chrono::seconds waiting_time=std::chrono::seconds(2))

Cancelling the listening action after a certain time.

Parameters:
  • self – Deduce this self reference

  • io_context – Reference to the io_context

  • waiting_time – Time until the listen action is cancelled.

Returns:

a future object to check whether the listen action is cancelled.

std::optional<std::future_status> wait_for_listen_finish(std::chrono::seconds time)

Blocking the current thread by waiting the listen action to finish until a certain time duration.

Parameters:

time – Time to wait for the listen action to finish.

Returns:

The result of waiting.

inline udp::socket &get_socket() const

Getter for the asio udp socket object.

Returns:

shared pointer to the udp socket.

inline int get_port() const

Getter for the port number.

Returns:

Port number.

inline auto &get_future()

Getter for the status of the listen action.

Returns:

The future status of the listen action coroutine.

inline std::size_t get_n_records() const

Getter for the number of frames read.

Returns:

Number of frames read.

inline std::size_t get_n_bytes() const

Getter for the number of bytes read.

Returns:

Number of bytes read.

inline std::uint64_t get_total_time_ns() const

Getter for the total listening time in nano seconds.

Returns:

Total listening time.

Protected Functions

explicit SpecialSocket(int port_number, io_context_type &io_context)

Projected constructor, which can only be called from the derived classes.

Parameters:
  • port_numer – Port number binding to the socket for the listening action.

  • io_context – asio io context.

Private Members

asio::system_timer cancel_timer_

Used for cancel the unfinished coroutine.

srs::connection::DataSocket

class DataSocket : public srs::connection::SpecialSocket

Socket class for reading main data stream.

Public Functions

void cancel()

Cancel reading the data from the UDP socket.

srs::connection::Stopper

class Stopper : public srs::connection::CommandBase

Public Functions

Stopper(const Stopper&) = delete

Deleted copy constructor (rule of 5).

Stopper(Stopper&&) = delete

Deleted move constructor (rule of 5).

Stopper &operator=(const Stopper&) = delete

Deleted copy assignment operator (rule of 5).

Stopper &operator=(Stopper&&) = delete

Deleted move assignment operator (rule of 5).

explicit Stopper(std::string_view name)

Constructor for Stopper connection class.

Parameters:

name – Name of the command

~Stopper() = default

Destructor for Stopper connection class.

The destructor change the Status::is_acq_off to be true

See also

Status

workflow

srs::workflow::TaskDiagram

class TaskDiagram

Class for analysis taskflow.

Public Functions

explicit TaskDiagram(AnalysisHandle &data_processor, std::size_t n_lines = 1)

Constructor with number of pipelines.

Parameters:
  • data_processor – Pointer to srs::workflow::Handler

  • n_lines – Number of pipelines

void construct_taskflow_and_run(BufferQueue &data_queue, const std::atomic<bool> &is_stopped)

Run the taskflow and block the current thread until finished.

internal

srs::internal::AppExitHelper

class AppExitHelper

An internal exit helper for App class.

Public Functions

inline explicit AppExitHelper(App *app)

Constructor with pointer to srs::App instance.

~AppExitHelper() noexcept

Destructor calling srs::App::end_of_work method.