Loading...
Searching...
No Matches
events.hpp
Go to the documentation of this file.
1// SPDX-License-Identifier: Apache-2.0
2// Apache-2.0 relicensing authorized by the project rights holder, 2026-10-29.
3#pragma once
4
5#include <algorithm>
6#include <atomic>
7#include <chrono>
8#include <cstdint>
9#include <deque>
10#include <limits>
11#include <mutex>
12#include <string>
13#include <utility>
14#include <vector>
15
16namespace meshkit
17{
18
20enum class Severity { Info, Warning, Error };
27
41
52
59inline const char *statusName(RunStatus status) noexcept
60{
61 switch (status) {
63 return "running";
65 return "complete";
67 return "complete_with_exceptions";
69 return "resource_limit";
71 return "cancelled";
73 return "failed";
75 return "infeasible";
76 }
77 return "failed";
78}
79
81struct Counts {
82 // -1 means unavailable. Working vertices can include unused/dead slots;
83 // delivered vertices are supplied only once the assembled output is known.
94 std::int64_t vertices = -1, workingVertices = -1, triangles = -1, quads = -1;
101 std::int64_t inserted = -1, removed = -1;
106 std::int64_t cells() const noexcept
107 {
108 return triangles < 0 || quads < 0 ||
109 triangles > std::numeric_limits<std::int64_t>::max() - quads
110 ? -1
111 : triangles + quads;
112 }
113};
114
155
156// A per-job bounded, thread-safe mailbox. Producers never wait for a UI/event
157// loop and retain no QObject. Consumers poll/drain on their own thread.
158// Progress is coalesced; overflow is explicitly counted, never hidden.
169{
170public:
172 struct Batch {
173 std::vector<Event> events;
175 std::uint64_t dropped = 0; // cumulative non-coalesced overflow
176 };
177
183 explicit EventChannel(std::size_t capacity = 2048)
184 : capacity_(std::max<std::size_t>(capacity, 2)), job_(nextJob_.fetch_add(1)),
185 started_(Clock::now())
186 {
187 }
188
193 std::uint64_t job() const noexcept { return job_; }
194
206 void publish(Event event)
207 {
208 // Bounded strings as well as bounded row count. Callers supply UTF-8.
209 truncate(event.message, 8192);
210 truncate(event.stage, 256);
211 truncate(event.code, 128);
212 std::lock_guard<std::mutex> guard(mutex_);
213 if (finished_)
214 return;
215 event.job = job_;
216 event.sequence = ++sequence_;
217 event.elapsedMs =
218 std::chrono::duration_cast<std::chrono::milliseconds>(Clock::now() - started_).count();
219 if (event.percent >= 0) {
220 percent_ = std::max(percent_, std::clamp(event.percent, 0, 100));
221 event.percent = percent_;
222 }
223 if (event.kind == EventKind::Progress && !pending_.empty() &&
224 pending_.back().kind == EventKind::Progress && pending_.back().stage == event.stage) {
225 pending_.back() = std::move(event);
226 return;
227 }
228 if (pending_.size() == capacity_) {
229 const auto progress =
230 std::find_if(pending_.begin(), pending_.end(),
231 [](const Event &e) { return e.kind == EventKind::Progress; });
232 if (progress != pending_.end())
233 pending_.erase(progress);
234 else
235 pending_.pop_front();
236 ++dropped_;
237 }
238 finished_ = event.kind == EventKind::Completed;
239 pending_.push_back(std::move(event));
240 }
241
248 {
249 std::lock_guard<std::mutex> guard(mutex_);
250 Batch batch;
251 batch.dropped = dropped_;
252 batch.events.reserve(pending_.size());
253 while (!pending_.empty()) {
254 batch.events.push_back(std::move(pending_.front()));
255 pending_.pop_front();
256 }
257 return batch;
258 }
259
260private:
261 static void truncate(std::string &s, std::size_t limit)
262 {
263 if (s.size() <= limit)
264 return;
265 while (limit > 0 && (static_cast<unsigned char>(s[limit]) & 0xc0) == 0x80)
266 --limit;
267 s.resize(limit);
268 s += "…";
269 }
270 using Clock = std::chrono::steady_clock;
271 const std::size_t capacity_;
272 const std::uint64_t job_;
273 const Clock::time_point started_;
274 inline static std::atomic<std::uint64_t> nextJob_{1};
275 std::mutex mutex_;
276 std::deque<Event> pending_;
277 std::uint64_t sequence_ = 0, dropped_ = 0;
278 int percent_ = 0;
279 bool finished_ = false;
280};
281
282} // namespace meshkit
Batch drain()
Remove and return every pending event.
Definition events.hpp:247
EventChannel(std::size_t capacity=2048)
Create an empty channel with a new process-wide job id.
Definition events.hpp:183
void publish(Event event)
Queue one event without waiting for the consumer.
Definition events.hpp:206
std::uint64_t job() const noexcept
Id of this channel, unique among the channels created in the process.
Definition events.hpp:193
The Qt-free MeshKit library: job events and progress (meshkit::runtime), the neutral mesh model,...
RunStatus
Status of a running or finished operation (see statusName()).
Definition events.hpp:43
@ Infeasible
Input or policy cannot be satisfied; no result.
Definition events.hpp:50
@ ResourceLimit
Stopped at a resource cap or allocation failure; no result.
Definition events.hpp:47
@ Running
Still running; carried by intermediate events.
Definition events.hpp:44
@ CompleteWithExceptions
Finished with a result, but with recorded exceptions.
Definition events.hpp:46
@ Cancelled
Stopped because cancellation was requested; no result.
Definition events.hpp:48
@ Complete
Finished; every checked requirement holds.
Definition events.hpp:45
@ Failed
Stopped by an error such as an exception or I/O error; no result.
Definition events.hpp:49
Severity
Severity of an Event.
Definition events.hpp:20
@ Warning
Warning-level notification.
Definition events.hpp:20
@ Info
Informational; the default.
Definition events.hpp:20
@ Error
Failure; runJob() uses it for a Completed event of a job that did not complete.
Definition events.hpp:20
const char * statusName(RunStatus status) noexcept
Stable lower-case name of a status, as used by the Python bindings.
Definition events.hpp:59
EventKind
Kind of an Event.
Definition events.hpp:29
@ Completed
Final event of a job, carrying its final status; the channel ignores later events.
Definition events.hpp:29
@ StageCompleted
A stage has finished.
Definition events.hpp:29
@ Progress
Progress within a stage.
Definition events.hpp:29
@ Stage
A stage has started; Event::stage names it.
Definition events.hpp:29
@ Diagnostic
Informational diagnostic, e.g.
Definition events.hpp:29
Vertex and cell counters of an operation or event; -1 marks a value not available.
Definition events.hpp:81
std::int64_t vertices
Delivered vertex count, known once the output is assembled.
Definition events.hpp:94
std::int64_t workingVertices
Working vertex slots while meshing, unused and dead slots included.
Definition events.hpp:94
std::int64_t quads
Quadrilateral count.
Definition events.hpp:94
std::int64_t triangles
Triangle count (live triangles while refining, delivered triangles at the end).
Definition events.hpp:94
std::int64_t inserted
Vertices inserted by refinement so far.
Definition events.hpp:101
std::int64_t removed
Vertices removed by coarsening so far.
Definition events.hpp:101
std::int64_t cells() const noexcept
Total cell count.
Definition events.hpp:106
Events removed by one drain().
Definition events.hpp:172
std::vector< Event > events
Pending events in publication order, oldest first.
Definition events.hpp:173
std::uint64_t dropped
Total events evicted for overflow since the channel was constructed.
Definition events.hpp:175
One job notification passed through an EventChannel.
Definition events.hpp:121
std::string stage
Short stage name such as "triangulation" or "refinement"; publish() cuts longer text to at most 256 b...
Definition events.hpp:147
std::string message
Human-readable UTF-8 text; publish() cuts longer text to at most 8192 bytes plus "…".
Definition events.hpp:147
Counts counts
Counter snapshot when the event was produced.
Definition events.hpp:148
RunStatus status
RunStatus::Running for intermediate events; the final status on a Completed event.
Definition events.hpp:135
std::string code
Machine-readable code (the job's report code on Completed); publish() cuts longer text to at most 128...
Definition events.hpp:147
EventKind kind
Kind of notification.
Definition events.hpp:132
std::uint64_t job
Id of the publishing channel (EventChannel::job()); set by publish().
Definition events.hpp:129
int percent
Overall progress, 0 to 100, or negative (default -1) when not given.
Definition events.hpp:153
std::uint64_t sequence
Per-channel number, from 1, set by publish().
Definition events.hpp:129
Severity severity
Severity of the notification.
Definition events.hpp:133
std::int64_t elapsedMs
Milliseconds since the channel was constructed (steady clock); set by publish().
Definition events.hpp:131