Abstract multi-segment message. More...
#include <Common.h>
Public Member Functions | |
| virtual | ~SegmentedMessageData ()=default |
| virtual size_t | numSegments () const =0 |
| Number of segments in the message. | |
| virtual Segment | segment (size_t idx) const =0 |
| Get a segment by index. Throws if the segment has been take()n. | |
| virtual std::unique_ptr< services::HostMemRegion > | take (size_t segIdx) |
| Optionally called by a backend once it has transmitted segment segIdx, to obtain ownership of the HostMem region backing it (e.g. | |
| size_t | totalSize () const |
| Total size across all segments. | |
| bool | empty () const |
| True if totalSize() == 0. | |
| virtual MessageData | toMessageData () const |
| Flatten all segments into a standard MessageData. | |
Detailed Description
Abstract multi-segment message.
Generated types subclass this to expose header + list segments without flattening into a contiguous buffer.
MessageData is the canonical flat, one-segment implementation of this interface. Other subclasses represent naturally segmented layouts.
Subclasses MUST own all data that their segments point to. Read and write APIs can hold the message across async boundaries / retries. Subclasses which hold data in HostMem regions must keep those regions alive for the lifetime of the message (e.g. by owning them as unique_ptr<HostMemRegion>) and point their segments' region at them. Subclasses which own their regions exclusively may override take() to hand them to the backend.
Constructor & Destructor Documentation
◆ ~SegmentedMessageData()
|
virtualdefault |
Member Function Documentation
◆ empty()
| bool SegmentedMessageData::empty | ( | ) | const |
◆ numSegments()
|
pure virtual |
Number of segments in the message.
Implemented in esi::MessageData, SerialCoordBurst, SerialCoordInput, and SerialCoordInput.
Referenced by toMessageData(), and totalSize().
◆ segment()
|
pure virtual |
Get a segment by index. Throws if the segment has been take()n.
Implemented in esi::MessageData, SerialCoordBurst, SerialCoordInput, and SerialCoordInput.
Referenced by toMessageData(), and totalSize().
◆ take()
|
virtual |
Optionally called by a backend once it has transmitted segment segIdx, to obtain ownership of the HostMem region backing it (e.g.
to re-use the region or return it to a pool).
Returns nullptr, leaving the segment accessible, if the segment isn't backed by a region or the message doesn't transfer region ownership. Otherwise, marks the segment as taken – after which segment(segIdx) (and thus anything which reads the whole message, such as toMessageData()) and further calls to take(segIdx) throw – and returns the region if no other untaken segment references it, or nullptr if some still do. Since several segments may share a region, a backend which calls take() on each segment as it is transmitted receives each region exactly once, after the last segment using it.
Since SegmentedMessageDataCursor reads segments via segment(), a backend must not take a segment which a cursor over the message can still reach, and must not take a segment it may need to retransmit. Any cursor (including one created after the take()) throws when it reaches a taken segment. Segment copies of a taken segment obtained before the take() are invalid: their data may point into a region which has been re-used.
The default implementation returns nullptr.
Reimplemented in SerialCoordInput.
Definition at line 87 of file Common.cpp.
◆ toMessageData()
|
virtual |
Flatten all segments into a standard MessageData.
Reimplemented in esi::MessageData.
Definition at line 61 of file Common.cpp.
References esi::Segment::data, numSegments(), segment(), esi::Segment::size, and totalSize().
Referenced by esi::detail::getMessageDataRef().
◆ totalSize()
| size_t SegmentedMessageData::totalSize | ( | ) | const |
Total size across all segments.
Definition at line 52 of file Common.cpp.
References numSegments(), segment(), and esi::Segment::size.
Referenced by empty(), and toMessageData().
The documentation for this class was generated from the following files:
- /home/runner/work/circt-www/circt-www/circt_src/lib/Dialect/ESI/runtime/cpp/include/esi/Common.h
- /home/runner/work/circt-www/circt-www/circt_src/lib/Dialect/ESI/runtime/cpp/lib/Common.cpp
Generated on for CIRCT by
1.15.0