chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/execution/frame_capture.py

@@ -0,0 +1,245 @@
+"""为显式报文导出保存同次记录和新编码所需DBC上下文。
+
+默认关闭时不创建这些对象。TextFrameStore只保存本次文本读取已交付的原帧、
+物理值和定位，可为多个窗口有限回放；不重新读原文件。FrameDBCContext负责
+新编码的DBC身份/字段声明，可借给新文本解码器共用一次加载。旧BLF链自身的
+DBC加载和解码不改变；为新增编码另加载同一哈希的定义属于新输出的显式成本。
+"""
+
+from hashlib import file_digest
+from pathlib import Path
+
+from ..legacy.records import LegacyCANField
+from ..legacy.binding import dbc_candidates, select_message
+from ..results.budget import _reserve_owned_ram,_release_owned_ram,_cleanup_owner
+from ..results.errors import ResultClosedError
+from ..results.frame_exports import as_export_frame
+from ..results.frame_patch import DBCFramePatch
+from ..results.frame_rebuild import FrameSample,_sample_packet,_restore_sample
+from ..results.frame_sort import FrameSort
+from .history import _metadata_bytes
+
+
+class FrameDBCContext:
+    """拥有供新输出使用的DBC定义、摘要和额外请求字段，借用者不负责释放。"""
+
+    def __init__(self,path,rules,budget,*,cycle_periods=False,integrity=True):
+        """加载并核身份，生成连续量/选择器请求。参数: path、规则tuple、budget。返回: owner。异常: DBC/预算/字段/I/O错。
+        """
+        if type(integrity) is not bool: raise TypeError("integrity需要bool")
+        self.path=Path(path); self.rules=rules; self._budget=budget
+        self._held_cost=self._fixed_cost=0; self.closed=self._closed=False
+        self.database=self._handle=self._patcher=None; self.sha256=None; self.extra_fields=();self.periods=None
+        self._candidates=(); self._selected=[]; self._identities=[]; self._cycle_periods=cycle_periods
+        self._by_frame_id={}; self._cycle_values={}
+        try:
+            size=self.path.stat().st_size
+            _reserve_owned_ram(self,1048576+size*64+_metadata_bytes(rules)*32,'_fixed_cost')
+            before_stat=self.path.stat()
+            before=self._hash() if integrity else None
+            from ..can_dependencies import import_can_dependency
+            cantools = import_can_dependency('cantools')
+            self.database=cantools.database.load_file(str(self.path))
+            # 导出的未知报文策略需要判断DBC是否认识该帧；一次建索引，不逐帧扫描DBC。
+            for message in self.database.messages:
+                self._by_frame_id.setdefault(message.frame_id,[]).append(message)
+            after_stat=self.path.stat()
+            changed=(before_stat.st_size,before_stat.st_mtime_ns,before_stat.st_ino)!=(after_stat.st_size,after_stat.st_mtime_ns,after_stat.st_ino)
+            if changed or integrity and self._hash()!=before:
+                raise ValueError('新增编码加载DBC期间内容发生变化')
+            self.sha256=before; self.version=cantools.__version__
+            fields=[]; candidates=[]
+            for rule in rules:
+                choices=dbc_candidates(self.database,rule.frame_id,(*rule.continuous,*rule.protected),rule.is_extended,rule.is_fd)
+                if not choices:
+                    raise ValueError('DBC缺少重建报文或指定信号: '+str(rule.frame_id))
+                candidates.append(choices)
+                # 候选定义均须可重建；最终选择等实际帧到达，不按DBC顺序取第一个。
+                for message in choices:
+                    if cycle_periods and id(message) not in self._cycle_values:
+                        # 声明DBC网格时，在打开日志前拒绝缺失或非法周期；只读取一次。
+                        from ..legacy.dbc_cycles import cycle_time_ns
+                        self._cycle_values[id(message)]=cycle_time_ns(message.cycle_time)
+                    try:
+                        self._patcher=DBCFramePatch(rule,message,budget)
+                    except BaseException as error:
+                        self._patcher=getattr(error,'frame_patch_cleanup_owner',None)
+                        raise
+                    self._patcher.close(); self._patcher=None
+                    names=tuple(dict.fromkeys((*rule.continuous,*(s.name for s in message.signals if s.is_multiplexer))))
+                    fields.extend(LegacyCANField(rule.channel,name,rule.frame_id,message.is_extended_frame,rule.is_fd) for name in names)
+            self.extra_fields=tuple(dict.fromkeys(fields))
+            self._candidates=tuple(candidates)
+            self._selected=[None]*len(rules); self._identities=[None]*len(rules)
+        except BaseException as error:
+            _cleanup_owner(self,error,'frame_dbc_cleanup_owner','导出DBC上下文')
+            raise
+
+    def _hash(self):
+        """核同一文件的完整内容身份。参数: 无。返回: SHA256文本。异常: 打开/读取/真实关闭错。
+        """
+        self._handle=self.path.open('rb')
+        digest=file_digest(self._handle,'sha256').hexdigest()
+        self._handle.close(); self._handle=None
+        return digest
+
+    def require_open(self):
+        """禁止使用已释放DBC。参数: 无。返回: None。异常: ResultClosedError。
+        """
+        if self.closed:
+            raise ResultClosedError('导出DBC上下文已关闭')
+
+    def pairs(self):
+        """交付规则与同次定义的有限借用。参数: 无。返回: tuple。异常: 已关闭或身份缺失。
+        """
+        self.require_open()
+        pairs=[]
+        for index,rule in enumerate(self.rules):
+            message=self._selected[index]
+            if message is None:
+                choices=self._candidates[index]
+                # 从未收到该报文时无需构造一个猜测的多候选输出规则。
+                if len(choices)!=1:
+                    continue
+                message=choices[0]
+            pairs.append((rule,message))
+        if self._cycle_periods:
+            self.periods=tuple(self._cycle_values[id(message)] for _,message in pairs)
+        return tuple(pairs)
+
+    def observe(self,frame):
+        """用正在读取的实际帧确定输出定义，禁止一条自动规则混用两种身份。
+
+        参数: frame为原始帧。返回: 匹配的DBC Message或None。异常: DBC或实际身份歧义。
+        副作用: 每条规则只保存一个已识别定义和身份，不保留额外帧或扫描文件。
+        """
+        self.require_open()
+        if frame.is_remote_frame or frame.is_error_frame:
+            return None
+        selected=[]
+        for index,rule in enumerate(self.rules):
+            if not rule.matches(frame):
+                continue
+            message=select_message(self._candidates[index],frame)
+            if message is None:
+                continue
+            identity=(frame.is_extended_id,frame.is_fd)
+            prior=self._identities[index]
+            if prior is not None and prior!=identity:
+                differing='is_extended' if prior[0]!=identity[0] else 'is_fd'
+                raise ValueError('报文重建规则匹配到多种实际帧，请补充'+differing)
+            self._identities[index]=identity; self._selected[index]=message
+            selected.append(message)
+        if len(selected)>1:
+            raise ValueError('同一实际报文匹配多个重建规则，请收紧帧类型约束')
+        return selected[0] if selected else None
+
+    def is_known_frame(self,frame):
+        """只判断未知报文输出策略，不要求未选报文的信号或定义唯一。
+
+        参数: frame为原始帧。返回: bool。异常: 已关闭时ResultClosedError。
+        副作用: 无，不解码或记录帧内容。
+        """
+        self.require_open()
+        return any(message.is_extended_frame==frame.is_extended_id
+            and (not frame.is_fd or message.is_fd)
+            for message in self._by_frame_id.get(frame.arbitration_id,()))
+
+    def close(self):
+        """在借用者关闭后释放定义和实际句柄。参数: 无。返回: None。异常: 原关闭/释放错可恢复。
+        """
+        if self.closed:
+            return
+        if self._handle is not None:
+            self._handle.close(); self._handle=None
+        if self._patcher is not None:
+            self._patcher.close(); self._patcher=None
+        self.database=None; self.extra_fields=();self.periods=None
+        self._candidates=(); self._selected=[]; self._identities=[]; self._by_frame_id={}; self._cycle_values={}
+        _release_owned_ram(self,self._fixed_cost,'_fixed_cost'); self.closed=self._closed=True
+
+
+class TextFrameStore:
+    """保存连续原序的同次文本CAN事实；封口后允许多个窗口逐个回放。"""
+
+    def __init__(self,path,budget,source,session_id,read_identity,*,database_context=None,channel=None,integrity=True,trace=True):
+        """建立有限排序暂存及真实读取身份。参数: 新路径、budget、源/会话/read身份，可借用重建DBC及声明通道。返回: owner。异常: I/O/预算错。
+        """
+        self.path=Path(path); self._budget=budget; self._held_cost=self._fixed_cost=self._row_cost=0
+        self.source_name=source; self.session_id=session_id; self.read_identity=read_identity
+        self.database_context=database_context; self.channel=channel; self.trace=trace
+        self.sort=None; self.count=0; self.last_ns=None; self.state='building'; self.closed=self._closed=False
+        try:
+            _reserve_owned_ram(self,131072,'_fixed_cost')
+            try:
+                self.sort=FrameSort(self.path,budget,integrity=integrity)
+            except BaseException as error:
+                self.sort=getattr(error,'frame_sort_cleanup_owner',None)
+                raise
+        except BaseException as error:
+            _cleanup_owner(self,error,'text_frame_store_cleanup_owner','文本原帧暂存构造')
+            raise
+
+    def append(self,record):
+        """保原序原时间，不让排序掩盖回退。参数: DecodedCANRecord同次记录。返回: None。异常: 时序/状态/预算/I/O错。
+        """
+        if self.closed or self.state!='building' or record.sequence!=self.count:
+            raise ValueError('文本原帧仓状态或连续序号不符')
+        if self.last_ns is not None and record.raw.time_ns<self.last_ns:
+            raise ValueError('文本原帧时间回退')
+        _reserve_owned_ram(self,1048576+_metadata_bytes((record.values,record.frame_values,record.frame_layout))*32,'_row_cost')
+        try:
+            known=record.status!='unknown'
+            if self.database_context is not None:
+                self.database_context.require_open()
+                frame=record.raw.frame
+                # 实际类型只在同次读取中匹配，输出不使用按ID覆盖的DBC字典。
+                message=self.database_context.observe(frame)
+                known=frame.channel==self.channel and self.database_context.is_known_frame(frame)
+            sample=FrameSample(as_export_frame(record,compact=not self.trace),record.frame_values,record.frame_layout,known)
+            self.sort.append((record.sequence,),_sample_packet(sample))
+            self.count+=1; self.last_ns=record.raw.time_ns
+        finally:
+            _release_owned_ram(self,self._row_cost,'_row_cost')
+
+    def seal(self):
+        """完整真实EOF后封口。参数: 无。返回: None。异常: 状态/配额/I/O错。
+        """
+        if self.closed or self.state!='building':
+            raise ResultClosedError('文本原帧仓不能重复封口')
+        self.sort.seal(); self.state='sealed'
+
+    def iter_samples(self):
+        """打开一个有界完整回放，提前关闭不声称完整核验。参数: 无。返回: FrameSample生成器。异常: 仓状态/篡改/I/O错。
+        """
+        if self.closed or self.state!='sealed':
+            raise ResultClosedError('文本原帧仓不可读')
+        cursor=self.sort._read(self.sort.path/f'{self.sort.level}-0.jsonl')
+        try:
+            for _,sequence,packet in cursor:
+                sample=_restore_sample(packet)
+                if sample.record.sequence!=sequence:
+                    raise ValueError('文本原帧暂存序号不一致')
+                yield sample
+        finally:
+            cursor.close()
+
+    def iter_frames(self):
+        """只交付原帧及定位，不重新解码。参数: 无。返回: ExportCANFrame生成器。异常: 原回放错。
+        """
+        cursor=self.iter_samples()
+        try:
+            for sample in cursor:
+                yield sample.record
+        finally:
+            cursor.close()
+
+    def close(self):
+        """关闭全部真实回放FD和排序仓，保诊断文件。参数: 无。返回: None。异常: 清理错可重试。
+        """
+        if self.closed:
+            return
+        if self.sort is not None:
+            self.sort.close()
+        _release_owned_ram(self,self._row_cost,'_row_cost')
+        _release_owned_ram(self,self._fixed_cost,'_fixed_cost'); self.closed=self._closed=True

chronaxis/execution/groups.py

@@ -0,0 +1,236 @@
+"""把已封存且全部来源EOF的历史归并为完整同刻更新组。
+
+输入只来自已解码磁盘历史，整数纳秒排序不会重读或重排旧文件链。
+每来源一个前瞻样本，跨批同刻更新全部收入同一组；不同原序号不collapse。
+游标、有限堆和当前组计入共享账本，超大组明确失败，不缓存全量历史。
+本组件是离线封存重放，不冒充未完成输入的在线watermark调度或算子执行。
+返回组须即时消费，调用方自行长期保留输出的内存不在内部预算保证内。
+"""
+
+# 冻结组模型、有限堆与复用既有行估算，不依赖任何数值后端。
+from dataclasses import dataclass
+import heapq
+from sys import getsizeof
+from ..timebase.conversion import require_int64_ns
+from ..results.codec import _estimate
+from ..results.errors import AnalysisError, ResultClosedError, ResultFormatError
+from ..results.spool import _cleanup_owner, _reserve_owned_ram, _release_owned_ram
+from .record_sample import RecordSample
+from .history_records import HistorySample, HistoryProgress, estimate_record_bytes
+
+
+@dataclass(frozen=True)
+class DecodedTimeGroup:
+    """保存一个session在同一整数ns的全部更新；来源和原sequence仍独立。"""
+
+    time_ns: int  # 完整组的共同纳秒坐标。
+    samples: tuple[HistorySample, ...]  # 同组全部原观测，不套用last_by_sequence策略。
+
+    def __post_init__(self) -> None:
+        """检查同刻、同会话和唯一原身份，不执行绑定或表达式。
+
+        参数: 无；读取time_ns/samples。返回: None。
+        异常: TypeError/ValueError/OverflowError为结构或身份错误。
+        """
+        require_int64_ns(self.time_ns)
+        if type(self.samples) is not tuple or not self.samples or any(type(item) not in (HistorySample,RecordSample) for item in self.samples):
+            raise TypeError('完整时间组需要非空HistorySample tuple')
+        if any(item.time_ns != self.time_ns for item in self.samples) or len({item.source_ref.session_id for item in self.samples}) != 1:
+            raise ValueError('时间组不能混用时间或session')
+        # 每别名原来源/sequence定位唯一，同原行不同列仍各自保留。
+        identities = {(item.source_ref, item.name, item.sequence) for item in self.samples}
+        if len(identities) != len(self.samples):
+            raise ValueError('完整时间组重复原观测')
+
+
+class _TimeGroupIterator:
+    """保留有限来源前瞻、当前组预算及活动游标。
+
+    readers为预分配槽位，未安装子游标由_uninstalled_reader单独持有。
+    close中断后保留尚未释放的句柄、组登记和预算，_closing期间只允许重试close。
+    closed只在真实子资源关闭且组预算抵销后成立，不能凭尝试关闭就解除所有权。
+    _held_cost仅含本层_state_cost与_group_cost，不包含子reader或借用history金额。
+    """
+
+    def __init__(self, owner, *, sources=None):
+        """先申请状态预算，再为已封存历史打开各来源独立游标。
+
+        参数: owner为DecodedHistoryStore；sources为唯一已知来源名tuple，None选择全部。
+        返回: 新组迭代器，只有所选来源参与完整同刻组。
+        异常: 生命周期/预算/打开或解析原错；持续清理失败从time_group_iterator_cleanup_owner恢复。
+        """
+        owner._check('sealed')
+        # 子集输入先做常量附加空间校验；禁止字符串/列表、未知或重复名偷偷扩充来源。
+        # 重复检查不预先建立set，按来源数增长的临时容器必须等预算预约成功后再创建。
+        if sources is not None:
+            if type(sources) is not tuple or any(type(name) is not str for name in sources):
+                raise TypeError('时间组来源子集需要来源名tuple或None')
+            for index, name in enumerate(sources):
+                if name not in owner.validators:
+                    raise ValueError('时间组来源子集包含未知来源')
+                if any(sources[previous] == name for previous in range(index)):
+                    raise ValueError('时间组来源子集不能重复')
+        # 常量空间计算原tuple估算，不在预留前构造按来源数增长的排序列表或tuple。
+        selected = owner.validators if sources is None else sources
+        count = len(selected)
+        tuple_bytes = getsizeof(()) + count * (getsizeof((None,)) - getsizeof(()))
+        names_cost = tuple_bytes + sum(_estimate(name) + 32 for name in selected)
+        state_cost = 8192 + count * 2048 + names_cost * 16
+        # 最小清理字段先建立，按来源数分配的结构、真实申请及打开都在保护区内。
+        self.owner, self.closed = owner, False
+        self._budget, self._held_cost = owner.budget, 0
+        self._closing = False
+        self._state_cost = self._group_cost = 0
+        self.readers, self.heap, self.last_times = [], [], []
+        self._current_group = None
+        self._uninstalled_reader = None
+        try:
+            # 仅围绕本层单笔预约检查实际账本，不从深子失败后的共享总额反推费用。
+            _reserve_owned_ram(self, state_cost, '_state_cost')
+            # 排序只规范所选来源顺序；未选来源不打开游标，也不并入相同时刻的更新。
+            names = tuple(sorted(selected))
+            self.readers = [None] * count
+            self.last_times = [None] * len(names)
+            for index, source in enumerate(names):
+                # 保存真实子游标以后才安装；安装前后失败都保有可关闭的句柄。
+                self._uninstalled_reader = owner.iter_records(source)
+                self.readers[index] = self._uninstalled_reader
+                self._uninstalled_reader = None
+            for index in range(len(self.readers)):
+                self._advance(index)
+        except BaseException as exc:
+            # 子reader构造或注册失败可能尚未赋值；只接管尚未在本组槽位拥有的实际恢复句柄。
+            reader = getattr(exc, 'history_iterator_cleanup_owner', None)
+            if (reader is not None and self._uninstalled_reader is None
+                    and not any(reader is installed for installed in self.readers)):
+                self._uninstalled_reader = reader
+            _cleanup_owner(self, exc, 'time_group_iterator_cleanup_owner', '时间组游标构造')
+            raise
+
+    def _advance(self, index: int) -> None:
+        """略过保留在历史中的批次进度，读取该来源下一个真实更新。
+
+        参数: index为固定来源游标编号。返回: None，必要时heap增加一个前瞻。
+        异常: 历史损坏/读取错误传播；真实EOF由游标校验完整计数与摘要。
+        """
+        for record in self.readers[index]:
+            # 所有来源已经EOF并seal，略过进度不会凭单批推断在线组完整。
+            if isinstance(record, HistoryProgress):
+                continue
+            previous = self.last_times[index]
+            if previous is not None and record.time_ns < previous:
+                raise ResultFormatError('解码历史重放时间回退')
+            self.last_times[index] = record.time_ns
+            # 一来源最多一个前瞻，index确保不同来源之间无需比较模型对象。
+            heapq.heappush(self.heap, (record.time_ns, index, record))
+            return
+
+    def __iter__(self) -> '_TimeGroupIterator':
+        """返回当前独立组游标。
+
+        参数: 无。返回: self。异常: 无。
+        """
+        return self
+
+    def __next__(self) -> DecodedTimeGroup:
+        """一次提交全部同刻更新，跨批/跨来源不拆成部分上下文。
+
+        参数: 无。返回: 一个DecodedTimeGroup。
+        异常: StopIteration为全部历史校验完成；预算/损坏/关闭错误不丢组继续。
+        """
+        if self.owner.closed:
+            raise ResultClosedError('解码历史已关闭')
+        if self.closed:
+            raise StopIteration
+        if self._closing:
+            raise ResultClosedError('完整时间组游标正在关闭')
+        # 上个组只在请求下一组或关闭时释放；调用方长期持有返回对象须自行预算。
+        self._current_group = None
+        if self._group_cost:
+            # 上个组实际释放后即清槽，返回取消也不能在close时再次扣同一笔借用金额。
+            _release_owned_ram(self, self._group_cost, '_group_cost')
+        if not self.heap:
+            self.close()
+            raise StopIteration
+        samples = []
+        time = self.heap[0][0]
+        try:
+            while self.heap and self.heap[0][0] == time:
+                _, index, record = heapq.heappop(self.heap)
+                cost = estimate_record_bytes(record)
+                # 每个record的直接预约成功后即登记，即使返回取消也由当前group唯一清理。
+                _reserve_owned_ram(self, cost, '_group_cost')
+                samples.append(record)
+                # 继续同来源直到更晚样本或真正EOF，确保跨批同刻组全部读齐。
+                self._advance(index)
+            # 排序仅规范同组跨列输出顺序，事件执行时仍原子应用整组而非按此顺序触发。
+            samples.sort(key=lambda item: (item.source_ref.source_name, item.sequence, item.name))
+            self._current_group = DecodedTimeGroup(time, tuple(samples))
+            return self._current_group
+        except BaseException as exc:
+            _cleanup_owner(self, exc, 'time_group_iterator_cleanup_owner', '时间组重放')
+            # 取消和既有AnalysisError原样传播，不用错误空组代替。
+            if isinstance(exc, (KeyboardInterrupt, SystemExit, AnalysisError)):
+                raise
+            error = AnalysisError('完整时间组重放失败')
+            # 保持已有AnalysisError包装合同；持续清理的顶层恢复入口在外层和原cause均可达。
+            recovery = getattr(exc, 'time_group_iterator_cleanup_owner', None)
+            if recovery is not None:
+                error.time_group_iterator_cleanup_owner = recovery
+                for note in getattr(exc, '__notes__', ()):
+                    error.add_note(note)
+            raise error from exc
+
+    def close(self) -> None:
+        """幂等关闭全部源游标并释放当前组/固定状态，不删除历史文件。
+
+        参数: 无。返回: None，重复关闭安全。
+        异常: 首个真实子关闭错误，仍尝试其余游标；预算/取消传播。
+            动作前失败保留所有权供重试，实际释放后的取消只完成最小关闭。
+        """
+        if self.closed:
+            # 释放后登记移除中断可能留下已关闭孤儿，重试只修登记而不再扣账。
+            self.owner._groups.discard(self)
+            return
+        self._closing = True
+        first_error = None
+        try:
+            # 安装失败可能只留下局部子游标；即使同时在槽位中，子close也须幂等。
+            if self._uninstalled_reader is not None:
+                try:
+                    self._uninstalled_reader.close()
+                except BaseException as exc:
+                    first_error = exc
+            for reader in self.readers:
+                if reader is None:
+                    continue
+                try:
+                    reader.close()
+                except BaseException as exc:
+                    if first_error is None:
+                        first_error = exc
+        finally:
+            # 子资源未真正关闭时保留所有字段和组成本，不能丢句柄或提前解除登记。
+            children_closed = all(reader is None or reader.closed for reader in self.readers)
+            uninstalled_closed = self._uninstalled_reader is None or self._uninstalled_reader.closed
+            if children_closed and uninstalled_closed:
+                budget, cost = self.owner.budget, self._state_cost + self._group_cost
+                before, released = budget.ram_bytes, False
+                try:
+                    # 本层两槽合计一次归还；空owner无需调用外部预算，也不扣任何子/借用金额。
+                    if cost:
+                        budget.release_ram(cost)
+                    released = True
+                finally:
+                    # 已抵销后先清成本/closed，再解除登记；动作前失败则完整保留供重试。
+                    if released or budget.ram_bytes == before - cost:
+                        self._held_cost -= cost
+                        self.closed = True
+                        self._state_cost = self._group_cost = 0
+                        self.readers.clear()
+                        self.heap.clear()
+                        self.last_times.clear()
+                        self._current_group = self._uninstalled_reader = None
+                        self.owner._groups.discard(self)
+        if first_error is not None:
+            raise first_error