Difference between poll_for_frames and wait_for_frames modes?

[mprat]

---

Required Info
Camera Model	D400
Firmware Version	5.09.14
Operating System & Version	Linux (Ubuntu 16)
Kernel Version (Linux Only)	4.4.38-tegra
Platform	NVIDIA Jetson
SDK Version	2
Language	C++

Issue Description

Reading through the API docs I was unclear about the difference / use cases between the mode of "poll_for_frames" and "wait_for_frames":

• poll_for_frames:

rs2::pipeline pipe;
pipe.start();
rs2::frameset frames = pipe.wait_for_frames();
rs2::frame frame = frames.first(RS2_STREAM_DEPTH);
if (frame)
    frame.get_data();

• wait_for_frames

rs2::pipeline pipe;
pipe.start();
rs2::frameset frames;
if (pipe.poll_for_frames(&frames))
{
    rs2::frame depth_frame = frames.first(RS2_STREAM_DEPTH);
    depth_frame.get_data();
}

My understanding is that wait_for_frames() is blocking with a timeout, and poll_for_frames you have to call yourself? If I'm using a rs2::frame_queue for processing my only option is to poll, correct? Am I misunderstanding something?

[dorodnic]

Hi @mprat
Your understanding is pretty much correct. Wait for frames will block until frame is available. Poll for frames will always return instantly. There is also try_wait_for_frames that will block but not throw on timeout but rather return false. frame_queue has similar wait_for_frame / poll_for_frame / try_wait_for_frame methods. Note frame instead of frames. These share the same semantics.
Usually, if you are implementing single producer / single consumer model wait_for_frame/s is best choice. If frame is available by the time your processing finish, it will return immediately, if not, it will block and free up CPU until next frame is available. If you have multiple producers (multi-camera setup) this model becomes problematic (since we don't have something like "wait for multiple objects" in the API). Then we recommend to switch to poll_for_frames, like in the multicam example.
If you do use poll_for_frames you should manually decide when to put the CPU to sleep and for how long, otherwise you can end up using 100% of a single core.
Let us know if you have follow-up questions

[mprat]

Does the "multi-cam" logic apply for multiple USB devices or for multiple camera streams from a single device as well?

If I know I want to process multiple streams (say RGB & depth) then do you still recommend the wait_for_frames model?

[dorodnic]

wait_for_frame/s works naturally with single pipeline / frame_queue object. If you have multiple, better use poll_for_frames to ensure you are not missing frames from one queue when waiting on another.

[mprat]

Multiple streams come from a single pipeline / frame_queue object, so sounds like wait_for_frames is the right way to go. Thanks!

[victorll998]

Hi @doronhi , my question is if I enable auto exposure priority, does it supersede wait_for_frameswhen exposure time is longer than time out period?