95 lines
5.7 KiB
Markdown
95 lines
5.7 KiB
Markdown
---
|
|
source_files:
|
|
- Common/DTS.Common.SerializationPlus/EventInfoAggregate.cs
|
|
generated_at: "2026-04-16T14:13:19.550350+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "342395eec4a038a1"
|
|
---
|
|
|
|
# Documentation: EventInfoAggregate
|
|
|
|
## 1. Purpose
|
|
|
|
`EventInfoAggregate` is an aggregate data structure that consolidates event information from multiple Data Acquisition System (DAS) devices/modules into a single unified view. It implements `IEventInfoAggregate` and serves as a central repository for event metadata during download operations, tracking properties like event identification, duration, channel counts, sample counts, and fault status across multiple hardware units that recorded the same event.
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### Properties
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| `EventId` | `string` | Identifier for the test/event. |
|
|
| `EventDescription` | `string` | Human-readable description of the event. |
|
|
| `DurationSeconds` | `double` | Total event duration in seconds (PreTriggerSeconds + PostTriggerSeconds). |
|
|
| `GUID` | `string` | Globally unique identifier for the test. |
|
|
| `HasBeenDownloaded` | `bool` | Indicates whether the event data has been downloaded. |
|
|
| `WasTriggered` | `bool` | Indicates whether the event was triggered. |
|
|
| `NumberOfChannels` | `int` | Total number of channels across all modules. |
|
|
| `NumberOfSamples` | `ulong` | Number of samples per channel. |
|
|
| `NumberOfBytes` | `ulong` | Calculated total bytes: `NumberOfSamples * NumberOfChannels * 2`. |
|
|
| `Faulted` | `bool` | Indicates if any module reported a fault condition. |
|
|
| `EventNumber` | `int` | Sequential event number identifier. |
|
|
|
|
### Methods
|
|
|
|
#### `EventInfoAggregate(DownloadReport.EventInfo newEvent)`
|
|
Constructor that initializes the aggregate from a single `DownloadReport.EventInfo`. Populates all properties and adds the first DAS module to the internal `_eventIndices` dictionary.
|
|
|
|
#### `void Add(IEventInfo newEvent)`
|
|
Merges additional event information from another module into this aggregate. Accumulates channel counts, recalculates `NumberOfBytes`, updates `Faulted` status, and adds the DAS to `_eventIndices`. Logs warnings for mismatched fields but does not throw exceptions.
|
|
|
|
#### `Slice.Control.Event GetEvent()`
|
|
Returns a lazily-instantiated `Slice.Control.Event` object, creating it if necessary.
|
|
|
|
#### `Slice.Control.Event GetEvent(bool bClear)`
|
|
Returns the `Slice.Control.Event` object. If `bClear` is `true`, resets the cached `_event` to null before returning (forcing recreation on next call).
|
|
|
|
#### `int GetEventIndex(IDASCommunication idas)`
|
|
Returns the event index for a specific DAS device. Returns `-1` and logs an error if the DAS is not found in `_eventIndices`.
|
|
|
|
#### `List<IDASCommunication> GetDasList()`
|
|
Returns a lazily-instantiated list of all DAS devices associated with this event. The list is cached after first creation.
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
- **Empty Modules Handling**: When `Modules` collection is empty, `DurationSeconds` and `NumberOfSamples` are set to `0` rather than throwing an exception.
|
|
- **Byte Calculation**: `NumberOfBytes` is always calculated as `2 * NumberOfChannels * NumberOfSamples` (assumes 2 bytes per sample per channel).
|
|
- **Fault Detection**: An event is considered faulted if `FaultFlags != 0` OR `FaultFlagsEx != 0` on any constituent module.
|
|
- **Event Index Dictionary**: `_eventIndices` is always initialized (readonly field) and maps `IDASCommunication` instances to their event numbers.
|
|
- **Minimum Value Resolution**: When merging events with mismatched `DurationSeconds` or `NumberOfSamples`, the minimum value is retained.
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### This module depends on:
|
|
- `System`, `System.Collections.Generic`, `System.Linq` (BCL)
|
|
- `DTS.Common.Interface.DASFactory` — provides `IDASCommunication`
|
|
- `DTS.Common.Interface.DASFactory.Download` — provides `DownloadReport.EventInfo`, `IEventInfo`, `DASModule`
|
|
- `DTS.Common.Utilities.Logging` — provides `APILogger`
|
|
- `DTS.DASLib.Service` — namespace import (specific usage unclear from source)
|
|
- `Slice.Control.Event` — external type instantiated in `GetEvent()` (assembly/source not specified in imports)
|
|
|
|
### What depends on this module:
|
|
- Not determinable from source alone. The `IEventInfoAggregate` interface suggests consumers depend on the interface rather than concrete implementation.
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **Silent Mismatch Handling**: The `Add()` method logs warnings for mismatched `TestID`, `Description`, `GUID`, `HasBeenDownloaded`, `WasTriggered`, and `EventNumber` values but **continues processing**. Callers are not notified of data integrity issues beyond log entries.
|
|
|
|
2. **Minimum Value Strategy**: When `DurationSeconds` or `NumberOfSamples` differ between modules being aggregated, the code silently takes the minimum value. This may result in data loss if larger values are correct.
|
|
|
|
3. **Empty Modules Edge Case**: The constructor guards against empty `Modules` collections (added per case 15575), but the `Add()` method **does not** — it accesses `newEvent.Modules[0]` without null/empty checks, which will throw `ArgumentOutOfRangeException` if `Modules` is empty.
|
|
|
|
4. **Lazy Initialization Side Effects**: `GetDasList()` and `GetEvent()` cache their results. The `_das` list is not invalidated when `Add()` is called, potentially returning stale data if `GetDasList()` was called before all `Add()` operations completed.
|
|
|
|
5. **Index Assignment for Duplicates**: `_eventIndices` uses indexer assignment (`_eventIndices[...] = value`) rather than `.Add()` to silently overwrite duplicate keys. This was added per case 44357 but means duplicate DAS entries are not detected or logged.
|
|
|
|
6. **Error Return Convention**: `GetEventIndex()` returns `-1` for missing keys rather than throwing an exception. Callers must check for this sentinel value. |