Loading...
Searching...
No Matches
hydrocouplehelpers.h
Go to the documentation of this file.
1
28
29#ifndef HYDROCOUPLEHELPERS_H
30#define HYDROCOUPLEHELPERS_H
31
32#include "hydrocouple.h"
33
34#include <type_traits>
35
45#if defined(__GNUC__) || defined(__clang__)
46#pragma GCC visibility push(default)
47#endif
48
49namespace HydroCouple
50{
53 namespace Helpers
54 {
60 constexpr int64_t dataKindSize(DataKind kind)
61 {
62 switch (kind)
63 {
64 case DataKind::Int8:
65 case DataKind::UInt8:
66 case DataKind::Boolean: return 1;
67 case DataKind::Int16:
68 case DataKind::UInt16: return 2;
69 case DataKind::Int32:
71 case DataKind::Float32: return 4;
72 case DataKind::Int64:
74 case DataKind::Float64: return 8;
75 default: return 0;
76 }
77 }
78
79 namespace Detail
80 {
82 template <typename U>
84 {
85 if constexpr (std::is_same_v<U, bool>)
86 return DataKind::Boolean;
87 else if constexpr (std::is_integral_v<U>)
88 {
89 // By width and signedness, not by name: `long` and `long long` are
90 // distinct types of the same width, and which one int64_t names
91 // differs between platforms.
92 constexpr bool isSigned = std::is_signed_v<U>;
93 if constexpr (sizeof(U) == 1) return isSigned ? DataKind::Int8 : DataKind::UInt8;
94 else if constexpr (sizeof(U) == 2) return isSigned ? DataKind::Int16 : DataKind::UInt16;
95 else if constexpr (sizeof(U) == 4) return isSigned ? DataKind::Int32 : DataKind::UInt32;
96 else if constexpr (sizeof(U) == 8) return isSigned ? DataKind::Int64 : DataKind::UInt64;
97 else return DataKind::Unknown;
98 }
99 else if constexpr (std::is_same_v<U, float>)
100 return DataKind::Float32;
101 else if constexpr (std::is_same_v<U, double>)
102 return DataKind::Float64;
103 else if constexpr (std::is_same_v<U, std::string>)
104 return DataKind::String;
105 else
106 return DataKind::Unknown;
107 }
108 }
109
120 template <typename T>
122 {
125 static_assert(kind != DataKind::Unknown,
126 "HydroCouple::Helpers::DataKindOf<T>: T has no DataKind. Use an "
127 "integer, float, double, bool or std::string element type, or "
128 "describe opaque elements with makeOpaqueContiguous().");
129 };
130
137 [[nodiscard]] constexpr int64_t itemSize(const BufferDescriptor &d)
138 {
139 return d.itemSizeBytes > 0 ? d.itemSizeBytes : dataKindSize(d.kind);
140 }
141
148 [[nodiscard]] constexpr bool hasValidItemSize(const BufferDescriptor &d)
149 {
150 switch (d.kind)
151 {
152 case DataKind::Unknown: return false;
153 case DataKind::Opaque: return d.itemSizeBytes > 0;
154 case DataKind::String: return d.itemSizeBytes == 0 ||
155 d.itemSizeBytes == static_cast<int64_t>(sizeof(std::string));
156 default: return d.itemSizeBytes == 0 || d.itemSizeBytes == dataKindSize(d.kind);
157 }
158 }
159
164 [[nodiscard]] constexpr int64_t elementCount(const BufferDescriptor &d)
165 {
166 int64_t n = 1;
167 for (int32_t k = 0; k < d.rank; ++k)
168 n *= d.shape[k];
169 return n;
170 }
171
176 [[nodiscard]] constexpr bool isContiguous(const BufferDescriptor &d)
177 {
178 if (d.stridesBytes == nullptr)
179 return true;
180 int64_t expected = itemSize(d);
181 for (int32_t k = d.rank - 1; k >= 0; --k)
182 {
183 if (d.shape[k] != 1 && d.stridesBytes[k] != expected)
184 return false;
185 expected *= d.shape[k];
186 }
187 return true;
188 }
189
195 [[nodiscard]] constexpr int64_t byteOffset(const BufferDescriptor &d, std::span<const int64_t> index)
196 {
197 int64_t offset = 0;
198 if (d.stridesBytes == nullptr)
199 {
200 int64_t stride = itemSize(d);
201 for (int32_t k = d.rank - 1; k >= 0; --k)
202 {
203 offset += index[static_cast<size_t>(k)] * stride;
204 stride *= d.shape[k];
205 }
206 }
207 else
208 {
209 for (int32_t k = 0; k < d.rank; ++k)
210 offset += index[static_cast<size_t>(k)] * d.stridesBytes[k];
211 }
212 return offset;
213 }
214
219 [[nodiscard]] constexpr int64_t contiguousByteSize(const BufferDescriptor &d)
220 {
221 return elementCount(d) * itemSize(d);
222 }
223
230 [[nodiscard]] constexpr BufferDescriptor makeContiguous(void *data, DataKind kind, std::span<const int64_t> shape)
231 {
233 d.data = data;
234 d.kind = kind;
235 d.rank = static_cast<int32_t>(shape.size());
236 d.shape = shape.data();
237 d.itemSizeBytes = dataKindSize(kind);
238 return d;
239 }
240
247 [[nodiscard]] constexpr BufferDescriptor makeOpaqueContiguous(void *data, int64_t itemSizeBytes, std::span<const int64_t> shape)
248 {
250 d.data = data;
252 d.rank = static_cast<int32_t>(shape.size());
253 d.shape = shape.data();
254 d.itemSizeBytes = itemSizeBytes;
255 return d;
256 }
257
268 {
270
271 // An unrecoverable error can be detected in any state but the terminal
272 // one -- most visibly by a proxy whose peer dies while it rests at
273 // Updated or Done (IProxyModelComponent's failure semantics), or by a
274 // component whose arguments cannot even be read. Failed is therefore
275 // reachable from everything except Finished (and itself).
276 if (to == CS::Failed)
277 return from != CS::Finished && from != CS::Failed;
278
279 switch (from)
280 {
281 case CS::Created: return to == CS::Initializing;
282 case CS::Initializing: return to == CS::Initialized || to == CS::Failed;
283 case CS::Initialized: return to == CS::Validating || to == CS::Initializing ||
284 to == CS::Finishing;
285 case CS::Validating: return to == CS::Valid || to == CS::Invalid;
286 case CS::Valid: return to == CS::Preparing || to == CS::Validating ||
287 to == CS::Finishing;
288 case CS::Invalid: return to == CS::Validating || to == CS::Finishing;
289 case CS::Preparing: return to == CS::Updated || to == CS::Failed;
290 case CS::Updating: return to == CS::Updated || to == CS::Done ||
291 to == CS::WaitingForData || to == CS::Failed;
292 case CS::WaitingForData: return to == CS::Updating || to == CS::Failed;
293 case CS::Updated: return to == CS::Updating || to == CS::Checkpointing ||
294 to == CS::Finishing;
295 // Checkpointing returns to the state it was entered from (Updated or Done);
296 // a successful restoreState() always lands in Updated.
297 case CS::Checkpointing: return to == CS::Updated || to == CS::Done || to == CS::Failed;
298 case CS::Done: return to == CS::Checkpointing || to == CS::Finishing;
299 case CS::Finishing: return to == CS::Finished || to == CS::Created;
300 case CS::Finished: return false;
301 case CS::Failed: return to == CS::Initializing || to == CS::Finishing;
302 }
303 return false;
304 }
305
316 {
318
319 // As for components: a workflow can learn of an unrecoverable failure
320 // (a managed component's, a transport's) in any non-terminal state.
321 if (to == WS::Failed)
322 return from != WS::Finished && from != WS::Failed;
323
324 switch (from)
325 {
326 case WS::Created: return to == WS::Initializing;
327 case WS::Initializing: return to == WS::Initialized || to == WS::Failed;
328 case WS::Initialized: return to == WS::Validating || to == WS::Initializing ||
329 to == WS::Finishing;
330 case WS::Validating: return to == WS::Validated || to == WS::Invalid;
331 case WS::Validated: return to == WS::Preparing || to == WS::Validating ||
332 to == WS::Finishing;
333 // A composition with problems can be fixed and validated again, exactly
334 // as a component's Invalid can; only an unrecoverable error is Failed.
335 case WS::Invalid: return to == WS::Validating || to == WS::Finishing;
336 case WS::Preparing: return to == WS::Prepared || to == WS::Failed;
337 case WS::Prepared: return to == WS::Updating || to == WS::Finishing;
338 case WS::Updating: return to == WS::Updated || to == WS::Paused ||
339 to == WS::Done || to == WS::Failed;
340 case WS::Updated: return to == WS::Updating || to == WS::Finishing;
341 case WS::Paused: return to == WS::Updated || to == WS::Finishing;
342 case WS::Done: return to == WS::Finishing;
343 case WS::Finishing: return to == WS::Finished;
344 case WS::Finished: return false;
345 case WS::Failed: return to == WS::Initializing || to == WS::Finishing;
346 }
347 return false;
348 }
349
358 template <typename T>
359 [[nodiscard]] bool getValue(const IComponentDataItem &item, T &value, std::span<const int64_t> index)
360 {
361 std::vector<int64_t> ones(index.size(), 1);
362 const int64_t one = 1;
363 return item.getValuesInto(makeContiguous(&value, DataKindOf<T>::kind, std::span<const int64_t>(&one, 1)),
364 index, ones);
365 }
366
375 template <typename T>
376 [[nodiscard]] bool setValue(IComponentDataItem &item, const T &value, std::span<const int64_t> index)
377 {
378 std::vector<int64_t> ones(index.size(), 1);
379 const int64_t one = 1;
380 return item.setValuesFrom(makeContiguous(const_cast<T *>(&value), DataKindOf<T>::kind, std::span<const int64_t>(&one, 1)),
381 index, ones);
382 }
383
393 template <typename T>
394 [[nodiscard]] bool getValues(const IComponentDataItem &item, std::span<T> destination,
395 std::span<const int64_t> start, std::span<const int64_t> count)
396 {
397 return item.getValuesInto(makeContiguous(destination.data(), DataKindOf<T>::kind, count), start, count);
398 }
399
409 template <typename T>
410 [[nodiscard]] bool setValues(IComponentDataItem &item, std::span<const T> source,
411 std::span<const int64_t> start, std::span<const int64_t> count)
412 {
413 return item.setValuesFrom(makeContiguous(const_cast<T *>(source.data()), DataKindOf<T>::kind, count), start, count);
414 }
415 }
416}
417
418#if defined(__GNUC__) || defined(__clang__)
419#pragma GCC visibility pop
420#endif
421
422#endif // HYDROCOUPLEHELPERS_H
IComponentDataItem is a fundamental unit of data for a component.
Definition hydrocouple.h:1844
virtual bool getValuesInto(const BufferDescriptor &destination, std::span< const int64_t > start, std::span< const int64_t > count, std::string *message=nullptr) const =0
Copies a hyperslab of this item's values into a caller-described buffer.
virtual bool setValuesFrom(const BufferDescriptor &source, std::span< const int64_t > start, std::span< const int64_t > count, std::string *message=nullptr)=0
Copies values from a caller-described buffer into a hyperslab of this item.
ComponentStatus
HydroCouple::ComponentStatus is an enumerator that describes the status of a component over the cours...
Definition hydrocouple.h:707
WorkflowStatus
The WorkflowStatus enum describes the status of a workflow component over the course of its lifetime.
Definition hydrocouple.h:2801
Core interface definitions for the HydroCouple component-based modeling framework.
Definition hydrocouplehelpers.h:80
constexpr DataKind deduceDataKind()
The DataKind of a C++ element type, or Unknown when it has none.
Definition hydrocouplehelpers.h:83
Convenience helpers for the HydroCouple interface standard; non-normative except for the two lifecycl...
Definition hydrocouplehelpers.h:54
bool setValues(IComponentDataItem &item, std::span< const T > source, std::span< const int64_t > start, std::span< const int64_t > count)
Typed convenience: writes a hyperslab from a flat contiguous span in C order.
Definition hydrocouplehelpers.h:410
constexpr bool hasValidItemSize(const BufferDescriptor &d)
Checks that a descriptor's element size is consistent with its kind.
Definition hydrocouplehelpers.h:148
constexpr int64_t itemSize(const BufferDescriptor &d)
Size in bytes of one element of a descriptor: its itemSizeBytes when set, otherwise the kind's natura...
Definition hydrocouplehelpers.h:137
constexpr BufferDescriptor makeOpaqueContiguous(void *data, int64_t itemSizeBytes, std::span< const int64_t > shape)
Builds a C-contiguous host BufferDescriptor over opaque elements.
Definition hydrocouplehelpers.h:247
constexpr int64_t contiguousByteSize(const BufferDescriptor &d)
Total byte extent of a C-contiguous buffer of the descriptor's shape and kind.
Definition hydrocouplehelpers.h:219
constexpr bool isContiguous(const BufferDescriptor &d)
Checks whether a BufferDescriptor's layout is C-contiguous (row-major, packed).
Definition hydrocouplehelpers.h:176
constexpr int64_t dataKindSize(DataKind kind)
Size in bytes of one element of the given DataKind.
Definition hydrocouplehelpers.h:60
bool setValue(IComponentDataItem &item, const T &value, std::span< const int64_t > index)
Typed convenience: writes the single element at the given index of a data item.
Definition hydrocouplehelpers.h:376
bool getValues(const IComponentDataItem &item, std::span< T > destination, std::span< const int64_t > start, std::span< const int64_t > count)
Typed convenience: reads a hyperslab into a flat contiguous span in C order.
Definition hydrocouplehelpers.h:394
constexpr bool isValidComponentStatusTransition(IModelComponent::ComponentStatus from, IModelComponent::ComponentStatus to)
Encodes the normative component lifecycle state machine.
Definition hydrocouplehelpers.h:266
constexpr bool isValidWorkflowStatusTransition(IWorkflowComponent::WorkflowStatus from, IWorkflowComponent::WorkflowStatus to)
Encodes the normative workflow lifecycle state machine.
Definition hydrocouplehelpers.h:314
constexpr int64_t byteOffset(const BufferDescriptor &d, std::span< const int64_t > index)
Byte offset from a descriptor's base address of the element at the given index.
Definition hydrocouplehelpers.h:195
constexpr BufferDescriptor makeContiguous(void *data, DataKind kind, std::span< const int64_t > shape)
Builds a C-contiguous host BufferDescriptor.
Definition hydrocouplehelpers.h:230
constexpr int64_t elementCount(const BufferDescriptor &d)
Number of elements a BufferDescriptor describes (product of shape; 1 for rank 0).
Definition hydrocouplehelpers.h:164
bool getValue(const IComponentDataItem &item, T &value, std::span< const int64_t > index)
Typed convenience: reads the single element at the given index of a data item.
Definition hydrocouplehelpers.h:359
HydroCouple namespace contains the core interface specifications for the HydroCouple component-based ...
Definition hydrocouple.h:54
DataKind
DataKind identifies the element type of a typed data buffer.
Definition hydrocouple.h:199
@ Float32
float
Definition hydrocouple.h:209
@ String
std::string (host memory only)
Definition hydrocouple.h:212
@ Boolean
bool (stored one element per byte)
Definition hydrocouple.h:211
@ Int16
int16_t
Definition hydrocouple.h:203
@ Int8
int8_t
Definition hydrocouple.h:201
@ Unknown
No/unknown element type.
Definition hydrocouple.h:200
@ UInt16
uint16_t
Definition hydrocouple.h:204
@ UInt64
uint64_t
Definition hydrocouple.h:208
@ UInt8
uint8_t
Definition hydrocouple.h:202
@ Int32
int32_t
Definition hydrocouple.h:205
@ Float64
double
Definition hydrocouple.h:210
@ UInt32
uint32_t
Definition hydrocouple.h:206
@ Opaque
Implementation-defined bytes; meaning agreed out of band, size in BufferDescriptor::itemSizeBytes.
Definition hydrocouple.h:213
@ Int64
int64_t
Definition hydrocouple.h:207
BufferDescriptor describes a typed, possibly strided, possibly device-resident multi-dimensional arra...
Definition hydrocouple.h:279
DataKind kind
Element type.
Definition hydrocouple.h:281
const int64_t * stridesBytes
Byte step per dimension; nullptr => C-contiguous.
Definition hydrocouple.h:284
int64_t itemSizeBytes
Size of one element; 0 => the kind's natural size (illegal for Opaque).
Definition hydrocouple.h:285
int32_t rank
Number of dimensions; 0 denotes a scalar.
Definition hydrocouple.h:282
const int64_t * shape
Extent per dimension; length == rank.
Definition hydrocouple.h:283
void * data
Base address of element (0, 0, ..., 0).
Definition hydrocouple.h:280
DataKindOf maps a C++ type to its DataKind at compile time.
Definition hydrocouplehelpers.h:122
static constexpr DataKind kind
The DataKind of T.
Definition hydrocouplehelpers.h:124