110 lines
5.1 KiB
Markdown
110 lines
5.1 KiB
Markdown
---
|
|
source_files:
|
|
- Common/DTS.Common.SerializationPlus/EventInfoAggregate.cs
|
|
generated_at: "2026-04-16T11:34:44.427048+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "342395eec4a038a1"
|
|
---
|
|
|
|
# Documentation: EventInfoAggregate
|
|
|
|
## 1. Purpose
|
|
|
|
`EventInfoAggregate` is an aggregation class that consolidates event information from multiple Data Acquisition System (DAS) units into a single unified view. It implements `IEventInfoAggregate` and serves to merge data from distributed recording modules that participate in the same test event, tracking metadata such as duration, sample counts, channel counts, and fault status across all participating units.
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### Properties
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| `EventId` | `string` | Test/event identifier |
|
|
| `EventDescription` | `string` | Human-readable event description |
|
|
| `DurationSeconds` | `double` | Event duration in seconds |
|
|
| `GUID` | `string` | Unique test identifier (string representation of GUID) |
|
|
| `HasBeenDownloaded` | `bool` | Indicates whether event data has been downloaded |
|
|
| `WasTriggered` | `bool` | Indicates whether the event was triggered |
|
|
| `NumberOfChannels` | `int` | Cumulative channel count across all modules |
|
|
| `NumberOfSamples` | `ulong` | Sample count per channel |
|
|
| `NumberOfBytes` | `ulong` | Total data size in bytes |
|
|
| `Faulted` | `bool` | Indicates any fault condition across aggregated units |
|
|
| `EventNumber` | `int` | Sequential event number |
|
|
|
|
### Constructor
|
|
|
|
```csharp
|
|
public EventInfoAggregate(DownloadReport.EventInfo newEvent)
|
|
```
|
|
Initializes the aggregate with the first event. Handles empty `Modules` collections gracefully by setting `DurationSeconds` and `NumberOfSamples` to 0. Registers the owning DAS unit in the internal index map.
|
|
|
|
### Methods
|
|
|
|
```csharp
|
|
public Slice.Control.Event GetEvent(bool bClear)
|
|
```
|
|
Returns the cached `Slice.Control.Event` instance. If `bClear` is `true`, clears the cached instance before returning (forcing recreation on next call).
|
|
|
|
```csharp
|
|
public Slice.Control.Event GetEvent()
|
|
```
|
|
Returns the cached `Slice.Control.Event` instance, creating it lazily if null.
|
|
|
|
```csharp
|
|
public int GetEventIndex(IDASCommunication idas)
|
|
```
|
|
Returns the event index associated with the specified DAS unit. Returns `-1` and logs an error if the DAS unit is not found in the index map.
|
|
|
|
```csharp
|
|
public List<IDASCommunication> GetDasList()
|
|
```
|
|
Returns the list of DAS units associated with this event. Lazily populated from the internal index dictionary keys.
|
|
|
|
```csharp
|
|
public void Add(IEventInfo newEvent)
|
|
```
|
|
Merges another event into this aggregate. Accumulates channel counts, ORs fault status, and takes minimum values for mismatched durations and sample counts. Logs warnings for any data mismatches but does not throw exceptions.
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
- **Byte Calculation**: `NumberOfBytes` is always calculated as `2 * NumberOfChannels * NumberOfSamples` (assumes 2 bytes per sample per channel).
|
|
- **Channel Accumulation**: `NumberOfChannels` is cumulative; each `Add()` call sums the new module's channel count.
|
|
- **Fault Aggregation**: `Faulted` is the logical OR of all aggregated events' fault status.
|
|
- **Mismatch Handling**: When durations or sample counts differ between aggregated events, the minimum value is retained.
|
|
- **Empty Modules Safety**: Constructor handles empty `Modules` collections without throwing (sets `DurationSeconds` and `NumberOfSamples` to 0).
|
|
- **Index Uniqueness**: `_eventIndices` uses indexer assignment to handle potential duplicate keys gracefully.
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### This Module Depends On
|
|
- `DTS.Common.Interface.DASFactory` — `IDASCommunication` interface
|
|
- `DTS.Common.Interface.DASFactory.Download` — `IEventInfo`, `DownloadReport.EventInfo`, `DASModule`
|
|
- `DTS.Common.Utilities.Logging` — `APILogger` for diagnostic logging
|
|
- `DTS.DASLib.Service` — `Slice.Control.Event` class
|
|
|
|
### Implementations
|
|
- Implements `IEventInfoAggregate` (interface not shown in source)
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **`Add()` lacks empty Modules guard**: Unlike the constructor, `Add()` accesses `newEvent.Modules[0]` without checking if `Modules` is empty, which will throw `ArgumentOutOfRangeException`.
|
|
|
|
2. **Mismatches are logged, not enforced**: The `Add()` method logs warnings for TestID, Description, GUID, EventNumber, and other mismatches but continues processing. Callers cannot detect mismatches programmatically.
|
|
|
|
3. **Silent data loss on mismatch**: When durations or sample counts don't match, the minimum is silently taken. The original values are lost and only a warning is logged.
|
|
|
|
4. **`GetEventIndex` returns -1 for missing keys**: Callers must check for -1 return value; no exception is thrown for unknown DAS units.
|
|
|
|
5. **Lazy initialization side effects**: `GetDasList()` and `GetEvent()` cache their results. The `GetEvent(bool bClear)` overload is the only way to reset the `Slice.Control.Event` cache.
|
|
|
|
6. **Historical bug fixes embedded**:
|
|
- Empty modules handling added for case 15575 (cable disconnect during download)
|
|
- Indexer assignment used instead of `.Add()` for case 44357 (duplicate key prevention) |