Roc Toolkit internal modules
Roc Toolkit: real-time audio streaming
watchdog.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2018 Roc Streaming authors
3 *
4 * This Source Code Form is subject to the terms of the Mozilla Public
5 * License, v. 2.0. If a copy of the MPL was not distributed with this
6 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 */
8
9//! @file roc_audio/watchdog.h
10//! @brief Watchdog.
11
12#ifndef ROC_AUDIO_WATCHDOG_H_
13#define ROC_AUDIO_WATCHDOG_H_
14
17#include "roc_core/array.h"
18#include "roc_core/attributes.h"
19#include "roc_core/iarena.h"
21#include "roc_core/time.h"
22#include "roc_packet/units.h"
23
24namespace roc {
25namespace audio {
26
27//! Watchdog parameters.
29 //! Timeout for the lack of packets, nanoseconds.
30 //! @remarks
31 //! Maximum allowed period during which every frame is blank. After this period,
32 //! the session is terminated. This mechanism allows to detect dead, hanging, or
33 //! broken clients. Set to zero to disable.
35
36 //! Timeout for frequent stuttering, nanoseconds.
37 //! @remarks
38 //! Maximum allowed period during which every drop detection window overlaps with
39 //! at least one frame which caused packet drops and with at least one frame which
40 //! is incomplete (it may be the same frame). After this period, the session is
41 //! terminated. This mechanism allows to detect the vicious circle when all client
42 //! packets are a bit late and we are constantly dropping them producing unpleasant
43 //! noise. Set to zero to disable.
45
46 //! Window size of detecting stuttering, nanoseconds.
47 //! @see
48 //! choppy_playback_timeout
50
51 //! Frame status window size for logging, number of frames.
52 //! @remarks
53 //! Used for debug logging. Set to zero to disable.
55
56 //! Initialize config with default values.
62 }
63
64 //! Automatically deduce no_playback_timeout from target_latency.
66 no_playback_timeout = target_latency * 4 / 3;
67 }
68
69 //! Automatically deduce choppy_playback_window from choppy_playback_timeout.
71 choppy_playback_window = std::min(300 * core::Millisecond, timeout / 4);
72 }
73};
74
75//! Watchdog.
76//! @remarks
77//! Terminates session if it is considered dead or corrupted.
78class Watchdog : public IFrameReader, public core::NonCopyable<> {
79public:
80 //! Initialize.
82 const audio::SampleSpec& sample_spec,
83 const WatchdogConfig& config,
84 core::IArena& arena);
85
86 //! Check if object is successfully constructed.
87 bool is_valid() const;
88
89 //! Check if stream is still alive.
90 //! @returns
91 //! false if during the session timeout each frame has an empty flag or the maximum
92 //! allowed number of consecutive windows that can contain frames that aren't fully
93 //! filled and contain dropped packets was exceeded.
94 bool is_alive() const;
95
96 //! Read audio frame.
97 //! @remarks
98 //! Updates stream state and reads frame from the input reader.
99 virtual bool read(Frame& frame);
100
101private:
102 void update_blank_timeout_(const Frame& frame,
103 packet::stream_timestamp_t next_read_pos);
104 bool check_blank_timeout_() const;
105
106 void update_drops_timeout_(const Frame& frame,
107 packet::stream_timestamp_t next_read_pos);
108 bool check_drops_timeout_();
109
110 void update_status_(const Frame& frame);
111 void flush_status_();
112
113 IFrameReader& reader_;
114
115 const audio::SampleSpec sample_spec_;
116
117 const packet::stream_timestamp_t max_blank_duration_;
118 const packet::stream_timestamp_t max_drops_duration_;
119 const packet::stream_timestamp_t drop_detection_window_;
120
121 packet::stream_timestamp_t curr_read_pos_;
122 packet::stream_timestamp_t last_pos_before_blank_;
123 packet::stream_timestamp_t last_pos_before_drops_;
124
125 unsigned curr_window_flags_;
126
127 core::Array<char> status_;
128 size_t status_pos_;
129 bool status_show_;
130
131 bool alive_;
132 bool valid_;
133};
134
135} // namespace audio
136} // namespace roc
137
138#endif // ROC_AUDIO_WATCHDOG_H_
Dynamic array.
Compiler attributes.
Audio frame.
Definition: frame.h:25
Frame reader interface.
Definition: iframe_reader.h:22
Sample specification. Describes sample rate and channels.
Definition: sample_spec.h:26
virtual bool read(Frame &frame)
Read audio frame.
Watchdog(IFrameReader &reader, const audio::SampleSpec &sample_spec, const WatchdogConfig &config, core::IArena &arena)
Initialize.
bool is_valid() const
Check if object is successfully constructed.
bool is_alive() const
Check if stream is still alive.
Memory arena interface.
Definition: iarena.h:23
Base class for non-copyable objects.
Definition: noncopyable.h:23
Memory arena interface.
Frame reader interface.
const nanoseconds_t Millisecond
One millisecond represented in nanoseconds.
Definition: time.h:67
const nanoseconds_t Second
One second represented in nanoseconds.
Definition: time.h:70
int64_t nanoseconds_t
Nanoseconds.
Definition: time.h:58
uint32_t stream_timestamp_t
Packet stream timestamp.
Definition: units.h:36
Root namespace.
Non-copyable object.
Sample specifications.
Watchdog parameters.
Definition: watchdog.h:28
core::nanoseconds_t choppy_playback_window
Window size of detecting stuttering, nanoseconds.
Definition: watchdog.h:49
WatchdogConfig()
Initialize config with default values.
Definition: watchdog.h:57
core::nanoseconds_t choppy_playback_timeout
Timeout for frequent stuttering, nanoseconds.
Definition: watchdog.h:44
size_t frame_status_window
Frame status window size for logging, number of frames.
Definition: watchdog.h:54
core::nanoseconds_t no_playback_timeout
Timeout for the lack of packets, nanoseconds.
Definition: watchdog.h:34
void deduce_no_playback_timeout(core::nanoseconds_t target_latency)
Automatically deduce no_playback_timeout from target_latency.
Definition: watchdog.h:65
void deduce_choppy_playback_window(core::nanoseconds_t timeout)
Automatically deduce choppy_playback_window from choppy_playback_timeout.
Definition: watchdog.h:70
Time definitions.
Various units used in packets.