Add DeviceConfiguration::disableImmediateMode to allow TPACKET_V3 on Linux - #2210
Open
MerinoSheep wants to merge 12 commits into
Open
Add DeviceConfiguration::disableImmediateMode to allow TPACKET_V3 on Linux#2210MerinoSheep wants to merge 12 commits into
DeviceConfiguration::disableImmediateMode to allow TPACKET_V3 on Linux#2210MerinoSheep wants to merge 12 commits into
Conversation
…Linux doOpen() unconditionally enables libpcap's immediate mode whenever the platform supports it, with no way to opt out. On Linux this forces libpcap to fall back from TPACKET_V3 to TPACKET_V2 and forces a non-blocking poll_timeout=0, turning the capture loop into a continuous busy-poll spin instead of an efficient blocking wakeup. Add a disableImmediateMode field (default false, preserving existing behavior) so callers can opt out of immediate mode and let libpcap use TPACKET_V3 with blocking, batched reads bounded by packetBufferTimeoutMs. A loopback benchmark comparing both modes under synthetic UDP flood showed ~14x lower capture-thread CPU usage and ~1.7x higher throughput with immediate mode disabled. Co-authored-by: Cursor <cursoragent@cursor.com>
Trim redundant restating of behavior in favor of the why: TPACKET_V2 vs TPACKET_V3 and busy-poll vs blocking wait tradeoffs. Co-authored-by: Cursor <cursoragent@cursor.com>
Lead with what the flag does, add a manpage reference, and match the style used by other DeviceConfiguration fields in this file. Co-authored-by: Cursor <cursoragent@cursor.com>
With immediate mode disabled, the packet buffer timeout controls delivery latency, but the platform default passed to pcap_set_timeout was -1 on Linux/Windows, which libpcap documents as unpredictable and which can delay delivery until a ring block fills. Fall back to 100 ms when packetBufferTimeoutMs is not set, drop the manpage URL from the doc comment, and fix a continuation-line alignment nit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The disableImmediateMode timeout fallback was unconditionally substituting 100ms whenever packetBufferTimeoutMs was unset, clobbering the small positive LIBPCAP_OPEN_LIVE_TIMEOUT already used on FreeBSD/macOS to work around a pcap_breakloop() bug. Only fall back to 100ms when the platform default is itself non-positive (Linux/Windows), leaving FreeBSD/macOS behavior unchanged regardless of disableImmediateMode. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## dev #2210 +/- ##
==========================================
+ Coverage 81.30% 83.01% +1.71%
==========================================
Files 319 328 +9
Lines 52180 59679 +7499
Branches 12124 12455 +331
==========================================
+ Hits 42423 49544 +7121
- Misses 7519 9143 +1624
+ Partials 2238 992 -1246
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Dimi1010
reviewed
Aug 5, 2026
Comment on lines
+321
to
+328
| /// Disable libpcap's "immediate mode", which PcapPlusPlus enables by default (where supported) for | ||
| /// minimal packet delivery latency. On Linux, immediate mode also forces a less efficient capture | ||
| /// path (TPACKET_V2 with non-blocking polling, instead of TPACKET_V3 with blocking, batched reads), | ||
| /// which can hurt throughput and CPU usage at high packet rates. Setting this to true trades some | ||
| /// added latency (up to packetBufferTimeoutMs, or 100 ms on Linux/Windows if not set) for those | ||
| /// throughput and CPU benefits. | ||
| /// Default value is false. | ||
| bool disableImmediateMode; |
Collaborator
There was a problem hiding this comment.
IMO, positive flags are easier to reason about than negative flags since the reader does not have to negate the condition. useImmediateMode defaulted to true might be easier to reason about when looking through the docs.
Also, I am wondering, do you think it would be better to have the flag be an enum instead of a bool?
Something like:
enum class BufferingMode
{
Default, // let the device decide (current behavior)
Immediate, // use immediate mode
Buffered // use buffered mode
}Default mode can also possibly have a graceful fallback to buffered, if immediate mode fails to enable for some reason.
Contributor
Author
There was a problem hiding this comment.
yeah good idea, Ill change
MerinoSheep
marked this pull request as ready for review
August 19, 2026 09:31
Use an enum class (Default/Immediate/Buffered) instead of a boolean flag, per review discussion.
Reformat throw to a single line per clang-format, and suppress a cppcheck knownConditionTrueFalse false positive on platforms where LIBPCAP_OPEN_LIVE_TIMEOUT is a positive constant.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PCAPPP_ENABLE_PCAP_IMMEDIATE_MODE, defaultOFF).DeviceConfiguration::disableImmediateMode(defaultfalse, backward compatible) to opt out and let Linux use TPACKET_V3.Changes
PcapLiveDevice.h: newdisableImmediateModefield + constructor param (defaultfalse).PcapLiveDevice.cpp:doOpen()skipspcap_set_immediate_mode()when set.packetBufferTimeoutMsis given (their default-1is unpredictable without immediate mode). FreeBSD/macOS keep their existingpcap_breakloop()workaround timeouts untouched.LiveDeviceTests.cpp:TestPcapLiveDeviceBlockingModenow also runs against adisableImmediateMode = trueconfig.