summaryrefslogtreecommitdiff
path: root/modules/swarm/c++/run.hpp
diff options
context:
space:
mode:
authorClaudius "keldu" Holeksa <mail@keldu.de>2026-11-13 14:12:49 +0100
committerClaudius "keldu" Holeksa <mail@keldu.de>2026-11-13 14:12:49 +0100
commite821d617802ebbfff756844e4d9720342fc78a4e (patch)
tree1dcf33b84698b5074218e44ea491b77a9c23ee66 /modules/swarm/c++/run.hpp
parent0c0087ef9482634273ec1a23d3a915754f94926d (diff)
downloadlibs-lbm-e821d617802ebbfff756844e4d9720342fc78a4e.tar.gz
Swarm POCdev
Diffstat (limited to 'modules/swarm/c++/run.hpp')
-rw-r--r--modules/swarm/c++/run.hpp193
1 files changed, 193 insertions, 0 deletions
diff --git a/modules/swarm/c++/run.hpp b/modules/swarm/c++/run.hpp
new file mode 100644
index 0000000..b11bdf5
--- /dev/null
+++ b/modules/swarm/c++/run.hpp
@@ -0,0 +1,193 @@
+#pragma once
+
+#include "message.hpp"
+
+#include <kel/lbm/abstract/data.hpp>
+
+#include <cstdint>
+#include <string>
+#include <string_view>
+#include <string_view>
+
+/**
+ * Run identity.
+ *
+ * There is none in the library today: outputs land in a directory named after
+ * the example, with `<field>_<step>.vtk` inside, so a rerun silently
+ * overwrites the one before it and nothing records what parameters produced
+ * what. A swarm makes that worse rather than better -- several workers write
+ * concurrently, and a result arriving for an unknown run has to be refusable.
+ *
+ * A run id is therefore the first thing the orchestrator mints and the thing
+ * every transfer names. It is sortable, unique, and safe as a directory name:
+ *
+ * 20261112T094501Z-a3f19c
+ *
+ * UTC so that two machines agree, second resolution because runs are not
+ * started faster than that by a human, and six hex digits of entropy so that
+ * two started in the same second by a script still differ.
+ */
+namespace kel {
+namespace lbm {
+namespace sch {
+
+using RunDescriptor = Struct<
+ Member<String, "run_id">,
+ Member<String, "name">,
+ Member<UInt64, "created_at_ms">,
+ Member<String, "schema_version">,
+ /**
+ * Whether halo exchange was on. False until milestone 3, and recorded
+ * rather than assumed: slices run with clamped edges until then, so the
+ * seams are wrong, and a stored result should say so rather than leave
+ * someone to mistake a seam artefact for a solver bug years later.
+ */
+ Member<Bool, "halo_exchange">,
+ /// Opaque to everything here: whatever the admin endpoint was handed.
+ Member<String, "params_json">
+>;
+
+} // namespace sch
+
+namespace swarm {
+
+namespace impl {
+
+/**
+ * Civil date from a day count since 1970-01-01, by Howard Hinnant's algorithm.
+ *
+ * Deliberately not gmtime_r: this is pure arithmetic, so it needs no locale,
+ * no timezone database and no thread safety caveat, and it can be exercised
+ * directly in a test rather than through whatever the host libc happens to
+ * believe. It is also the same on a browser as on the orchestrator, which
+ * matters when both ends format or parse an id.
+ */
+struct civil_date {
+ int64_t year;
+ uint32_t month; ///< 1-12
+ uint32_t day; ///< 1-31
+};
+
+constexpr civil_date civil_from_days(int64_t z){
+ z += 719468;
+ const int64_t era = (z >= 0 ? z : z - 146096) / 146097;
+ const uint64_t doe = static_cast<uint64_t>(z - era * 146097);
+ const uint64_t yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
+ const int64_t y = static_cast<int64_t>(yoe) + era * 400;
+ const uint64_t doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+ const uint64_t mp = (5 * doy + 2) / 153;
+ const uint64_t d = doy - (153 * mp + 2) / 5 + 1;
+ const uint64_t m = mp + (mp < 10 ? 3 : -9);
+ return civil_date{y + (m <= 2 ? 1 : 0), static_cast<uint32_t>(m),
+ static_cast<uint32_t>(d)};
+}
+
+inline void append_padded(std::string &out, uint64_t value, uint32_t width){
+ char buffer[20];
+ uint32_t written = 0u;
+ do {
+ buffer[written++] = static_cast<char>('0' + (value % 10u));
+ value /= 10u;
+ } while(value > 0u and written < sizeof(buffer));
+
+ for(uint32_t i = written; i < width; ++i){
+ out.push_back('0');
+ }
+ for(uint32_t i = written; i > 0u; --i){
+ out.push_back(buffer[i - 1u]);
+ }
+}
+
+inline void append_hex(std::string &out, uint64_t value, uint32_t digits){
+ static constexpr char table[] = "0123456789abcdef";
+ for(uint32_t i = digits; i > 0u; --i){
+ out.push_back(table[(value >> ((i - 1u) * 4u)) & 0xfu]);
+ }
+}
+
+} // namespace impl
+
+/**
+ * Formats a run id.
+ *
+ * Takes the clock and the entropy rather than reading them, for the same
+ * reason the registry takes `now_ms`: a test can then pin both and assert the
+ * exact string, instead of matching a pattern and hoping.
+ *
+ * Only the low 24 bits of `entropy` are used.
+ */
+inline std::string make_run_id(uint64_t now_ms, uint64_t entropy){
+ const int64_t seconds = static_cast<int64_t>(now_ms / 1000u);
+ const int64_t days = (seconds >= 0) ? (seconds / 86400)
+ : ((seconds - 86399) / 86400);
+ const uint64_t secs_of_day = static_cast<uint64_t>(seconds - days * 86400);
+
+ const auto date = impl::civil_from_days(days);
+
+ std::string out;
+ out.reserve(24u);
+
+ impl::append_padded(out, static_cast<uint64_t>(date.year), 4u);
+ impl::append_padded(out, date.month, 2u);
+ impl::append_padded(out, date.day, 2u);
+ out.push_back('T');
+ impl::append_padded(out, secs_of_day / 3600u, 2u);
+ impl::append_padded(out, (secs_of_day / 60u) % 60u, 2u);
+ impl::append_padded(out, secs_of_day % 60u, 2u);
+ out.push_back('Z');
+ out.push_back('-');
+ impl::append_hex(out, entropy, 6u);
+
+ return out;
+}
+
+/**
+ * Whether a string could have come from make_run_id.
+ *
+ * The sink uses a run id as a directory name, so this is also the check that
+ * keeps a hostile id from escaping the storage root -- there is no '/', no
+ * '.', and nothing but a fixed shape of digits and hex.
+ */
+inline bool is_run_id(std::string_view id){
+ if(id.size() != 23u){
+ return false;
+ }
+
+ auto digit = [&](std::size_t i){ return id[i] >= '0' and id[i] <= '9'; };
+ auto hex = [&](std::size_t i){
+ return (id[i] >= '0' and id[i] <= '9') or (id[i] >= 'a' and id[i] <= 'f');
+ };
+
+ for(std::size_t i = 0u; i < 8u; ++i){
+ if(not digit(i)){ return false; }
+ }
+ if(id[8] != 'T'){ return false; }
+ for(std::size_t i = 9u; i < 15u; ++i){
+ if(not digit(i)){ return false; }
+ }
+ if(id[15] != 'Z'){ return false; }
+ if(id[16] != '-'){ return false; }
+ for(std::size_t i = 17u; i < 23u; ++i){
+ if(not hex(i)){ return false; }
+ }
+
+ return true;
+}
+
+} // namespace swarm
+
+namespace sch {
+
+using MsgRunStart = Envelope<Member<RunDescriptor, "run">>;
+using MsgRunEnd = Envelope<Member<String, "run_id">, Member<String, "outcome">>;
+
+} // namespace sch
+
+namespace run_outcome {
+inline constexpr std::string_view finished = "finished";
+inline constexpr std::string_view cancelled = "cancelled";
+inline constexpr std::string_view failed = "failed";
+} // namespace run_outcome
+
+} // namespace lbm
+} // namespace kel