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<HeldImage>, 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HVeDQrPqZ52Tp6rzzZGxf3
This commit is contained in:
leonarski_fandClaude Opus 5.5 committed 2026-11-18 20:06:37 +01:00
1 parent 4c9cc48382
commit b7518fe17e
8 files changed
+127 -88

No files matched your search

+8 -8
View File
@@ -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.
+11
View File
@@ -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<int64_t>(chunks.size()) >= max_slots;
}
int64_t GetSlotsUsed() {
std::unique_lock ul(m);
return static_cast<int64_t>(chunks.size());
+6
View File
@@ -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<uint8_t> &v, int64_t image_number) { return false; }
// The latest of them
virtual std::optional<int64_t> GetLastWaitingImage() { return {}; }
};
+51 -57
View File
@@ -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<HoldArena>(image_buffer, slots / 2 - visible_max, stills_keep_free,
hold_arena = std::make_unique<HoldArena>(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<StillsGPUAnalysis>(
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<HeldImage>();
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<uint8_t *>(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<size_t>(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<int64_t> 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<uint8_t> &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.
+14 -6
View File
@@ -3,6 +3,7 @@
#pragma once
#include <map>
#include <memory>
#include <mutex>
#include <string>
@@ -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<int64_t> 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<HoldArena> hold_arena;
// The frames waiting, by number, as they came, to be seen while they wait
struct Waiting {
std::weak_ptr<HeldImage> held;
DataMessage message;
};
std::mutex waiting_mutex;
std::map<int64_t, Waiting> 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<uint8_t> &v, int64_t image_number) override;
std::optional<int64_t> GetLastWaitingImage() override;
};
+12 -3
View File
@@ -424,20 +424,29 @@ void JFJochReceiverService::GetStartMessageFromBuffer(std::vector<uint8_t> &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<uint8_t> &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<uint8_t> 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<uint8_t> cbor_image;
if (!image_buffer.GetImage(cbor_image, image_number))
if (!GetImageFromBuffer(cbor_image, image_number))
return {};
return PreviewImage::GenerateTIFF(cbor_image);
}
+2 -1
View File
@@ -67,6 +67,8 @@ public:
~StillsGPUAnalysis();
void Hold(const std::shared_ptr<HeldImage> &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();
+23 -13
View File
@@ -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<RugnuxModel>(), 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<std::string>{"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<std::string>{"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);