[jwrosewell]

Why

The performance options page listed the profiles but gave little help in choosing one, and called HighPerformance "generally not recommended, because it uses about as much memory as MaxPerformance". The C library's next release changes what HighPerformance and IP Intelligence Balanced hold:

• 51degrees-cxx#114 and #125: IP Intelligence HighPerformance loads only what the named properties read (loadRequiredPropertiesOnly), and Balanced holds the same whatever is named.
• 51degrees-cxx#135: Device Detection HighPerformance holds only the values and text the named properties read.
• All three are merged into the cxx rc and ship with its release candidate, 51degrees-cxx#137.

Change

• src/devicedetection/features/performanceoptions.md
  • The HighPerformance row says what it holds when some properties are named, and recommends it for a few properties at in-memory speed.
  • A new Choosing a profile section says when to use each profile: plentiful memory, every property, a few properties, a shared network location, or limited memory.
  • A new IP Intelligence profiles section says what HighPerformance and Balanced hold, with the measured memory and lookup times from cxx#114.
  • The link to the profile definitions points at the current code for Device Detection and IP Intelligence, rather than a June 2021 commit of the old file layout.
• src/devicedetection/cloudtoonpremise.md: the HighPerformance line no longer says it uses about as much memory as MaxPerformance, and links to the guidance.
• src/ipintelligence/algorithm.md: naming required properties is described under HighPerformance, not Balanced.
• src/productsummaries/hardwarebenchmarks.md: the same correction to the paragraph that described Balanced from version 4.5.98.

Sources checked

• The figures quoted come from the pull request bodies and runs they cite:
  • IP Intelligence: cxx#114, runs 42329419876, 42345282361 and 42328404429
  • Device Detection: cxx#135, run 42511841308
  • Every-property detections a second with Balanced: the existing hardware benchmarks
• No figure is quoted for anything not measured. That covers Device Detection lookup speed and start-up time before and after the change, and LowMemory or MaxPerformance in these runs.
• What each profile holds was read from the definitions and their comments on cxx rc at cf087785 (hash.c lines 307 to 401, ipi.c lines 192 to 290, ipi.h lines 455 to 505).
• The default profile and the PHP exception come from the specifications (device-detection-on-premise.md line 292, ip-intelligence-on-premise.md line 259). Those lines are carried by Say that PHP's start-up engine always uses MaxPerformance, and that Update Matched User Agent is on by default #307, which this is stacked on.
• The shared network location advice repeats automatic data file updates.

Not covered

• BalancedTemp is still not described. Its settings differ by engine (reuseTempFile is false for Device Detection and true for IP Intelligence). The profile setters in the C++ layer don't copy the temp file setting, so outside Go it behaves as Balanced. That needs a decision before it is documented.

Merge order

1. This is stacked on Say that PHP's start-up engine always uses MaxPerformance, and that Update Matched User Agent is on by default #307 and targets its branch. Once Say that PHP's start-up engine always uses MaxPerformance, and that Update Matched User Agent is on by default #307 merges into rc, retarget this to rc.
2. Hold it, as Say that PHP's start-up engine always uses MaxPerformance, and that Update Matched User Agent is on by default #307 is held, until the cxx release in DOC: fix mobile nav-tree overlapping doc content #137 and the language releases that carry it are out. Until then the pages would describe behaviour the released packages don't have.

[github-actions]

Documentation preview 👀