From b7518fe17ebe24669f8a23bbad4ab236b4e986b5 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 18 Nov 2026 20:06:37 +0100 Subject: [PATCH] Live stills hold: packed only, frames seen by lookup, the stream waits when it is full As the Fable review proposed and the owner decided: - HoldArena is the only hold: the quarter of single-frame slots of 4c9cc4838 (visible_held, visible_max) is gone. A waiting frame is seen by lookup: the receiver keeps image number -> (weak_ptr, the message as it came), inserted in OnImage, erased when the frame is sent. JFJochReceiver:: GetWaitingImage (default: none) serialises it, its image in the hold, into the output while it holds the frame; GetLastWaitingImage gives the latest. JFJochReceiverService::GetImageFromBuffer (and the JPEG and TIFF routes) try the image buffer first, then the receiver; MaxImage takes the later of the two. ImageBuffer is unchanged. - The pre-pass holds up to PREPASS_MAX_IMAGES; it starts when the hold has no room for another frame (HoldArena::Full), on what is held. - One behaviour, no IsBlocking(): a frame that finds the hold full waits while the collection is not cancelled, and the pre-pass and the analysis drain it. No frame is lost at the hold; a source faster than the analysis loses frames at the card. An analysed frame that finds no slot to be written from within 2 s is still not written and counted (writer_queue_full), as before. Tests: ImagesVisibleDuringPrePass sees every waiting frame by lookup (and no slot in sending); BufferFullDuringPrePass, 200 frames into a 12-slot buffer, writes them all with no loss; CancelDuringRun gives frames until the pre-pass starts (the hold full) instead of relying on a six-frame pre-pass. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3 --- docs/JFJOCH_BROKER.md | 16 ++-- receiver/HoldArena.h | 11 +++ receiver/JFJochReceiver.h | 6 ++ receiver/JFJochReceiverRugnuxStills.cpp | 108 +++++++++++------------- receiver/JFJochReceiverRugnuxStills.h | 20 +++-- receiver/JFJochReceiverService.cpp | 15 +++- receiver/StillsGPUAnalysis.h | 3 +- tests/JFJochReceiverRugnuxTest.cpp | 36 +++++--- 8 files changed, 127 insertions(+), 88 deletions(-) diff --git a/docs/JFJOCH_BROKER.md b/docs/JFJOCH_BROKER.md index 43e3b31f4..a9b92b444 100644 --- a/docs/JFJOCH_BROKER.md +++ b/docs/JFJOCH_BROKER.md @@ -373,14 +373,14 @@ of its frames indexed, as with a small image buffer, a low hit rate or a chip wh cell given), the distance in the header is used for the whole run: this is a warning in the log and a note of the live status, and a wrong header distance then costs resolution and indexed frames. -Frames arriving during the pre-pass, or faster than the analysis, wait in at most half of the image buffer: a quarter -of its slots hold a frame each (it can be seen through the image routes while it waits), the rest of that half -holds frames as their compressed bytes, several to a slot; the other half is for the analysed frames, which go to -the writer from a slot each, with one slot kept per analysis thread. The receiver's image memory is the image -buffer (`image_buffer_MiB`, `-B` of `jfjoch_fpga_stills_test`) and nothing beside it. A frame that finds the waiting -half full is dropped and counted as for a full image buffer, so analysis slower than the frame rate costs frames, -not memory. Where the writer lags behind, the analysis -waits for slots to come back. A pre-pass that fails leaves the stated geometry and +Frames arriving during the pre-pass, or faster than the analysis, wait in at most half of the image buffer, as their +compressed bytes, several to a slot; the image routes serve them from there, by number, while they wait. The other +half is for the analysed frames, which go to the writer from a slot each, with one slot kept per analysis thread. +The pre-pass takes at most 2000 frames, fewer where the waiting half fills first: then it starts on what it has. The +receiver's image memory is the image buffer (`image_buffer_MiB`, `-B` of `jfjoch_fpga_stills_test`) and nothing +beside it. A frame that finds the waiting half full waits until the analysis has made room; frames are not dropped +there, so analysis slower than the frame rate holds the stream back, and frames are lost at the card. An analysed +frame that finds no slot to be written from within 2 s is not written and is counted as for a full image buffer. A pre-pass that fails leaves the stated geometry and mask in use. Where the start message cannot be sent after the pre-pass (no writer listening) or the analysis cannot be set up, the collection ends with that error, reported by `/status` and `/wait_till_done`, and the next `/start` runs as usual. diff --git a/receiver/HoldArena.h b/receiver/HoldArena.h index ebfeaf5b7..dab478bf0 100644 --- a/receiver/HoldArena.h +++ b/receiver/HoldArena.h @@ -83,6 +83,17 @@ public: return ret; } + // No room for a frame of this size without a frame going first + bool Full(size_t size) { + std::unique_lock ul(m); + if (current != SIZE_MAX && chunks[current].used + size <= slot_size) + return false; + for (const auto &c: chunks) + if (c.slot && c.frames == 0) + return false; + return static_cast(chunks.size()) >= max_slots; + } + int64_t GetSlotsUsed() { std::unique_lock ul(m); return static_cast(chunks.size()); diff --git a/receiver/JFJochReceiver.h b/receiver/JFJochReceiver.h index 693d52a83..a2ff2f651 100644 --- a/receiver/JFJochReceiver.h +++ b/receiver/JFJochReceiver.h @@ -131,6 +131,12 @@ public: virtual void SetSpotFindingSettings(const SpotFindingSettings &spot_finding_settings); virtual JFJochReceiverOutput GetFinalStatistics() const; + + // A frame the receiver holds and has not sent to the image buffer yet, serialised as the buffer serves an image; + // false where there is none of that number + virtual bool GetWaitingImage(std::vector &v, int64_t image_number) { return false; } + // The latest of them + virtual std::optional GetLastWaitingImage() { return {}; } }; diff --git a/receiver/JFJochReceiverRugnuxStills.cpp b/receiver/JFJochReceiverRugnuxStills.cpp index 809e0b64d..7d95f0520 100644 --- a/receiver/JFJochReceiverRugnuxStills.cpp +++ b/receiver/JFJochReceiverRugnuxStills.cpp @@ -54,9 +54,7 @@ void JFJochReceiverRugnuxStills::OnStart(std::chrono::steady_clock::time_point r const int64_t slots = image_buffer.GetStatus().total_slots; // The frames that wait take at most half of the image buffer; the other half is for those analysed, sent from // a slot each, and a slot is kept free for each analysis thread to send with - stills_keep_free = std::min(stills_nthreads, slots / 2); - visible_max = slots / 4; - hold_arena = std::make_unique(image_buffer, slots / 2 - visible_max, stills_keep_free, + hold_arena = std::make_unique(image_buffer, slots / 2, std::min(stills_nthreads, slots / 2), experiment.GetImageBufferLocationSize()); const StartMessage start = MakeStartMessage(experiment, pixel_mask, *az_int_mapping); // The frames are shown from their arrival, on the stated geometry until the pre-pass has decided its own. @@ -73,8 +71,8 @@ void JFJochReceiverRugnuxStills::OnStart(std::chrono::steady_clock::time_point r auto analysis = std::make_unique( analysis_experiment, pixel_mask, analysis_start, indexing_thread_pool, stills_nthreads, - // What the pre-pass holds and fits on; the frames beyond it wait in the image buffer as well. - slots / 2, logger, + // What the pre-pass holds and fits on, at most: the hold full starts it earlier (OnImage) + StillsGPUAnalysis::PREPASS_MAX_IMAGES, logger, *this, live_status, true, model, deadline_s, refine_solvent); std::unique_lock ul(stills_mutex); stills = std::move(analysis); @@ -92,66 +90,32 @@ void JFJochReceiverRugnuxStills::OnImage(uint32_t id, DataMessage &message, std: CountImage(message); const size_t size = message.image.GetCompressedSize(); - // Waits for the analysis in half of the image buffer at most: in a slot of its own, where it can be seen while it - // waits (it is not sent from there), in up to half of those slots; else as its compressed bytes, packed with - // others into the rest (HoldArena) + // Waits for the analysis as its compressed bytes, packed into at most half of the image buffer (HoldArena) auto held = std::make_shared(); - HoldArena::Region region; - const auto hold = [&] { - if (visible_held.fetch_add(1) < visible_max) { - held->slot = image_buffer.GetImageSlot(stills_keep_free); - if (held->slot) { - held->release = [this] { --visible_held; }; - return true; - } - } - --visible_held; - region = hold_arena->Allocate(size); - return region.data != nullptr; - }; - bool held_ok = hold(); - while (!held_ok && image_puller.IsBlocking() && !cancelled) { + // With the hold full, the frame waits: the pre-pass starts on what is held and the analysis drains it. No frame is + // lost here; a source faster than the analysis loses frames at the card. + HoldArena::Region region = hold_arena->Allocate(size); + if (!region.data || hold_arena->Full(size)) + stills->StartPrePass(); + while (!region.data && !cancelled) { std::this_thread::sleep_for(std::chrono::milliseconds(1)); - held_ok = hold(); + region = hold_arena->Allocate(size); } - if (!held_ok) { - writer_queue_full = true; + if (!region.data) return; - } + memcpy(region.data, message.image.GetCompressed(), size); + held->release = std::move(region.release); // Not chosen (stills_downsample): written as it came, without its analysis held->analyse = StillsImageSelected(message.number, downsample, StillsGPUAnalysis::PREPASS_MAX_IMAGES); held->message = message; StampImage(held->message, image_puller.GetCurrentFifoUtilization()); - - if (held->slot) { - // In the slot as an image without analysis; the analysis reads the image where it is in the slot. - auto slot_buffer = static_cast(held->slot->GetImage()); - CBORStream2Serializer serializer(slot_buffer, experiment.GetImageBufferLocationSize()); - held->message.image = CompressedImage(nullptr, 0, message.image.GetWidth(), message.image.GetHeight(), - message.image.GetMode(), message.image.GetCompressionAlgorithm(), - message.image.GetChannel()); - serializer.SerializeImage(held->message); - const size_t image_offset = serializer.GetImageAppendOffset(); - if (image_offset + size + 32 >= static_cast(experiment.GetImageBufferLocationSize())) { - logger.Error("Dropping image {} - metadata {} B + image {} B do not fit in buffer slot {} B", message.number, - image_offset, size, experiment.GetImageBufferLocationSize()); - return; - } - memcpy(slot_buffer + image_offset, message.image.GetCompressed(), size); - serializer.AppendImage(size); - held->message.image = CompressedImage(slot_buffer + image_offset, size, message.image.GetWidth(), - message.image.GetHeight(), message.image.GetMode(), - message.image.GetCompressionAlgorithm(), message.image.GetChannel()); - held->slot->SetImageNumber(message.number); - held->slot->SetImageSize(serializer.GetBufferSize()); - held->slot->SetIndexed(false); - held->slot->ReadyToSend(); - } else { - memcpy(region.data, message.image.GetCompressed(), size); - held->release = std::move(region.release); - held->message.image = CompressedImage(region.data, size, message.image.GetWidth(), message.image.GetHeight(), - message.image.GetMode(), message.image.GetCompressionAlgorithm(), - message.image.GetChannel()); + held->message.image = CompressedImage(region.data, size, message.image.GetWidth(), message.image.GetHeight(), + message.image.GetMode(), message.image.GetCompressionAlgorithm(), + message.image.GetChannel()); + { + // Seen while it waits (GetWaitingImage): the message as it came, as the analysis changes its own + std::unique_lock ul(waiting_mutex); + waiting[message.number] = Waiting{.held = held, .message = held->message}; } stills->Hold(held); } @@ -230,6 +194,10 @@ ZeroCopyReturnValue *JFJochReceiverRugnuxStills::AnalysedImageSlot() { } void JFJochReceiverRugnuxStills::SendAnalysedImage(DataMessage &message, const AzimuthalIntegrationProfile &profile) { + { + std::unique_lock ul(waiting_mutex); + waiting.erase(message.number); + } try { const auto status = image_buffer.GetSlotStatus(); message.receiver_buf_available = status.available_slots; @@ -257,6 +225,32 @@ void JFJochReceiverRugnuxStills::SendAnalysedImage(DataMessage &message, const A } } +std::optional JFJochReceiverRugnuxStills::GetLastWaitingImage() { + std::unique_lock ul(waiting_mutex); + // A frame the analysis let go of without sending it (a failed setup) is no longer there + while (!waiting.empty() && waiting.rbegin()->second.held.expired()) + waiting.erase(std::prev(waiting.end())); + if (waiting.empty()) + return {}; + return waiting.rbegin()->first; +} + +bool JFJochReceiverRugnuxStills::GetWaitingImage(std::vector &v, int64_t image_number) { + std::unique_lock ul(waiting_mutex); + const auto it = waiting.find(image_number); + if (it == waiting.end()) + return false; + // The frame's bytes in the hold stay while this copy is made + const auto held = it->second.held.lock(); + if (!held) + return false; + v.resize(experiment.GetImageBufferLocationSize()); + CBORStream2Serializer serializer(v.data(), v.size()); + serializer.SerializeImage(it->second.message); + v.resize(serializer.GetBufferSize()); + return true; +} + void JFJochReceiverRugnuxStills::AddToEndMessage(EndMessage &message) { JFJochReceiverStream::AddToEndMessage(message); // A failure here costs the end message the analysis only: it goes out as the receiver made it. diff --git a/receiver/JFJochReceiverRugnuxStills.h b/receiver/JFJochReceiverRugnuxStills.h index 57d5c09ee..395a4bbd3 100644 --- a/receiver/JFJochReceiverRugnuxStills.h +++ b/receiver/JFJochReceiverRugnuxStills.h @@ -3,6 +3,7 @@ #pragma once +#include #include #include #include @@ -22,13 +23,17 @@ class JFJochReceiverRugnuxStills : public JFJochReceiverStream, public StillsSin IndexerThreadPool *const indexing_thread_pool; const int64_t stills_nthreads; - // The frames waiting for the analysis take at most half of the image buffer's slots: a quarter as a slot each, - // the rest packed as their compressed bytes (a frame is a fraction of a slot: 1.5 MB of a 24 MB slot on a 9M - // detector, and the pre-pass holds every frame that arrives before it is over) - int64_t stills_keep_free = 0; // slots frames do not take, for the analysis threads to send with - int64_t visible_max = 0; - std::atomic visible_held = 0; + // The frames waiting for the analysis, packed as their compressed bytes into at most half of the image buffer's + // slots (a frame is a fraction of a slot: 1.5 MB of a 24 MB slot on a 9M detector, and the pre-pass holds every + // frame that arrives before it is over); a slot is kept free for each analysis thread to send with std::unique_ptr hold_arena; + // The frames waiting, by number, as they came, to be seen while they wait + struct Waiting { + std::weak_ptr held; + DataMessage message; + }; + std::mutex waiting_mutex; + std::map waiting; std::mutex stills_mutex; bool cut = false; @@ -64,4 +69,7 @@ public: IndexerThreadPool *indexing_thread_pool = nullptr, int64_t downsample = 1); ~JFJochReceiverRugnuxStills() override; + + bool GetWaitingImage(std::vector &v, int64_t image_number) override; + std::optional GetLastWaitingImage() override; }; diff --git a/receiver/JFJochReceiverService.cpp b/receiver/JFJochReceiverService.cpp index 50d9d892d..709849ba5 100644 --- a/receiver/JFJochReceiverService.cpp +++ b/receiver/JFJochReceiverService.cpp @@ -424,20 +424,29 @@ void JFJochReceiverService::GetStartMessageFromBuffer(std::vector &v) { image_buffer.GetStartMessage(v); } +// The image buffer, then the frames the receiver holds and has not sent yet (live stills, waiting for the analysis) bool JFJochReceiverService::GetImageFromBuffer(std::vector &v, int64_t image_number) { - return image_buffer.GetImage(v, image_number); + std::unique_lock ul(state_mutex); // the receiver is replaced at a start + if (receiver && image_number == ImageBuffer::MaxImage) { + const auto waiting = receiver->GetLastWaitingImage(); + if (waiting && *waiting > image_buffer.GetStatus().max_image_number) + image_number = *waiting; + } + if (image_buffer.GetImage(v, image_number)) + return true; + return receiver && (image_number != ImageBuffer::MaxImage) && receiver->GetWaitingImage(v, image_number); } std::string JFJochReceiverService::GetJPEGFromBuffer(const PreviewImageSettings &settings, int64_t image_number) { std::vector cbor_image; - if (!image_buffer.GetImage(cbor_image, image_number)) + if (!GetImageFromBuffer(cbor_image, image_number)) return {}; return preview_image.GenerateImage(settings, cbor_image); } std::string JFJochReceiverService::GetTIFFFromBuffer(int64_t image_number) { std::vector cbor_image; - if (!image_buffer.GetImage(cbor_image, image_number)) + if (!GetImageFromBuffer(cbor_image, image_number)) return {}; return PreviewImage::GenerateTIFF(cbor_image); } diff --git a/receiver/StillsGPUAnalysis.h b/receiver/StillsGPUAnalysis.h index fd85e4711..cbb2f3dc1 100644 --- a/receiver/StillsGPUAnalysis.h +++ b/receiver/StillsGPUAnalysis.h @@ -67,6 +67,8 @@ public: ~StillsGPUAnalysis(); void Hold(const std::shared_ptr &image); + // The frames held are all the pre-pass gets (the end of the collection, or no room for more): it starts on them + void StartPrePass(); // No frame comes after this: every frame is analysed before it returns. Throws if the setup after the pre-pass failed. void Finish(); // After Finish, once everything is written; without it the outcome is reported when the analysis goes @@ -159,7 +161,6 @@ private: void ModelThread(); void PublishModel(const ModelStepResult &result, const std::string &title); - void StartPrePass(); void PrePassThread(); void AnalysisThread(); void MergeThread(); diff --git a/tests/JFJochReceiverRugnuxTest.cpp b/tests/JFJochReceiverRugnuxTest.cpp index 167167439..bc3b7cc46 100644 --- a/tests/JFJochReceiverRugnuxTest.cpp +++ b/tests/JFJochReceiverRugnuxTest.cpp @@ -220,7 +220,7 @@ TEST_CASE("JFJochReceiverRugnux_Stills", "[JFJochReceiverRugnux]") { } TEST_CASE("JFJochReceiverRugnux_Stills_ImagesVisibleDuringPrePass", "[JFJochReceiverRugnux]") { - // A frame held for the pre-pass can be seen in the image buffer as it came, with a start message on the stated + // A frame held for the pre-pass can be seen through the image routes as it came, with a start message on the stated // geometry; once analysed, the copy with the analysis is the only one there. The writer gets each image once. Logger logger(Catch::getResultCapture().getCurrentTestName()); RegisterHDF5Filter(); @@ -263,7 +263,8 @@ TEST_CASE("JFJochReceiverRugnux_Stills_ImagesVisibleDuringPrePass", "[JFJochRece } REQUIRE(service.GetImageFromBuffer(cbor, ImageBuffer::MaxImage)); CHECK(CBORStream2Deserialize(cbor)->data_message->number == held - 1); - CHECK(service.GetImageBufferStatus().sending_slots == held); + // They wait in the receiver's hold, not as images of the buffer: none is in a slot to be sent + CHECK(service.GetImageBufferStatus().sending_slots == 0); // Nothing goes to the writer before the pre-pass CHECK(pusher.Events().empty()); @@ -348,10 +349,9 @@ TEST_CASE("JFJochReceiverRugnux_Stills_CancelDuringRun", "[JFJochReceiverRugnux] PixelMask mask(x); Stream stream(x, images); - // Twelve slots: the pre-pass ends on six frames, and the analysis starts with most of the run to come. - const size_t buffer_MiB = 12 * x.GetImageBufferLocationSize() / (1024 * 1024) + 1; - const int64_t given = 8; - stream.Frames(0, given); + // Four slots: the pre-pass starts once the two the frames wait in are full, and the analysis starts with most of + // the run to come. The frames are given one by one until it does. + const size_t buffer_MiB = 4 * x.GetImageBufferLocationSize() / (1024 * 1024) + 1; RecordingPusher pusher; AcquisitionDeviceGroup group; @@ -362,6 +362,16 @@ TEST_CASE("JFJochReceiverRugnux_Stills_CancelDuringRun", "[JFJochReceiverRugnux] service.RugnuxLive(true, std::make_shared(), 4, 60); service.Start(x, mask, nullptr, stream.puller); + int64_t given = 0; + const auto holding = [&] { + const auto s = service.GetRugnuxStatus(); + return !s.stills || s.stills->prepass == RugnuxLivePrePass::Holding; + }; + while (holding() && given < images - 1) { + stream.Frames(given++, 1); + std::this_thread::sleep_for(std::chrono::milliseconds(100)); + } + REQUIRE(given < images - 1); WaitForStatus(service, [](const RugnuxLiveSnapshot &s) { return s.stills && s.stills->prepass == RugnuxLivePrePass::Done && s.stills->images_analysed > 0; }); @@ -369,6 +379,7 @@ TEST_CASE("JFJochReceiverRugnux_Stills_CancelDuringRun", "[JFJochReceiverRugnux] const auto out = service.Stop(); CHECK(out.status.cancelled); + CHECK(out.status.images_collected == given); CHECK(out.status.images_sent == given); CHECK(pusher.Events() == std::vector{"start", "image", "end"}); const auto live = service.GetRugnuxStatus(); @@ -636,16 +647,16 @@ TEST_CASE("JFJochReceiverRugnux_Stills_ZMQWriterDown", "[JFJochReceiverRugnux]") } TEST_CASE("JFJochReceiverRugnux_Stills_BufferFullDuringPrePass", "[JFJochReceiverRugnux]") { - // Forty frames, all there before the pre-pass ends, and twelve slots in the image buffer. + // More frames than half of a twelve-slot image buffer holds, all there before the pre-pass ends. The frames that + // wait take at most half of the buffer: past it, a frame waits, the pre-pass starts on what is held and the + // analysis drains it. Every frame is written. Logger logger(Catch::getResultCapture().getCurrentTestName()); RegisterHDF5Filter(); - const int64_t images = 40; + const int64_t images = 200; DiffractionExperiment x = StillsExperiment(images); PixelMask mask(x); Stream stream(x, images); - stream.Frames(0, images); - stream.End(); const size_t buffer_MiB = 12 * x.GetImageBufferLocationSize() / (1024 * 1024) + 1; @@ -656,16 +667,15 @@ TEST_CASE("JFJochReceiverRugnux_Stills_BufferFullDuringPrePass", "[JFJochReceive service.Indexing(x.GetIndexingSettings()); service.RugnuxLive(true, nullptr, 4, 60); + stream.Frames(0, images); + stream.End(); service.Start(x, mask, nullptr, stream.puller); const auto out = service.Stop(); // No deadlock, and the end message goes out. CHECK(!out.status.cancelled); CHECK(pusher.Events() == std::vector{"start", "image", "end"}); - - // A frame that finds no free slot waits in a copy of its own, and is written. CHECK(out.status.images_collected == images); - CHECK(out.efficiency == 1.0f); CHECK(out.status.images_sent == images); CHECK(!out.writer_queue_full_warning); CHECK(out.scan_result.images.size() == out.status.images_sent);