Repository navigation
Results instances are not thread-safe, so reads take no lock - #241
Merged
Merged
Conversation
SwigData in the Device Detection and IP Intelligence on-premise packages no longer holds a lock for each read of its native results or for close(). A results instance is not thread-safe, the caller is responsible for thread-safe access, and the class docstrings say so, with what to do instead. specifications#190 adds this as the "Results instances" section of the thread safety page. The thread tests asserted that reads never overlap and that close() waits for a read, which is no longer promised. They now check that the docstring says the caller coordinates threads and that an instance holds no lock. Closing results and reading afterwards is still tested with real data by test_flowdata_close_releases_results in both packages.
The ElementData docstring says a finished instance is safe to read from several threads at once, as its values are Python's own managed data and do not change once written. It now also says that Element Data reading from a results instance, which holds unmanaged memory, is the exception. Multi-threaded access to a results instance is not supported, for performance reasons, so the caller gives each thread its own Flow Data or coordinates its own access. The documentation test checks both, as lines 3 to 16 of the thread safety page in specifications#190 frame it.
Both SwigData docstrings now say a results instance holds unmanaged memory, and that multi-threaded access to it is not supported, for performance reasons, as lines 3 to 16 of the thread safety page in specifications#190 frame it. The caller either gives each thread its own Flow Data or coordinates its own access. That wording replaces the quotation of the rule against locking. The documentation tests check the new wording.
The ElementData docstring now says an instance is written only by the Flow Element that provides it, or the Flow Elements that share it, and only while they process, and that the Flow Data holding it is used by one thread at a time. Element Data that reads from a results instance takes no lock to make those reads safe. Both SwigData docstrings now follow the results instance section of the thread safety page in specifications#190 at a90ba516. Reading a value writes into the results instance, and the engine, its results instances and the instance take no lock to make those reads safe for several threads. The documentation tests check the new words.
test_an_instance_holds_no_lock in both on-premise packages looks only at the attributes of one SwigData instance. A lock at module level, on the engine or in AspectData would still pass it. Its docstring now says it is a smoke test, so no one reads more into it than that. The rule it checks is in the results instance section of the thread safety page, as merged in specifications 52e9b047.
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
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.
Problem
#80 made every read of an on-premise results instance, and closing one, take a lock, so that several threads could read one Flow Data's results at once. Every property read of every request pays for that lock, to protect the few callers that share a results instance between threads. On an Intel Mac, in 10 paired rounds against its parent, it cost 1.69 percent on the console benchmark and 1.86 percent on the web benchmark.
#80 merged into
rcon 14 November, the day after the last release (#114,main612aa28). No released version has taken this lock.What the specification says
specifications#190 rewrote the thread safety page and is merged into the specification's
rcas 52e9b047. The quotes below are fromrcat d79bbe3b, which holds it.Lines 198 to 212:
The same page also has these:
What changed
Five commits on
rc2373d14, the merge base:ElementDatadocstring in pipeline core.SwigDatadocstrings.Since the merge base,
rchas changed two of the six files: both on-premiseswig_data.pyfiles now defineOnPremiseMissingPropertyService. Those edits are in other parts of the files, and the head still merges cleanly into today'src(b64b480).In the code:
SwigDataindevice-detection/.../swig_data.pyandip-intelligence/.../swig_data.pytakes no lock. Thethreadingimport,_read_lockand thewithblocks inget()andclose()are gone, so those lines are back to how they were before Let one thread at a time read a native results instance #80.get()still raisesRESULTS_CLOSEDonce the results are closed.SwigDatadocstrings now say an instance reads from a results instance that references unmanaged memory, that multi-threaded access isn't supported, and that reading a value writes into it. They say nothing takes a lock for those reads, and that the caller either gives each thread its own Flow Data or wraps every read andclose()in a lock of its own.ElementDatadocstring inpipeline/.../elementdata.pysays who writes Element Data and when, that once written it's safe to read from several threads because its values are Python's own data, and that Element Data reading from a results instance is the exception.test_swig_data_threads.pyin both on-premise packages used to assert that reads never overlap and thatclose()waits for a read in progress. Both now check the docstring and that an instance holds nothreadinglock. The second test is only a smoke test: its docstring says a lock kept at module level, on the engine or inAspectDatawould get past it.test_elementdata_documentation.pychecks theElementDatawording.test_flowdata_close_releases_resultsin both packages, which this draft doesn't touch.Locks removed and kept
I searched every package's source on today's
rcforthreading.Lock,RLock,Condition,Semaphore,asyncio.Lockandwithblocks on a lock. Only the two locks on a results instance go.SwigData._read_lockswig_data.pyclose()SwigData._read_lockswig_data.pyclose()_properties_lockcloudengine.py_lockshare_usage.py_invariants_lockshare_usage.py_lockshare_usage_backoff.py_lockand each data file's update lockdatafile_update_service.py_loop_lock()did_client.pyNone of these guards a results instance. No Python code here locks Flow Data, Evidence or a parallel group, and
flowdata.pyonrctakes no lock.Released tests
The last release is
main612aa28. None of the three test files this draft changes shipped there, because #80 and #84 added them onrcon 14 November. So no released test is altered.The released tests that exercise this code are the
testsfolders of the three packages at 612aa28 (23 files for pipeline core, 8 for Device Detection on-premise, 7 for IP Intelligence on-premise). They were copied unaltered and run locally on Windows with Python 3.14.5 against 6e80124 and againstrc2373d14, with both native modules built fromcxx178371ac and the free Lite data files. Since 6e80124 only a test docstring has changed.rc2373d14The same eight tests fail on
rcwithout this draft, from otherrcchanges:test_setheader.pytest_get_response_header_name,test_devicedetection.pytest_excluded_property,test_missing_property_service_not_found_anywhere,test_missing_property_service_not_found_in_current,test_validate_data_falseandtest_validate_data_true,test_update_matched_useragent.pytest_turned_off_leaves_user_agents_empty, andtest_ipintelligence.pytest_missing_licence_key.Red and green
All three runs are on Ubuntu and Windows with Python 3.10 to 3.14, 10 Build and Test jobs each, no macOS. Each built a temporary branch with one workflow file added.
rc3abcb1c with this draft's three test files copied in unchanged. It failed in all 10 jobs. The Ubuntu Python 3.12 log shows the twotest_elementdata_documentation.pytests failing in pipeline core, and bothtest_swig_data_threads.pytests failing in each on-premise package, withtest_an_instance_holds_no_lockreportingLists differ: [] != ['_read_lock']. No other test failed in that job.The red still holds for today's
rc: no commit from 3abcb1c to b64b480 touches any of the six files, and bothswig_data.pyfiles there still haveimport threadingand_read_lock.Timing
c6883fe was timed against
rc2373d14 on an Intel Mac, with the same compiler, Python 3.13.18, the Lite data file andcxx178371ac, in 10 paired rounds with the order alternating. All 20 runs passed. The later commits change only docstrings and tests.rc, ms per detection (range)The web benchmark was faster in every round, so that gain is clear of the noise and wins back all of #80's 1.86 percent. The console ranges overlap, so that gain isn't.
What remains
ElementDatadocstring says Element Data isn't written once processed "apart from lazy properties". No Python Element Data has a lazy property yet, so that clause describes what the specification allows, not anything this package does today.Before you upgrade
Locking doesn't change for anyone upgrading from the last release. The lock only ever existed on
rc, from #80, and this draft removes it before it ships.What a released user does see is the documentation. The
SwigDatadocstrings in both on-premise packages, and theElementDatadocstring in pipeline core, now say that a results instance, and Element Data that reads from one, isn't safe to use from several threads at once, and that the caller is responsible for thread-safe access. Lines 219 to 221 require that statement, and lines 205 and 206 forbid the lock.If you use each Flow Data on one thread, change nothing. If you share one between threads, give each thread its own Flow Data, or wrap every read and the call to
close()in a lock of your own. The released packages didn't lock these reads either.