Requeue an already queued camera buffer: why it breaks acquisition

A rig of 12-16 GigE cameras runs for hours, then one camera drops off the network and only a power cycle brings it back. The log points at code trying to requeue a buffer that is already queued. Read that warning as naming the victim, not the culprit: the message describes a buffer lifecycle fault, but in a rig this size the usual trigger is an exhausted link that backs frames up, times out the fetches, and pushes an error path into queueing a buffer twice. This guide gives you the signature that separates a code bug from a bandwidth fault, the arithmetic that sizes the link for 12 cameras at 18 frames per burst, and the fixes in the order that makes them stick.

What "requeue an already queued buffer" means

GenICam acquisition runs on a fixed cycle. Your code announces a pool of buffers to the driver, the camera fills each one over the stream channel, and your code fetches each filled buffer, reads the pixels, then requeues it so the driver can fill it again. At any instant each buffer has exactly one owner: waiting in the driver's queue, in flight from the camera, or in your hands between fetch and requeue.

Requeueing a buffer that is still queued hands the driver the same memory twice. Two writes then race on one buffer, the driver's bookkeeping breaks, and most acquisition stacks log a warning and stop delivering frames. That dead stream is your disconnect: the control channel still answers pings and register reads, but no frames arrive, and many rigs only recover when a power cycle rebuilds the stream state.

Two pairing faults produce the warning directly:

• Double requeue: the same buffer is queued twice, for example once in the processing loop and once in a completion callback.
• Requeue without fetch: a timeout or error path queues the handle just in case, but the fetch never completed, so the buffer was never yours to return.

The mirror fault, a fetch that is never followed by a requeue, stays quiet at first and starves the pool until acquisitions time out with nothing delivered. The pairing rule is one line: every fetch is followed by exactly one requeue, and nothing else in the code queues a buffer. The same ownership discipline governs acquisition state as a whole, as in why a repeated start needs a stop first, and the frame list your code keeps between callbacks, as in bounding the frame queue and reusing frames.

Read the failure signature first

One table of clues settles which cause you have before anyone touches code.

The rig in question, random across cameras with 12-16 cameras through one switch into one PC, sits squarely in the right-hand column. Size the budget first; a pairing bug exposed by timeouts will keep returning until the link carries its burst.

Cause 1: a buffer is queued without being fetched

The deterministic case is a software bug, and a log finds it quickly. Log every queue and every fetch with the buffer identity, then check one invariant per buffer: queues must equal fetches exactly. Three patterns account for most hits:

• Some acquisition stacks return the buffer to the pool automatically on retrieval, so an explicit queue call in your code queues it a second time.
• The same buffer is requeued from two places, a callback and the main loop.
• A fetch with a short timeout fails, and the handler queues the handle anyway.

The fix is one owner. A single thread runs fetch, process, requeue; timeout and error paths skip the requeue; acquisition stops and every buffer is released before anything is reconfigured. In multi-camera rigs the same missing discipline can freeze acquisition across all cameras at once, which callbacks and buffer queues walks through camera by camera.

Cause 2: the link ran out before the code broke

Each GigE port moves at most 1 Gb/s of line rate, about 125 MB/s, before headers take their share. A switch forwards frames; it does not create capacity. Twelve cameras bursting together present their combined load to the one uplink into the PC, and when offered load exceeds capacity the switch drops frames. The camera's resend machinery covers the first losses, the driver's queue drains, your fetches time out, and the first code path that queues defensively now requeues a buffer the driver still owns. The requeue warning appears, and the disconnect follows.

The images tell the story first: horizontal missing bands in live images and blank frames from stream packet loss precede the drop. The knobs, in the order that pays:

• Packet size: set the largest value every element of the path supports, before acquisition starts.
• Per-camera cap: the GenICam DeviceLinkThroughputLimit feature limits the bytes per second one camera may put on the network, so a shared link can be divided on purpose.
• Host NIC: raise receive buffers and descriptors, ease interrupt moderation; the measured gains are in what a high-performance NIC driver changes.
• Absorb, don't hide: deeper buffers hold a short burst whose average still fits, as in burst capture faster than the link; no buffer depth survives a link that is undersized on average.

For the general case of several cameras per link, the multi-camera GigE bandwidth budget works the same division.

Worked example: 12 GigE cameras, 18 frames each, one 1 Gb/s uplink

Inputs, with their sources:

• 12 cameras, the rig's low end, each a GigE area scan camera feeding one switch with a single uplink to the storage PC.
• 18 frames per camera per trigger cycle, the rig's own burst count.
• 12 MP frames: a current 12 MP GigE camera such as the LS-CMR-0053 runs full resolution at 9 fps, which sets the per-camera pace used below.
• Mono, 8-bit pixels, one byte per pixel; raw color is also one byte per pixel, and decoded RGB would triple it.
• One 1 Gb/s uplink: 1,000 Mb/s ÷ 8 = 125 MB/s of line rate. MB means 1,000,000 bytes throughout.

The rule in words: drain time equals total bytes per cycle divided by the usable payload rate of the narrowest link, and a link is sized when that fits the cycle time with margin. Allow about 8% of line rate for headers, packet gaps and resends, which plans on 115 MB/s of payload per 1 Gb/s link.

The arithmetic:

• One frame: 12,000,000 pixels × 1 B = 12.0 MB.
• One camera per cycle: 18 × 12.0 MB = 216 MB.
• Twelve cameras per cycle: 12 × 216 MB = 2,592 MB, about 2.6 GB.
• Drain time: 2,592,000,000 B ÷ 115,000,000 B/s ≈ 22.5 s, with a perfect-line-rate floor of 2,592 MB ÷ 125 MB/s = 20.7 s.

Cross-check per port: at the camera's full-resolution 9 fps, one camera alone offers 12.0 MB × 9 = 108 MB/s = 864 Mb/s, which is 86% of a 1 Gb/s port before any overhead. Two such cameras cannot share one link; one alone leaves almost nothing for resends.

Decision, by cycle time:

• Cycle of 23 s or more: one 1 Gb/s uplink carries the burst. Pace the triggers and set DeviceLinkThroughputLimit so sustained load per link stays at or below about 70% of line rate, 700 Mb/s or 87.5 MB/s, keeping the margin that the 8% allowance assumes.
• Cycle between about 6 s and 23 s: split the cameras across four host ports at three cameras per port. Each port then carries 3 × 216 MB = 648 MB per cycle, which drains in 648 ÷ 115 ≈ 5.6 s.
• Cycle under about 6 s: the uplink needs 2,592 MB ÷ cycle time; at 5 s that is 518 MB/s, about 4.1 Gb/s, so move the narrowest path to 10GbE. A 10GbE port offers 1,250 MB/s of line rate, carries the burst in about 2.1 s at full rate, and runs a 5 s cycle at about 42% load.

At 16 cameras the same burst is 16 × 216 MB = 3,456 MB, about 3.5 GB, which needs roughly 30 s on one 1 Gb/s uplink, so the tier boundaries move up with camera count.

Fixes, in order

1. Write the budget down first: frames × pixels × bytes per pixel per camera, then per link, using the worked example above.
2. Set the packet size to the largest value every switch and NIC on the path supports, before acquisition starts; a link negotiating below 1 Gb/s refuses large packets, as in the packet size error below gigabit.
3. Set DeviceLinkThroughputLimit per camera so the sum per shared link stays at or below the 70% planning line.
4. Split the camera groups across host ports; the frame grabbers and PoE cards below are the parts that do it:

5. The LS-FGB-0004 adds four PoE Gigabit ports over PCIe x4, so PoE-capable cameras connect straight to the host, three per port, with no switch in between. The MV-GE1104 is a 4-port GigE frame grabber for the same layout, and the MV-GE2002P is a 2-port PoE NIC for smaller groups.
6. Where the cycle is tight, move the narrowest path itself to 10GbE:

7. The MV-GT2104 puts four copper 10GbE ports on the host. At a 5 s cycle the uplink needs 518 MB/s, about 42% of one such port, so a single port carries the whole rig's uplink with margin.
8. Tune the host NIC as the last knob: raise receive buffers and descriptors, ease interrupt moderation, then re-measure with the same counters.
9. Repair the pairing regardless of the network: one owner thread runs fetch, process, requeue, timeout paths skip the requeue, and every buffer is released before any reconfiguration.
10. Verify with counters: run a full shift, watch per-camera frame counters and resend counters, and timestamp the first and last frame of each burst to confirm the drain time the budget predicts.

Prevention checklist

• Budget every link before adding a camera: bytes per cycle = cameras × frames × pixels × bytes per pixel, with sustained load at or below 70% of line rate.
• Three cameras per 1 Gb/s host port for 12-camera bursts of this size; go 10GbE when the cycle drops under about 6 s.
• Packet size set at commissioning and rechecked after any switch or NIC change.
• Per-buffer logging of queue and fetch events, with an alarm when the counts diverge for any buffer.
• Announced buffers sized to the largest burst plus processing slack, 24-32 per camera for the 18-frame burst here.
• Error paths that release: stop acquisition and free every buffer before recovery, so a fault never needs a power cycle to clear.

New cameras and network cards land in that budget too; GigE Vision camera selection covers the bandwidth, cable and software checks that come with them.

Size the links first, then pick the parts that carry them:

If the tiers above leave you between two answers, send the frames per cycle, pixel count and cycle time through the contact page and we will run the budget with you. More network-side reads live on the systems topic page.