群益API 事件回呼跑在哪個執行緒?回呼裡不能做的 4 件事
這四種狀況,看起來是四個不同的毛病:
- 報價一多,畫面就卡住或閃爍,整個介面沒反應。
- 報價越跑越慢,延遲越積越多,收盤前最嚴重。
- 偶發的崩潰,堆疊指向看不懂的地方,而且重現不了。
- 程式無預警卡死,沒有錯誤訊息,只能強制關閉。
它們常常是同一個根源:群益API 事件回呼跑在元件自己的執行緒上,而程式把它當成一般的函式呼叫在用。

目錄
群益API 事件回呼跑在哪個執行緒?
要回答這個問題,先看群益API 事件回呼和一般函式呼叫差在哪。一般的 API 呼叫是「你呼叫函式、拿到回傳值」,執行緒是你的——你決定什麼時候呼叫、在哪條緒上呼叫。
事件回呼剛好相反:元件在它自己的執行緒上,呼叫你寫的那個函式。
這個差別的後果很直接:你在回呼裡寫的每一行,都跑在一條你沒有建立、也不歸你控制的執行緒上,而那條執行緒同時還負責把後續的資料送進來。你在回呼裡待越久,後面的資料就塞得越久。
所有訂閱者都在同一條執行緒上排隊
還有一件事會放大這個問題:如果程式把報價事件再轉發給多個訂閱者,而轉發是同步的,那麼所有訂閱者都在同一條事件執行緒上依序執行。
一個訂閱者慢,全部跟著慢。這條路徑上如果同時掛著「計算」「畫面更新」「送單」,它們是串在一起的,不是各跑各的。你以為的三件事並行,實際上是一條單行道。
群益API 事件回呼裡不能做的 4 件事
| 紀律 | 為什麼 |
|---|---|
| 不要直接更新畫面 | UI 有自己的執行緒歸屬,從別條緒直接碰會出問題;而且畫面重繪很慢,會把資料流一起卡住 |
| 不要呼叫耗時的查詢 | 事件緒被佔住的期間,後面的事件全部在等 |
| 不要阻塞等待 | 在回呼裡等一個需要同一條緒才能完成的結果,會直接鎖死 |
| 不要在回呼內重入元件 | 部分函式在對應事件內同步呼叫會靜默失效——回傳成功,但事件整批不來 |
這四條就是群益API 事件回呼的全部紀律。前三條的後果你看得見:卡頓、延遲、當掉。第四條不一樣,它的失敗是無聲的。
第四條最難查:回傳成功,事件卻整批不來
在群益API 事件回呼裡重入元件的情況是這樣:你呼叫了一個函式,它回傳成功,然後你開始等對應的事件——而那個事件永遠不會來。
沒有例外、沒有錯誤碼、沒有任何東西告訴你出了問題。你手上唯一的線索是一個「成功」的回傳值,而它是誤導你的。
兩個已知的案例:
- 在
OnConnection的回呼內,同步呼叫SKQuoteLib_RequestStockList:函式回傳0(成功),但清單事件整批靜默。 - 官方建議避免在
OnNotifyLiveKLineData事件內呼叫SKQuoteLib_GetLiveKLineLONG。
這類問題之所以難查,是因為除錯的直覺會先懷疑「是不是沒訂閱到」「是不是參數錯了」——但那些地方都是對的。真正的原因是你在錯的執行緒上呼叫了它。
實務上的處理方式是一致的:在回呼裡記下「要做什麼」,離開回呼之後再去做。
反例與正解:回呼只收集,其餘交出去
先看反例。這段程式碼一次違反了三條紀律,而且它長得很像第一版最容易寫出來的樣子:
// ⚠️ 反例:不要這樣寫
private void OnQuoteReceived(short sMarketNo, int nStockIdx)
{
var snapshot = GetSnapshot(sMarketNo, nStockIdx);
labelPrice.Text = snapshot.Close.ToString(); // ① 在事件緒上直接更新畫面
var history = QueryHistory(snapshot.Symbol); // ② 耗時查詢,後面的報價全在等
if (ShouldFire(snapshot, history))
{
SendOrder(snapshot); // ③ 在事件緒上送單
}
}這段的問題不在任何一行單獨看起來錯——每一行都很合理。問題在於它們全部擠在一條不屬於你的執行緒上。
正解的結構是:群益API 事件回呼只做「取值 → 放下 → 結束」,其餘全部交出去。
// 事件緒只做最輕量的收集
private void OnQuoteReceived(short sMarketNo, int nStockIdx)
{
var snapshot = GetSnapshot(sMarketNo, nStockIdx);
lock (_gate)
{
_latest[snapshot.Symbol] = snapshot; // 只寫入最新狀態
}
_evaluationSignal.Set(); // 喚醒負責運算的執行緒,自己不算
}
// 畫面那一端用計時器定期取用,不在事件裡觸發重繪
private void OnUiTimerTick(object sender, EventArgs e)
{
Snapshot[] batch;
lock (_gate) { batch = _latest.Values.ToArray(); } // 取複本再離開鎖
RenderBatch(batch);
}兩段都是結構示意,不是可以直接編譯的專案碼。重點在形狀:事件那一端只寫入,畫面那一端只讀取,兩邊用最短的鎖區間交接。
畫面更新要合併,不要逐筆重繪
報價事件的量很大,逐筆更新畫面是行不通的。正確的方向是把最新狀態存起來,由畫面那一端定期批次取用——也就是上面那個計時器的作用。
合併的間隔要取多少?實務上 50–100 毫秒量級是一個可行的起點,但這是經驗值而不是建議值:它沒有量測數據支持它是最佳解,而最佳解本來就取決於你的商品數量、畫面複雜度與機器。把它當起點,然後自己量。
同樣的原則也適用於歷史回補:訂閱的當下可能一次收到大量歷史資料,如果逐筆往上層發通知,會把上層灌爆。實務上會累積到一定筆數才通知一次——累積多少由你依實際狀況決定,原則是不要讓每一筆都觸發一次完整的處理流程。
背景運算要吃快照,不要吃活的集合
把運算搬出群益API 事件回呼之後,會遇到第二個問題:事件緒還在持續往集合裡追加資料。
如果背景執行緒直接迭代那個集合,而事件緒同時在修改它,就會出問題。這類崩潰有很明顯的特徵:
- 偶發,跑十次可能只炸一次
- 重現不了,你照著同樣的步驟再跑一遍就沒事
- 堆疊指向集合內部,看起來跟你的業務邏輯完全無關
崩潰的地點,離真正的原因很遠。 這也是為什麼這類問題特別耗時間——你會在錯的地方找很久。
做法是:先在擁有集合的那條執行緒上擷取一份不可變複本,背景只讀那份複本。 上面正解的 batch = _latest.Values.ToArray() 就是這個動作——取完複本立刻離開鎖,後續處理不再碰原本的集合。
為什麼「搬到背景」不是通解?
讀到這裡,最自然的結論是:那就把所有重的事情都搬到背景執行緒。
但有一段不能搬:送單。
COM 物件有執行緒歸屬(也就是 STA,單一執行緒 Apartment 的概念):它的方法只能由所屬 apartment 的執行緒直接呼叫,其他執行緒要呼叫必須經由 COM 的封送機制。而實務上,這套元件跨執行緒直接呼叫會造成偶發的崩潰。
這不是某種寫法的偏好,是 COM 本身的規則——也是群益API 事件回呼之外,另一個由底層技術決定的限制。
所以正確的分工是:評估可以在背景做,但真正呼叫送單函式時要回到建立 COM 物件的那條執行緒。
另外一條要一起記住:持有鎖的時候不要跨進 COM 呼叫。 那是死鎖的典型配方——你在鎖裡面等 COM,而 COM 那一端可能正在等你手上的鎖。
還有一個容易被忽略的耗時操作:在回呼裡同步寫日誌檔。它看起來很輕,但檔案寫入是 I/O,一樣會卡住事件緒。改成非同步之後要記得,程式結束時最後一批日誌可能還沒寫出去,收尾要確保沖刷完成——不然出事的那一次,你最想看的那幾行剛好不在檔案裡。
常見問題
群益API 事件回呼跟一般的函式呼叫有什麼不同?
一般呼叫是你在自己的執行緒上呼叫函式;事件回呼是元件在它自己的執行緒上呼叫你寫的函式。你在回呼裡花的每一毫秒,後面的資料都在等。
群益API 事件回呼導致畫面卡頓,是不是電腦效能不夠或報價訂太多?
不一定。一個容易被忽略的原因是在事件回呼裡直接更新畫面,把資料流和畫面重繪綁在同一條路徑上。先確認畫面更新是不是由計時器批次觸發,而不是由每一筆報價觸發。
偶發崩潰、重現不了,是不是元件不穩定?
有一類崩潰來自兩條執行緒同時碰同一個集合——一邊在追加、一邊在迭代。特徵是偶發、重現不了、堆疊指向集合內部,而且崩潰點離真正的原因很遠。
把重的工作全部搬到背景執行緒就好了嗎?
不行。送單那一段不能搬——COM 物件有執行緒歸屬,其他執行緒要呼叫必須經由封送機制,而這套元件跨執行緒直接呼叫會造成偶發崩潰。評估可以在背景做,送出要回到建立 COM 物件的那條執行緒。
呼叫回傳成功,但事件一直不來,是哪裡寫錯了?
先確認那個呼叫是不是寫在某個事件的回呼裡面。部分函式在對應事件內同步呼叫會靜默失效——回傳成功,事件卻整批不來。把呼叫移出回呼再試一次。
風險揭露
期貨與選擇權屬高槓桿商品,價格波動可能造成超過原始保證金的損失,交易人須自負交易責任。本文為程式開發技術教學,說明事件驅動介面的執行緒模型與工程注意事項,不構成投資建議,也不保證任何交易結果。程式化交易並不降低市場風險,反而可能因程式錯誤造成非預期的委託行為——本文討論的執行緒問題正是這類錯誤的來源之一。
投資人教育資源
| 機構 | 資源 |
|---|---|
| 臺灣期貨交易所(TAIFEX) | 期貨及選擇權數位學習網 |
| 證券暨期貨市場發展基金會 | 證券期貨市場教育推廣 |
| 金融智慧網 | 金管會金融知識平台 |
| 中華民國期貨業商業同業公會 | 期貨業法規與宣導 |
| 證券投資人及期貨交易人保護中心 | 投資人保護與申訴 |
延伸閱讀
- 〈群益API 是什麼〉——COM、群益API 事件回呼、Interop 組件、STA 這幾個詞在那篇定義過,本篇是它那段四點清單的完整版。
- 〈Python 接群益API 收不到事件〉——同一個執行緒模型在 Python 端的表現:回呼可能根本不會被呼叫。
- 〈群益API 報價訂閱有哪兩層〉——這四條紀律在報價場景的實際應用,以及訂閱本身的兩條管道。
- 〈群益API 下單初始化有哪 7 步〉——送單留在原執行緒這條紀律,在下單流程裡的具體落點。
- 〈群益API 登入錯誤怎麼判讀〉——
2017這個碼也跟事件註冊的順序有關。 - 〈群益API 報價停止更新怎麼辦〉——看門狗在背景讀取事件寫入的狀態,是「背景運算要吃快照」的實際場景。
參考資料
- Processes, Threads, and Apartments – Microsoft Learn(COM 的執行緒模型與 apartment 概念)
- 四條事件緒紀律、訂閱者同緒執行、快照與活集合、送單執行緒限制、歷史回補批次、日誌沖刷,均為實作與測試歸納,非官方文件記載。
- 兩個重入案例為實測結果。
- 50–100 毫秒為實務量級,無量測數據支持其為最佳值。
免責聲明
本文章僅作為群益API實作經驗分享,不構成投資建議,且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資,請謹慎評估自身風險承擔能力。







![群益API Python 回傳值為什麼是 list?[in,out]、[out] 參數與 comtypes 的回傳規則 8 群益API Python 回傳值:[in,out]、[out] 參數與 comtypes 的回傳規則](https://capfutures.com/wp-content/uploads/2026/10/capital-api-python-out-params-768x403.webp)