群益API 事件回呼的執行緒模型示意圖,說明回呼跑在元件自己的執行緒上

群益API 事件回呼跑在哪個執行緒?回呼裡不能做的 4 件事

這四種狀況,看起來是四個不同的毛病:

  • 報價一多,畫面就卡住或閃爍,整個介面沒反應。
  • 報價越跑越慢,延遲越積越多,收盤前最嚴重。
  • 偶發的崩潰,堆疊指向看不懂的地方,而且重現不了。
  • 程式無預警卡死,沒有錯誤訊息,只能強制關閉。

它們常常是同一個根源:群益API 事件回呼跑在元件自己的執行緒上,而程式把它當成一般的函式呼叫在用。

群益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)期貨及選擇權數位學習網
證券暨期貨市場發展基金會證券期貨市場教育推廣
金融智慧網金管會金融知識平台
中華民國期貨業商業同業公會期貨業法規與宣導
證券投資人及期貨交易人保護中心投資人保護與申訴

延伸閱讀

參考資料

  • Processes, Threads, and Apartments – Microsoft Learn(COM 的執行緒模型與 apartment 概念)
  • 四條事件緒紀律、訂閱者同緒執行、快照與活集合、送單執行緒限制、歷史回補批次、日誌沖刷,均為實作與測試歸納,非官方文件記載。
  • 兩個重入案例為實測結果。
  • 50–100 毫秒為實務量級,無量測數據支持其為最佳值。

免責聲明

本文章僅作為群益API實作經驗分享,不構成投資建議,且策略及程式皆應自行撰寫。期貨及衍生性金融商品交易屬高風險投資,請謹慎評估自身風險承擔能力。

延伸閱讀|相關文章

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *