1// Copyright (C) 2023 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#ifndef QAUDIOSTATEMACHINE_P_H
5#define QAUDIOSTATEMACHINE_P_H
6
7//
8// W A R N I N G
9// -------------
10//
11// This file is not part of the Qt API. It exists purely as an
12// implementation detail. This header file may change from version to
13// version without notice, or even be removed.
14//
15// We mean it.
16//
17
18#include "qaudiostatemachineutils_p.h"
19
20#include <qpointer.h>
21#include <atomic>
22
23QT_BEGIN_NAMESPACE
24
25class QAudioStateChangeNotifier;
26
27/* QAudioStateMachine provides an opportunity to
28 * toggle QAudio::State with QAudio::Error in
29 * a thread-safe manner.
30 * The toggling functions return a notifier,
31 * which notifies about the change via
32 * QAudioStateChangeNotifier::stateChanged and errorChanged.
33 *
34 * The state machine is supposed to be used mostly in
35 * QAudioSink and QAudioSource implementations.
36 */
37class Q_MULTIMEDIA_EXPORT QAudioStateMachine
38{
39public:
40 using RawState = AudioStateMachineUtils::RawState;
41 class Notifier
42 {
43 public:
44 void reset()
45 {
46 if (auto stateMachine = std::exchange(obj&: m_stateMachine, new_val: nullptr))
47 stateMachine->reset(state: m_state, prevState: m_prevState);
48 }
49
50 ~Notifier() { reset(); }
51
52 Notifier(const Notifier &) = delete;
53 Notifier(Notifier &&other) noexcept
54 : m_stateMachine(std::exchange(obj&: other.m_stateMachine, new_val: nullptr)),
55 m_state(other.m_state),
56 m_prevState(other.m_prevState)
57 {
58 }
59
60 operator bool() const { return m_stateMachine != nullptr; }
61
62 QAudio::State prevAudioState() const { return AudioStateMachineUtils::toAudioState(state: m_prevState); }
63
64 QAudio::State audioState() const { return AudioStateMachineUtils::toAudioState(state: m_state); }
65
66 bool isDraining() const { return AudioStateMachineUtils::isDrainingState(state: m_state); }
67
68 bool isStateChanged() const { return prevAudioState() != audioState(); }
69
70 private:
71 Notifier(QAudioStateMachine *stateMachine = nullptr, RawState state = QAudio::StoppedState,
72 RawState prevState = QAudio::StoppedState)
73 : m_stateMachine(stateMachine), m_state(state), m_prevState(prevState)
74 {
75 }
76
77 private:
78 QAudioStateMachine *m_stateMachine;
79 RawState m_state;
80 const RawState m_prevState;
81
82 friend class QAudioStateMachine;
83 };
84
85 enum class RunningState {
86 Active = QtAudio::State::ActiveState,
87 Idle = QtAudio::State::IdleState
88 };
89
90 QAudioStateMachine(QAudioStateChangeNotifier &notifier);
91
92 ~QAudioStateMachine();
93
94 QAudio::State state() const;
95
96 QAudio::Error error() const;
97
98 bool isActiveOrIdle() const;
99
100 bool isDraining() const;
101
102 // atomicaly checks if the state is stopped and marked as drained
103 std::pair<bool, bool> getDrainedAndStopped() const;
104
105 // Stopped[draining] -> Stopped
106 bool onDrained();
107
108 // Active/Idle/Suspended -> Stopped
109 // or Active -> Stopped[draining] for shouldDrain = true
110 Notifier stop(QAudio::Error error = QAudio::NoError, bool shouldDrain = false,
111 bool forceUpdateError = false);
112
113 // Active/Idle/Suspended -> Stopped
114 Notifier stopOrUpdateError(QAudio::Error error = QAudio::NoError)
115 {
116 return stop(error, shouldDrain: false, forceUpdateError: true);
117 }
118
119 // Stopped -> Active/Idle
120 Notifier start(RunningState activeOrIdle = RunningState::Active);
121
122 // Active/Idle -> Suspended + saves the exchanged state
123 Notifier suspend();
124
125 // Suspended -> saved state (Active/Idle)
126 Notifier resume();
127
128 // Idle -> Active
129 Notifier activateFromIdle();
130
131 // Active/Idle -> Active/Idle + updateError
132 Notifier updateActiveOrIdle(RunningState activeOrIdle, QAudio::Error error = QAudio::NoError);
133
134 // Any -> Any; better use more strict methods
135 Notifier forceSetState(QAudio::State state, QAudio::Error error = QAudio::NoError);
136
137 // force set the error
138 Notifier setError(QAudio::Error error);
139
140private:
141 template <typename StatesChecker, typename NewState>
142 Notifier changeState(const StatesChecker &statesChecker, const NewState &newState);
143
144 void reset(RawState state, RawState prevState);
145
146private:
147 QPointer<QAudioStateChangeNotifier> m_notifier;
148 std::atomic<RawState> m_state = QAudio::StoppedState;
149 QAudio::State m_suspendedInState = QAudio::SuspendedState;
150};
151
152QT_END_NAMESPACE
153
154#endif // QAUDIOSTATEMACHINE_P_H
155

source code of qtmultimedia/src/multimedia/audio/qaudiostatemachine_p.h