新增一节：使用条件变量实现后台提示音播放

Mq-b · Mq-b · commit 8954e3c9f1b9 · 2024-09-21T11:36:06.000+08:00
diff --git a/code/ModernCpp-ConcurrentProgramming-Tutorial/26使用条件变量实现后台提示音播放.cpp b/code/ModernCpp-ConcurrentProgramming-Tutorial/26使用条件变量实现后台提示音播放.cpp
@@ -0,0 +1,106 @@
+#include <SFML/Audio.hpp>
+#include <mutex>
+#include <condition_variable>
+#include <atomic>
+#include <thread>
+#include <queue>
+#include <array>
+#include <iostream>
+using namespace std::chrono_literals;
+
+class AudioPlayer{
+public:
+    AudioPlayer() : stop {false}, player_thread{ &AudioPlayer::playMusic, this }
+    {}
+
+    ~AudioPlayer(){
+        while (!audio_queue.empty()){
+            std::this_thread::sleep_for(50ms);
+        }
+        stop = true;
+        cond.notify_all();
+        if(player_thread.joinable()){
+            player_thread.join();
+        }
+    }
+
+    void addAudioPath(const std::string& path){
+        std::lock_guard<std::mutex> lc{ m };
+        audio_queue.push(path);
+        cond.notify_one();
+    }
+
+private:
+    void playMusic(){
+        while(!stop){
+            std::string path;
+            {
+                std::unique_lock<std::mutex> lock{ m };
+                // 条件不满足，就解锁 unlock，让其它线程得以运行 如果被唤醒了，就会重新获取锁 lock
+                cond.wait(lock, [this] {return !audio_queue.empty() || stop; });
+
+                if (audio_queue.empty()) return; // 防止对象为空时出问题
+
+                path = audio_queue.front(); // 取出
+                audio_queue.pop();          // 取出后就删除这个元素，表示此元素以及被使用
+            }
+
+            if(!music.openFromFile(path)){
+                std::cerr << "无法加载音频文件: " << path << std::endl;
+                continue;
+            }
+
+            music.play(); // 异步 非阻塞
+
+            while(music.getStatus() == sf::SoundSource::Playing){
+                sf::sleep(sf::seconds(0.1f)); // sleep 避免忙等 占用 CPU
+            }
+        }
+    }
+
+    std::atomic<bool> stop;              // 控制线程的停止与退出
+    std::thread player_thread;           // 后台执行音频播放任务的专用线程
+    std::mutex m;                        // 保护共享资源
+    std::condition_variable cond;        // 控制线程的等待和唤醒，当有新的任务的时候通知播放线程
+    std::queue<std::string> audio_queue; // 音频任务队列，存储待播放的音频文件的路径
+    sf::Music music;                     // SFML 音频播放器对象，用来加载播放音频
+
+public:
+    static constexpr std::array soundResources{
+    "./sound/01初始化失败.ogg",
+    "./sound/02初始化成功.ogg",
+    "./sound/03试剂不足，请添加.ogg",
+    "./sound/04试剂已失效，请更新.ogg",
+    "./sound/05清洗液不足，请添加.ogg",
+    "./sound/06废液桶即将装满，请及时清空.ogg",
+    "./sound/07废料箱即将装满，请及时清空.ogg",
+    "./sound/08激发液A液不足，请添加.ogg",
+    "./sound/09激发液B液不足，请添加.ogg",
+    "./sound/10反应杯不足，请添加.ogg",
+    "./sound/11检测全部完成.ogg"
+    };
+};
+
+AudioPlayer audioPlayer;
+
+int main() {
+    audioPlayer.addAudioPath(AudioPlayer::soundResources[4]);
+    audioPlayer.addAudioPath(AudioPlayer::soundResources[5]);
+    audioPlayer.addAudioPath(AudioPlayer::soundResources[6]);
+    audioPlayer.addAudioPath(AudioPlayer::soundResources[7]);
+
+    std::thread t{ [] {
+        std::this_thread::sleep_for(1s);
+        audioPlayer.addAudioPath(AudioPlayer::soundResources[1]);
+    } };
+    std::thread t2{ [] {
+        audioPlayer.addAudioPath(AudioPlayer::soundResources[0]);
+    } };
+
+    std::cout << "乐\n";
+
+    t.join();
+    t2.join();
+
+    std::cout << "end\n";
+}
diff --git a/code/ModernCpp-ConcurrentProgramming-Tutorial/CMakeLists.txt b/code/ModernCpp-ConcurrentProgramming-Tutorial/CMakeLists.txt
@@ -12,14 +12,14 @@ elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR CMAKE_CXX_COMPILER_ID STREQUAL "C
     add_compile_options("-finput-charset=UTF-8" "-fexec-charset=UTF-8")
 endif()
 
-add_executable(${PROJECT_NAME} "25线程安全的队列.cpp")
+add_executable(${PROJECT_NAME} "26使用条件变量实现后台提示音播放.cpp")
 
 
 # 设置 SFML 的 CMake 路径
 set(SFML_DIR "D:/lib/SFML-2.6.1-windows-vc17-64-bit/SFML-2.6.1/lib/cmake/SFML")
 
-# 查找 SFML 库并设置链接选项
+# 查找 SFML 库
 find_package(SFML 2.6.1 COMPONENTS system window graphics audio network REQUIRED)
 
-# 链接 SFML 库到项目
+# 链接 SFML 库到项目 设置链接选项
 target_link_libraries(${PROJECT_NAME} sfml-system sfml-window sfml-graphics sfml-audio sfml-network)
diff --git a/code/ModernCpp-ConcurrentProgramming-Tutorial/test/AduioPlayer.h b/code/ModernCpp-ConcurrentProgramming-Tutorial/test/AduioPlayer.h
@@ -30,9 +30,9 @@ class AudioPlayer {
     }
 
     void addAudioPath(const std::string& path) {
-        std::lock_guard<std::mutex> lock{ mtx };
-        audio_queue.push(path);
-        cond.notify_one();  // 通知线程新的音频
+        std::lock_guard<std::mutex> lock{ mtx }; // 互斥量确保了同一时间不会有其它地方在操作共享资源（队列）
+        audio_queue.push(path); // 为队列添加元素 表示有新的提示音需要播放
+        cond.notify_one();      // 通知线程新的音频
     }
 
 private:
@@ -45,8 +45,8 @@ class AudioPlayer {
 
                 if (audio_queue.empty()) return; // 防止在对象为空时析构出错
 
-                path = audio_queue.front();
-                audio_queue.pop();
+                path = audio_queue.front(); // 从队列中取出元素
+                audio_queue.pop();          // 取出后就删除元素，表示此元素已被使用
             }
 
             if (!music.openFromFile(path)) {
@@ -58,18 +58,18 @@ class AudioPlayer {
 
             // 等待音频播放完毕
             while (music.getStatus() == sf::SoundSource::Playing) {
-                sf::sleep(sf::seconds(0.1f));  // sleep 避免忙等占用CPU
+                sf::sleep(sf::seconds(0.1f));  // sleep 避免忙等占用 CPU
             }
         }
     }
 
-    std::atomic<bool> stop;
-    std::thread player_thread;
-    std::mutex mtx;
-    std::condition_variable cond;
-    std::queue<std::string> audio_queue;
-    sf::Music music;
-
+    std::atomic<bool> stop;              // 控制线程的停止与退出，
+    std::thread player_thread;           // 后台执行音频任务的专用线程
+    std::mutex mtx;                      // 保护共享资源
+    std::condition_variable cond;        // 控制线程等待和唤醒，当有新任务时通知音频线程
+    std::queue<std::string> audio_queue; // 音频任务队列，存储待播放的音频文件路径
+    sf::Music music;                     // SFML 音频播放器，用于加载和播放音频文件
+    
 public:
     static constexpr std::array soundResources{
         "./sound/01初始化失败.ogg",
diff --git a/md/04同步操作.md b/md/04同步操作.md
@@ -180,7 +180,7 @@ public:
     std::shared_ptr<T> pop() {
         std::unique_lock<std::mutex> lk{ m };
         data_cond.wait(lk, [this] {return !data_queue.empty(); });
-        std::shared_ptr<T>res { std::make_shared<T>(data_queue.front()) };
+        std::shared_ptr<T> res { std::make_shared<T>(data_queue.front()) };
         data_queue.pop();
         return res;
     }
@@ -286,7 +286,130 @@ Consumer 线程弹出元素 4：
 
 到此，也就可以了。
 
-## 使用条件变量实现后台音乐播放
+## 使用条件变量实现后台提示音播放
+
+一个常见的场景是：当你的软件完成了主要功能后，领导可能突然要求添加一些竞争对手产品的功能。比如领导看到了人家的设备跑起来总是有一些播报，说明当前的情况，执行的过程，或者报错了也会有提示音说明。于是就想让我们的程序也增加“**语音提示**”的功能。此时，你需要考虑如何在程序运行到不同状态时添加适当的语音播报，并且**确保这些提示音的播放不会影响其他功能的正常运行**。
+
+为了不影响程序的流畅执行，提示音的播放显然不能占据业务线程的资源。我们需要额外启动一个线程来专门处理这个任务。
+
+但是，大多数的提示音播放都是短暂且简单。如果每次播放提示音时都新建一个线程，且不说创建线程也需要大量时间，可能影响业务正常的执行任务的流程，就光是其频繁创建线程的开销也是不能接受的。
+
+---
+
+因此，更合理的方案是：**在程序启动时，就启动一个专门用于播放提示音的线程。当没有需要播放的提示时，该线程会一直处于等待状态；一旦有提示音需要播放，线程就被唤醒，完成播放任务**。
+
+具体来说，我们可以通过条件变量来实现这一逻辑，核心是监控一个音频队列。我们可以封装一个类型，包含以下功能：
+
+- 一个成员函数在对象构造时就启动，使用条件变量监控队列是否为空，互斥量确保共享资源的同步。如果队列中有任务，就取出并播放提示音；如果队列为空，则线程保持阻塞状态，等待新的任务到来。
+- 提供一个外部函数，以供在需要播放提示音的时候调用它，向队列添加新的元素，该函数需要通过互斥量来保护数据一致性，并在成功添加任务后唤醒条件变量，通知播放线程执行任务。
+
+> 这种设计通过合理利用**条件变量**和**互斥量**，不仅有效减少了 CPU 的无效开销，还能够确保主线程的顺畅运行。它不仅适用于提示音的播放，还能扩展用于其他类似的后台任务场景。
+
+我们引入 [SFML](https://github.com/SFML/SFML) 三方库进行声音播放，然后再自己进行上层封装。
+
+```CPP
+class AudioPlayer {
+public:
+    AudioPlayer() : stop{ false }, player_thread{ &AudioPlayer::playMusic, this }
+    {}
+
+    ~AudioPlayer() {
+        // 等待队列中所有音乐播放完毕
+        while (!audio_queue.empty()) {
+            std::this_thread::sleep_for(50ms);
+        }
+        stop = true;
+        cond.notify_all();
+        if (player_thread.joinable()) {
+            player_thread.join();
+        }
+    }
+
+    void addAudioPath(const std::string& path) {
+        std::lock_guard<std::mutex> lock{ mtx }; // 互斥量确保了同一时间不会有其它地方在操作共享资源（队列）
+        audio_queue.push(path); // 为队列添加元素 表示有新的提示音需要播放
+        cond.notify_one();      // 通知线程新的音频
+    }
+
+private:
+    void playMusic() {
+        while (!stop) {
+            std::string path;
+            {
+                std::unique_lock<std::mutex> lock{ mtx };
+                cond.wait(lock, [this] { return !audio_queue.empty() || stop; });
+
+                if (audio_queue.empty()) return; // 防止在对象为空时析构出错
+
+                path = audio_queue.front(); // 从队列中取出元素
+                audio_queue.pop();          // 取出后就删除元素，表示此元素已被使用
+            }
+
+            if (!music.openFromFile(path)) {
+                std::cerr << "无法加载音频文件: " << path << std::endl;
+                continue;  // 继续播放下一个音频
+            }
+
+            music.play();
+
+            // 等待音频播放完毕
+            while (music.getStatus() == sf::SoundSource::Playing) {
+                sf::sleep(sf::seconds(0.1f));  // sleep 避免忙等占用 CPU
+            }
+        }
+    }
+
+    std::atomic<bool> stop;              // 控制线程的停止与退出，
+    std::thread player_thread;           // 后台执行音频任务的专用线程
+    std::mutex mtx;                      // 保护共享资源
+    std::condition_variable cond;        // 控制线程等待和唤醒，当有新任务时通知音频线程
+    std::queue<std::string> audio_queue; // 音频任务队列，存储待播放的音频文件路径
+    sf::Music music;                     // SFML 音频播放器，用于加载和播放音频文件
+};
+```
+
+该代码实现了一个简单的**后台音频播放类型**，通过**条件变量**和**互斥量**确保播放线程 `playMusic` 只在只在**有音频任务需要播放时工作**（当外部通过调用 `addAudioPath()` 向队列添加播放任务时）。在没有任务时，线程保持等待状态，避免占用 CPU 资源影响主程序的运行。
+
+此外，关于提示音的播报，为了避免每次都手动添加路径，我们可以创建一个音频资源数组，便于使用：
+
+```cpp
+static constexpr std::array soundResources{
+    "./sound/01初始化失败.ogg",
+    "./sound/02初始化成功.ogg",
+    "./sound/03试剂不足，请添加.ogg",
+    "./sound/04试剂已失效，请更新.ogg",
+    "./sound/05清洗液不足，请添加.ogg",
+    "./sound/06废液桶即将装满，请及时清空.ogg",
+    "./sound/07废料箱即将装满，请及时清空.ogg",
+    "./sound/08激发液A液不足，请添加.ogg",
+    "./sound/09激发液B液不足，请添加.ogg",
+    "./sound/10反应杯不足，请添加.ogg",
+    "./sound/11检测全部完成.ogg"
+};
+```
+
+为了提高代码的可读性，我们还可以使用一个枚举类型来表示音频资源的索引：
+
+```cpp
+enum SoundIndex {
+    InitializationFailed,
+    InitializationSuccessful,
+    ReagentInsufficient,
+    ReagentExpired,
+    CleaningAgentInsufficient,
+    WasteBinAlmostFull,
+    WasteContainerAlmostFull,
+    LiquidAInsufficient,
+    LiquidBInsufficient,
+    ReactionCupInsufficient,
+    DetectionCompleted,
+    SoundCount // 总音频数量，用于计数
+};
+```
+
+需要注意的是 SFML不支持 `.mp3` 格式的音频文件，大家可以使用 ffmpeg 或者其它软件[网站](https://www.freeconvert.com/audio-converter)将音频转换为支持的格式。
+
+如果是测试使用，不知道去哪生成这些语音播报，我们推荐 [`tts-vue`](https://github.com/LokerL/tts-vue)。
 
 ## 使用 `future`
 
