Struct QotCache 

pub struct QotCache {
    pub basic_qot: DashMap<SecurityKey, CachedBasicQot>,
    pub us_stock_overnight: DashMap<u64, bool>,
    pub klines: DashMap<String, Vec<CachedKLine>>,
    pub order_books: DashMap<SecurityKey, CachedOrderBook>,
    pub tickers: DashMap<SecurityKey, Vec<CachedTicker>>,
    pub rt_data: DashMap<String, Vec<CachedTimeShare>>,
    pub brokers: DashMap<SecurityKey, CachedBroker>,
    pub broker_dict: Arc<BrokerDictionaryCache>,
    pub spread_tables: DashMap<i32, Vec<CachedSpreadBand>>,
    pub cold_cache_waiters: DashMap<String, Arc<Notify>>,
    /* private fields */
}

行情缓存管理器

Fields

basic_qot: DashMap<SecurityKey, CachedBasicQot>

基本报价缓存

us_stock_overnight: DashMap<u64, bool>

US stock overnight-enabled state, keyed by backend stock_id.

C++ stores this as stockID -> bool in INNData_Qot_USStockOvernight:

• NNData_Qot_USStockOvernight.cpp:21-35 (missing key => false)
• NNBiz_Qot_USStockState.cpp:180-190 writes overnight_type == 1
• APIServer_Qot_MarketState.cpp:238-244 reads it for 11 -> 37 projection

klines: DashMap<String, Vec<CachedKLine>>

K 线缓存: key = sec:r{rehab}:k{type}:s{aggregate} where aggregate is typed RTH/ETH/ALL, not a raw backend RequestSection.

order_books: DashMap<SecurityKey, CachedOrderBook>

摆盘缓存

tickers: DashMap<SecurityKey, Vec<CachedTicker>>

逐笔缓存: 保留最近 N 条

rt_data: DashMap<String, Vec<CachedTimeShare>>

分时缓存 v1.4.106 codex 1140 F6 (P2 audit Finding 6): RT cache key 加 session 维度. 之前 DashMap<SecurityKey, ...> 把 RTH/ETH/PRE/AFTER 全部混到 同一桶, 客户端订阅 RTH 也能读到 PRE 数据. 现在 key 是 “sec_key:s{session}” (RequestSection 0=NORMAL/1=FULL/2=PREMARKET/ 3=AFTERHOURS), 隔离不同 session.

brokers: DashMap<SecurityKey, CachedBroker>

经纪队列缓存

broker_dict: Arc<BrokerDictionaryCache>

CMD18008 broker dictionary. Version + issuer names + broker-code aliases are published as one immutable snapshot by BrokerDictionaryRuntime.

spread_tables: DashMap<i32, Vec<CachedSpreadBand>>

C++ INNData_Qot_Spread: spread table code → price bands.

Filled from CMD6503 at QOT handler registration time and refreshed every 8h, matching NNBiz_Qot_Spread::SetTimerUpdateSpreadInfo. Read paths are synchronous and lock-free enough for push hot paths.

cold_cache_waiters: DashMap<String, Arc<Notify>>

v1.4.110 codex Phase 3 Slice 6c: cold-cache wait waiters.

key = "<cache_key>:<wait_kind>" (e.g. "91_BTCUSDT@b1007:basic" / "1_00700:orderbook"). value = shared Arc<Notify> 让 handler 阻塞等 push parser 写 cache 后唤醒.

对齐 C++ APIServer_Qot_StockBasic.cpp:226-320 WaitForReady — 已订阅但 cache 未就绪时 handler 主动 Pull_SubData + 等 push 写 cache.

设计 trade-off:

• 用 DashMap<String, Arc<Notify>> 而非 RwLock<HashMap>: 高并发读 写不锁全表
• key 编码 wait_kind 防 basic / orderbook 共用同一 Notify 互相错唤醒
• update path 调 notify_waiters (broadcast 给所有 awaiter) 然后从 map 中 remove (Arc 被 awaiter 持有, 自然释放)

Implementations

impl QotCache

pub fn make_kline_key_by_dims(sec_key: &str, dims: KlineDims) -> String

构造 K 线 cache key (v1.4.106 codex 1140 F3 4-tuple).

之前 key 仅 (sec_key, kl_type) 2-tuple, 同股票同 KLType 但前复权 vs 后复权 / RTH vs ETH 数据互相覆盖. 对齐 C++ APIServer_Qot_KL.cpp: GetNewestKLByCount(stock_id, enRehabType, enKLType, num, session, ...) 用 4 维 key.

• rehab: proto Qot_Common.RehabType (0=None, 1=Forward, 2=Backward), 对齐 backend FTCmdKline.ExrightType. 同一股票同一 kl_type 不同 rehab 走独立 cache, 不互相覆盖.
• kl_type: proto Qot_Common.KLType (1=1Min, 2=Day, …, 11=Quarter).
• session: typed C++ aggregate view (Rth, Eth, All), never a raw FTCmdKline.RequestSection. Push first folds the wire-order section list, then updates the applicable aggregate views atomically; pull/read select the exact connection aggregate.

pub fn make_kline_key( sec_key: &str, rehab: i32, kl_type: i32, session: KlineAggregateSession, ) -> String

pub fn update_klines_by_dims( &self, sec_key: &str, dims: KlineDims, klines: Vec<CachedKLine>, )

Replace one exact KLine aggregate generation under the shared owner.

pub fn update_klines( &self, sec_key: &str, rehab: i32, kl_type: i32, session: KlineAggregateSession, klines: Vec<CachedKLine>, )

pub fn upsert_kline_push_point( &self, sec_key: &str, dims: KlineDims, incoming: CachedKLine, ) -> Option<CachedKLine>

Merge one ordinary KLine push point with the existing pull generation.

Ref: C++ NNDataCenter/Quote/NNData_Qot_KLRT.cpp:790-895. A matching timestamp is replaced only when high-precision volume is not lower; the prior last_close_price remains authoritative and the following point is relinked. Only a point newer than the current tail may append.

pub fn upsert_kline_push_aggregates( &self, sec_key: &str, rehab: i32, kl_type: i32, sessions: &[KlineAggregateSession], incoming: CachedKLine, ) -> Option<CachedKLine>

Apply one ordinary push point to every C++ aggregate cache view under a single owner and return only the final aggregate’s updated point.

Ref: NNData_Qot_KLRT.cpp:561-584; the shared pResult is overwritten in RTH -> ETH -> ALL order and only that final result reaches PushKL.

pub fn get_klines_by_dims( &self, sec_key: &str, dims: KlineDims, ) -> Option<Vec<CachedKLine>>

Read one exact KLine aggregate generation under the shared owner.

pub fn get_klines( &self, sec_key: &str, rehab: i32, kl_type: i32, session: KlineAggregateSession, ) -> Option<Vec<CachedKLine>>

pub fn update_klines_broker_by_dims( &self, key: &QotSecurityKey, dims: KlineDims, klines: Vec<CachedKLine>, )

v1.4.110 Phase 2 Slice 5: 更新 K 线 (broker-aware).

用 QotSecurityKey::cache_key() 作 prefix, broker_id=None 时退化到原行为. composite 维度仍是 4-tuple (rehab, kl_type, session), broker_id 是第 5 维通过 QotSecurityKey 注入到 prefix.

pub fn merge_kline_pull_generation_broker_by_dims( &self, key: &QotSecurityKey, dims: KlineDims, incoming: Vec<CachedKLine>, )

Merge a late CMD6161 pull generation with any live points already committed while the request was in flight.

Ref: NNData_Qot_KLRT.cpp:896-973. Equal timestamps choose the larger high-precision volume; equal-volume points that differ only in last-close keep the existing live point. The merged chain then fills non-first zero last-close values from the preceding close.

pub fn merge_event_contract_klines_broker_by_direction( &self, key: &QotSecurityKey, dims: KlineDims, direction: i32, klines: Vec<CachedKLine>, )

Atomically replace one EventContract direction while retaining the other directions in the shared generic K-line dimension bucket.

Ref: frozen C++ aec0f6cda1 NNProtoCenter/Quote/NNBiz_Qot_KLRT.cpp:793-805,896-908. EventContract direction is point metadata, not a generic cache-key dimension. The DashMap entry guard makes concurrent YES/NO cold pulls one read-modify-write transaction.

pub fn upsert_event_contract_kline_push_broker_by_direction( &self, key: &QotSecurityKey, dims: KlineDims, direction: i32, incoming: CachedKLine, )

Upsert one EventContract point inside its direction-scoped generation. Same-timestamp updates replace directly (no ordinary volume gate), older points insert in order, and retention is capped per direction.

Ref: C++ NNDataCenter/Quote/NNData_Qot_ECKline.cpp:27-64.

pub fn update_klines_broker( &self, key: &QotSecurityKey, rehab: i32, kl_type: i32, session: KlineAggregateSession, klines: Vec<CachedKLine>, )

pub fn get_klines_broker_by_dims( &self, key: &QotSecurityKey, dims: KlineDims, ) -> Option<Vec<CachedKLine>>

v1.4.110 Phase 2 Slice 5: 获取 K 线 (broker-aware).

pub fn latest_authoritative_kline_broker_by_dims( &self, key: &QotSecurityKey, dims: KlineDims, ) -> Option<CachedKLine>

Return the newest non-blank KLine only when that exact point’s previous close is authoritative.

C++ GetNewestKlineByCount removes trailing blank/future points before selecting the newest public item (NNData_Qot_KLRT.cpp:178-192). This accessor keeps that scan under the cache read owner and clones one point instead of cloning the full bucket.

pub fn get_klines_broker( &self, key: &QotSecurityKey, rehab: i32, kl_type: i32, session: KlineAggregateSession, ) -> Option<Vec<CachedKLine>>

pub fn kline_count_like_cpp_broker_by_dims( &self, key: &QotSecurityKey, dims: KlineDims, ) -> usize

C++ INNData_Qot_KLRT::GetKlineCount: points up to and including the last non-blank point (trailing blank points are not counted).

Ref: NNData_Qot_KLRT.cpp:260-283.

pub fn kline_has_older_broker_by_dims( &self, key: &QotSecurityKey, dims: KlineDims, ) -> bool

C++ INNData_Qot_KLRT::HasOlderKline: missing cache entry or a bucket that no pull generation has written yet reports true (Ndt_Qot_KlineCacheData constructor default).

Ref: NNData_Qot_KLRT.cpp:285-309,777-782.

pub fn set_kline_has_older_broker_by_dims( &self, key: &QotSecurityKey, dims: KlineDims, has_older: bool, )

Record KlineRsp.has_older_item for the pulled session bucket only.

Ref: NNData_Qot_KLRT.cpp:533-556 (AddKlinePoints, KLRTSrc_Pull branch writes bHasOlderData{,BA,All} for the requested session).

pub fn kline_has_data_like_cpp_broker_by_dims( &self, key: &QotSecurityKey, dims: KlineDims, req_num: usize, ) -> bool

C++ IKLRTCore::IsHasKLData: the cache satisfies a GetKL request when it already holds req_num points or the backend has no older points to pull. Otherwise the caller must pull CMD6161 and merge before replying.

Ref: APIServer/Business/Quote/IKLRTCore.cpp:6-19.

pub fn begin_kline_pull_broker_by_dims( self: &Arc<Self>, key: &QotSecurityKey, dims: KlineDims, ) -> Option<KlinePullFlightGuard>

Claim the single in-flight CMD6161 slot for one (sec, dims). None means another pull for the same identity is in flight.

pub async fn wait_for_kline_pull_broker_by_dims( &self, key: &QotSecurityKey, dims: KlineDims, )

Wait until the in-flight CMD6161 pull for (sec, dims) (if any) has completed. Returns immediately when nothing is in flight.

impl QotCache

pub fn make_rt_key(sec_key: &str, session: i32) -> String

pub fn make_rt_key_broker(key: &QotSecurityKey, session: i32) -> String

pub fn begin_rt_pull( self: &Arc<Self>, key: &QotSecurityKey, ) -> Option<RtPullFlightGuard>

pub async fn wait_for_rt_pull(&self, key: &QotSecurityKey)

pub fn update_rt_data_broker( &self, key: &QotSecurityKey, session: i32, rt_data: Vec<CachedTimeShare>, )

pub fn publish_rt_pull_generation( &self, key: &QotSecurityKey, generation: RtPullGeneration, buckets: Vec<(i32, Vec<CachedTimeShare>)>, ) -> bool

pub fn get_rt_data_broker( &self, key: &QotSecurityKey, session: i32, ) -> Option<Vec<CachedTimeShare>>

pub fn apply_rt_push_point_broker( &self, key: &QotSecurityKey, session: i32, incoming: CachedTimeShare, average_mode: RtAverageMode, ) -> RtPushApplyOutcome

impl QotCache

pub fn register_cold_cache_waiter(&self, wait_key: &str) -> Arc<Notify>

v1.4.110 codex Phase 3 Slice 6c: 注册 cold-cache wait waiter.

返已存在或新建的 Arc<Notify>. handler 调:

1. register_cold_cache_waiter("91_BTCUSDT@b1007:basic") 获 Notify
2. 主动发 Pull_SubData CMD6824
3. tokio::time::timeout(Duration::from_secs(3), notify.notified()) 等
4. 再 get_basic_qot_broker(&key) 读 cache (可能仍 None — 真 timeout)

wait_kind 推荐: "basic" / "orderbook". 不混 sub_type 数字防误唤.

pub fn register_cold_cache_waiter_flight( &self, wait_key: &str, ) -> (Arc<Notify>, bool)

Register a cold-cache waiter and identify the request that created the flight.

The returned bool is true only for the caller that inserted the waiter. Handlers use it to singleflight the active Pull_SubData request while still letting all concurrent callers await the same Notify.

pub fn notify_cold_cache_waiters(&self, wait_key: &str)

v1.4.110 codex Phase 3 Slice 6c: 唤醒指定 cold-cache wait waiter.

push parser update path 调 (update_basic_qot / update_order_book / _broker 变种). 没 waiter → no-op. 有 waiter → notify_waiters() broadcast 给所有 awaiter, 然后 remove (Arc 仍被 awaiter 持有, 自然释放).

pub fn has_cold_cache_waiters(&self) -> bool

pub fn notify_basic_qot_cold_cache_waiters(&self, cache_key: &str)

pub fn notify_order_book_cold_cache_waiters(&self, cache_key: &str)

pub fn notify_odd_lot_order_book_cold_cache_waiters(&self, cache_key: &str)

pub fn notify_ticker_cold_cache_waiters(&self, cache_key: &str)

pub fn cleanup_cold_cache_waiter_if_idle( &self, wait_key: &str, caller_notify: &Arc<Notify>, )

v1.4.110 codex audit Round3 #22: cold-cache wait timeout 后清 idle waiter.

wait_for_basic_cache / wait_for_order_book_cache 3s timeout 仍 cache miss 时调. 若 push 始终没来, notify_cold_cache_waiters 不会触发, entry 会一直留在 cold_cache_waiters map (虽 bounded by distinct wait_key 数, 仍是慢速 leak).

只删 caller 自己注册的那个 entry, 且无其他并发 awaiter 时才删: remove_if closure 在 entry lock 下原子检查两条:

1. Arc::ptr_eq(stored, caller_notify) — stored 必须就是 caller 当初 register_cold_cache_waiter 拿到的同一 Arc. 防 race: caller timeout 后到本调用之间, 若 push 触发 notify_cold_cache_waiters 删了旧 entry, 另一个 wait_for_* 又 register 建了新 entry (不同 Arc), ptr_eq false → 不误删别人的新 entry.
2. Arc::strong_count(stored) <= 2 — DashMap stored Arc 1 + caller 持有的 caller_notify 1. > 2 表示有其他 wait_for_* 仍 await 同 entry → 保留让它们能被 notify 唤醒.

caller 约定: 必须把 register_cold_cache_waiter 返回的 Arc<Notify> 原样传进来 (caller 全程持有未 drop).

impl QotCache

pub fn new() -> Self

pub fn replace_spread_tables<I>(&self, tables: I)

where I: IntoIterator<Item = (i32, Vec<CachedSpreadBand>)>,

Replace the whole spread-table cache after a successful CMD6503 pull.

C++ INNData_Qot_Spread::SetSpreadInfo installs a flattened full table snapshot. We use a code-keyed map but preserve the same replacement semantics so stale removed codes do not linger across refreshes.

pub fn spread_value_raw(&self, spread_code: u32, price_raw: i64) -> i64

Return the raw 1e9 fixed-point spread value for a security price.

Mirrors the spread-band selection in NNBiz_Qot_Spread::GetStockSpreadPriceForTade with bUp=true and enTrdMarket=Unknown, which is what quote snapshot / BasicQot push use. Missing table returns 0, matching C++ cache miss falling through with initial nPriceSpread=0 at the API projection layer.

pub fn first_spread_value_raw(&self, spread_code: u32) -> i64

Event Contract contract-list projection uses the first configured band as the contract tick size, independent of a current quote price.

Ref: frozen C++ 10.9.6918 APIServer_Qot_GetEventContract.cpp, GetSpreadInfo(...)[0].

pub fn price_spread_for_raw_price( &self, spread_code: u32, price_raw: i64, ) -> f64

Project BasicQot.priceSpread / SnapshotBasicData.priceSpread.

pub fn price_spread_for_price(&self, spread_code: u32, price: f64) -> f64

Project priceSpread from a floating-point API price.

pub fn set_us_stock_overnight_state(&self, stock_id: u64, is_overnight: bool)

Update C++-style US overnight stock state (stockID -> bool).

Ref: NNData_Qot_USStockOvernight.cpp:21-35 and NNBiz_Qot_USStockState.cpp:180-190.

pub fn is_us_stock_overnight(&self, stock_id: u64) -> bool

Query whether a US stock is currently in overnight trading.

C++ cache miss returns false (NNData_Qot_USStockOvernight.cpp:29-34).

pub fn get_broker_name(&self, broker_id: i64) -> Option<String>

查 issuer id → broker display name (默认中文语言顺序). Cache miss returns None; callers must not fabricate a public name.

pub fn get_broker_name_for_app_lang( &self, broker_id: i64, app_lang: i32, ) -> Option<String>

Latest C++ selects the current-language abbreviation, then EN/TC/SC abbreviations, followed by the same full-name fallback sequence.

pub fn get_broker_name_by_issuer_for_app_lang( &self, issuer_id: i64, app_lang: i32, ) -> Option<String>

Resolve a CMD6968/top-ten issuer ID directly. Unlike HK broker queue and trade counter-broker fields, this ID must not pass through the broker-code alias map.

pub fn install_broker_dict(&self, entries: Vec<(i64, CachedBrokerInfo)>)

Compatibility seed helper for tests and embedded runtimes. Production CMD18008 uses the versioned two-map replacement API directly.

pub fn update_basic_qot(&self, key: &str, qot: CachedBasicQot)

更新基本报价

pub fn get_basic_qot(&self, key: &str) -> Option<CachedBasicQot>

获取基本报价

pub fn get_basic_qot_by_cache_key( &self, cache_key: &str, ) -> Option<CachedBasicQot>

pub fn basic_qot_last_close_by_cache_key(&self, cache_key: &str) -> Option<f64>

pub fn update_basic_qot_broker(&self, key: &QotSecurityKey, qot: CachedBasicQot)

v1.4.110 Phase 2 Slice 5: 更新基本报价 (broker-aware).

用 QotSecurityKey::cache_key() 派生 String key. broker_id=None → 与 update_basic_qot(public_sec_key, ...) 等价; broker_id=Some(N) → 写 独立 cache key "market_code@b{N}" (crypto multi-broker isolation).

pub fn get_basic_qot_broker( &self, key: &QotSecurityKey, ) -> Option<CachedBasicQot>

v1.4.110 Phase 2 Slice 5: 获取基本报价 (broker-aware).

pub fn update_order_book(&self, key: &str, ob: CachedOrderBook)

更新摆盘

pub fn update_order_book_broker( &self, key: &QotSecurityKey, ob: CachedOrderBook, )

v1.4.110 Phase 2 Slice 5: 更新摆盘 (broker-aware).

pub fn update_odd_lot_order_book_broker( &self, key: &QotSecurityKey, ob: CachedOrderBook, )

Update odd-lot order book cache (MY/SG only in C++ 10.7).

pub fn get_order_book_broker( &self, key: &QotSecurityKey, ) -> Option<CachedOrderBook>

v1.4.110 Phase 2 Slice 5: 获取摆盘 (broker-aware).

pub fn get_odd_lot_order_book_broker( &self, key: &QotSecurityKey, ) -> Option<CachedOrderBook>

Get odd-lot order book cache (MY/SG only in C++ 10.7).

pub fn append_tickers(&self, key: &str, new_tickers: Vec<CachedTicker>)

追加逐笔（保留最近 1000 条）

pub fn append_tickers_broker( &self, key: &QotSecurityKey, new_tickers: Vec<CachedTicker>, )

v1.4.110 Phase 2 Slice 5: 追加逐笔 (broker-aware).

pub fn get_tickers_broker( &self, key: &QotSecurityKey, ) -> Option<Vec<CachedTicker>>

v1.4.110 Phase 2 Slice 5: 获取逐笔 (broker-aware).

pub fn get_tickers_by_cache_key( &self, cache_key: &str, ) -> Option<Vec<CachedTicker>>

pub fn ticker_count_by_cache_key(&self, cache_key: &str) -> usize

pub fn recent_tickers_by_cache_key( &self, cache_key: &str, count: usize, ) -> Option<Vec<CachedTicker>>

pub fn update_broker(&self, key: &str, broker: CachedBroker)

更新经纪队列

pub fn get_broker(&self, key: &str) -> Option<CachedBroker>

获取经纪队列

pub fn clear_security(&self, key: &str)

清除指定股票的所有缓存

pub fn clear_security_broker(&self, key: &QotSecurityKey)

v1.4.110 Phase 2 Slice 5: 清除指定股票的所有缓存 (broker-aware).

用 QotSecurityKey::cache_key() 派生 cache key 字符串. broker_id=None → 与 clear_security(public_sec_key) 等价; broker_id=Some(N) → 只清 该 broker 下的 cache (其他 broker 下同 stock_id 的 cache 保留).

pub fn clear_realtime_quote_market(&self, quote_market_type: u8)

Clear only the C++ ReSub() realtime cache families for one backend quote-market bucket.

Ref: QotRealTimeData.cpp:613-671 clears Basic, OrderBook (including odd-lot), Broker and Ticker before a non-CMD6304 replay. KLine and RT are deliberately retained. Market membership is derived from each cache key’s public FTAPI market and the canonical FTAPI -> backend QOT mapping; string prefixes are not used as market identity.

pub fn clear_realtime_quotes_where( &self, belongs_to_target: impl Fn(&str) -> bool, )

Clear the C++ ReSub() realtime cache families selected by an owner-supplied market predicate.

The gateway supplies static-security-aware ownership for ordinary market replay. Cache-only callers may continue using clear_realtime_quote_market, whose public-market mapping remains correct for crypto exchange-ready replay.

pub fn clear_all_realtime_quotes(&self)

Clear all C++ ReSubAll() realtime cache families.

C++ constructs every supported MktQotSub bucket up front and calls ReSub() on every bucket after reconnect. Each ordinary ReSub() invokes QotRealTimeData::OnClearRealTimeData before rebuilding the backend desired set. KLine, RT and reference/configuration caches are deliberately retained.

Trait Implementations

impl Default for QotCache

fn default() -> Self

Returns the “default value” for a type.