diff --git a/device-detection/fiftyone_devicedetection_onpremise/src/fiftyone_devicedetection_onpremise/swig_data.py b/device-detection/fiftyone_devicedetection_onpremise/src/fiftyone_devicedetection_onpremise/swig_data.py index 05f4cc0f..c4ea2a09 100644 --- a/device-detection/fiftyone_devicedetection_onpremise/src/fiftyone_devicedetection_onpremise/swig_data.py +++ b/device-detection/fiftyone_devicedetection_onpremise/src/fiftyone_devicedetection_onpremise/swig_data.py @@ -20,8 +20,6 @@ # such notice(s) shall fulfill the requirements of that article. # ********************************************************************* -import threading - from fiftyone_pipeline_engines.aspectdata import AspectData from fiftyone_pipeline_core.aspectproperty_value import AspectPropertyValue @@ -40,6 +38,15 @@ class SwigData(AspectData): """! Extention of AspectData made for retrieving results created by the SWIG wrapper of the On Premise Device Detection engine + + An instance reads its values from a results instance, the native results + of one request, which holds unmanaged memory. Multi-threaded access to a + results instance is not supported, for performance reasons, so an + instance is not safe to use from several threads at once. The caller is + responsible for thread-safe access, and either gives each thread its own + Flow Data, and so its own results instance, or coordinates its own + access, for example with a lock of its own around every read and around + close(). """ def __init__(self, flow_element, swig_results): @@ -58,11 +65,6 @@ def __init__(self, flow_element, swig_results): self.missing_property_service = OnPremiseMissingPropertyService() - # Reading a value writes into the native results, and the first read - # of a component can walk its graph, so one thread at a time reads - # this instance. - self._read_lock = threading.RLock() - def close(self): """! @@ -72,8 +74,7 @@ def close(self): exception. Closing the FlowData closes its results. """ - with self._read_lock: - self.swig_results = None + self.swig_results = None def get(self, key): @@ -84,13 +85,12 @@ def get(self, key): @returns mixed """ - with self._read_lock: - # Checked here, because AspectData.get turns an exception from - # get_internal into a missing property message. - if self.swig_results is None: - raise Exception(RESULTS_CLOSED) + # Checked here, because AspectData.get turns an exception from + # get_internal into a missing property message. + if self.swig_results is None: + raise Exception(RESULTS_CLOSED) - return super(SwigData, self).get(key) + return super(SwigData, self).get(key) def get_internal(self, key): diff --git a/device-detection/fiftyone_devicedetection_onpremise/tests/test_swig_data_threads.py b/device-detection/fiftyone_devicedetection_onpremise/tests/test_swig_data_threads.py index e07f169d..ee191828 100644 --- a/device-detection/fiftyone_devicedetection_onpremise/tests/test_swig_data_threads.py +++ b/device-detection/fiftyone_devicedetection_onpremise/tests/test_swig_data_threads.py @@ -21,59 +21,21 @@ # ********************************************************************* """ -One thread at a time reads a native results instance, because reading a value -writes into the results. +A results instance is not safe to use from several threads at once and the +caller is responsible for thread-safe access, so SwigData takes no lock and +its documentation says so. """ import threading -import time import unittest from fiftyone_devicedetection_onpremise.swig_data import SwigData -# How long a stand-in read takes, long enough that overlapping reads are seen. -READ_SECONDS = 0.02 -# The longest a test waits for another thread. -WAIT_SECONDS = 10 -# How long closing is given while a read holds the results. It must still be -# waiting at the end. -BLOCKED_SECONDS = 0.2 - -KEY = "deviceid" -VALUE = "1-2-3" - - -class OverlapCountingResults: - """Stands in for the native results and records how many reads overlap.""" - - def __init__(self): - self.guard = threading.Lock() - self.active = 0 - self.most_active = 0 - - def getDeviceId(self): - with self.guard: - self.active += 1 - self.most_active = max(self.most_active, self.active) - time.sleep(READ_SECONDS) - with self.guard: - self.active -= 1 - return "1-2-3" - - -class BlockingResults: - """Stands in for the native results with a read that waits to be let go, - so a test can act while the read is in progress.""" - - def __init__(self): - self.reading = threading.Event() - self.release = threading.Event() - - def getDeviceId(self): - self.reading.set() - self.release.wait(WAIT_SECONDS) - return "1-2-3" +# The types of the locks the threading module makes. +LOCK_TYPES = ( + type(threading.Lock()), type(threading.RLock()), + threading.Condition, threading.Semaphore) class FakeElement: @@ -83,50 +45,20 @@ class FakeElement: class SwigDataThreadTests(unittest.TestCase): - def test_reads_from_several_threads_do_not_overlap(self): - results = OverlapCountingResults() - data = SwigData(FakeElement(), results) - errors = [] - - def read(): - try: - for _ in range(3): - data.get("deviceid") - except Exception as e: - errors.append(e) - - threads = [threading.Thread(target=read) for _ in range(6)] - for thread in threads: - thread.start() - for thread in threads: - thread.join() - - self.assertEqual([], errors) - self.assertEqual(1, results.most_active) - - def test_closing_waits_for_a_read_in_progress(self): - results = BlockingResults() - data = SwigData(FakeElement(), results) - values = [] - reader = threading.Thread( - target=lambda: values.append(data.get(KEY))) - reader.start() - self.assertTrue(results.reading.wait(WAIT_SECONDS)) - - closer = threading.Thread(target=data.close) - closer.start() - closer.join(BLOCKED_SECONDS) - # The read holds the results, so closing waits for it. - self.assertTrue(closer.is_alive()) - - results.release.set() - reader.join(WAIT_SECONDS) - closer.join(WAIT_SECONDS) - self.assertFalse(closer.is_alive()) - self.assertEqual([VALUE], [value.value() for value in values]) - self.assertIsNone(data.swig_results) - with self.assertRaises(Exception): - data.get(KEY) + def test_the_documentation_says_the_caller_coordinates_threads(self): + text = " ".join(SwigData.__doc__.split()) + self.assertIn("unmanaged memory", text) + self.assertIn( + "Multi-threaded access to a results instance is not supported, " + "for performance reasons", text) + self.assertIn("not safe to use from several threads at once", text) + self.assertIn("caller is responsible for thread-safe access", text) + + def test_an_instance_holds_no_lock(self): + data = SwigData(FakeElement(), object()) + locks = [name for name, value in vars(data).items() + if isinstance(value, LOCK_TYPES)] + self.assertEqual([], locks) if __name__ == "__main__": diff --git a/ip-intelligence/fiftyone_ipintelligence_onpremise/src/fiftyone_ipintelligence_onpremise/swig_data.py b/ip-intelligence/fiftyone_ipintelligence_onpremise/src/fiftyone_ipintelligence_onpremise/swig_data.py index 2070a22b..5285aca6 100644 --- a/ip-intelligence/fiftyone_ipintelligence_onpremise/src/fiftyone_ipintelligence_onpremise/swig_data.py +++ b/ip-intelligence/fiftyone_ipintelligence_onpremise/src/fiftyone_ipintelligence_onpremise/swig_data.py @@ -21,7 +21,6 @@ # ********************************************************************* import math -import threading from decimal import Decimal, ROUND_HALF_UP from fiftyone_pipeline_engines.aspectdata import AspectData @@ -48,6 +47,15 @@ class SwigData(AspectData): """! Extension of AspectData made for retrieving results created by the SWIG wrapper of the On Premise IP Intelligence engine + + An instance reads its values from a results instance, the native results + of one request, which holds unmanaged memory. Multi-threaded access to a + results instance is not supported, for performance reasons, so an + instance is not safe to use from several threads at once. The caller is + responsible for thread-safe access, and either gives each thread its own + Flow Data, and so its own results instance, or coordinates its own + access, for example with a lock of its own around every read and around + close(). """ def __init__(self, flow_element, swig_results, echo_ip=None, echo_ipv6=None): @@ -72,11 +80,6 @@ def __init__(self, flow_element, swig_results, echo_ip=None, echo_ipv6=None): self.missing_property_service = OnPremiseMissingPropertyService() - # Reading a value writes into the native results, and the first read - # of a component can walk its graph, so one thread at a time reads - # this instance. - self._read_lock = threading.RLock() - def close(self): """! @@ -86,8 +89,7 @@ def close(self): exception. Closing the FlowData closes its results. """ - with self._read_lock: - self.swig_results = None + self.swig_results = None def get(self, key): @@ -98,13 +100,12 @@ def get(self, key): @returns mixed """ - with self._read_lock: - # Checked here, because AspectData.get turns an exception from - # get_internal into a missing property message. - if self.swig_results is None: - raise Exception(RESULTS_CLOSED) + # Checked here, because AspectData.get turns an exception from + # get_internal into a missing property message. + if self.swig_results is None: + raise Exception(RESULTS_CLOSED) - return super(SwigData, self).get(key) + return super(SwigData, self).get(key) @staticmethod def utf8_string_to_str(utf8_string): diff --git a/ip-intelligence/fiftyone_ipintelligence_onpremise/tests/test_swig_data_threads.py b/ip-intelligence/fiftyone_ipintelligence_onpremise/tests/test_swig_data_threads.py index c1476c43..b2d25c18 100644 --- a/ip-intelligence/fiftyone_ipintelligence_onpremise/tests/test_swig_data_threads.py +++ b/ip-intelligence/fiftyone_ipintelligence_onpremise/tests/test_swig_data_threads.py @@ -21,121 +21,44 @@ # ********************************************************************* """ -One thread at a time reads a native results instance, because reading a value -writes into the results. +A results instance is not safe to use from several threads at once and the +caller is responsible for thread-safe access, so SwigData takes no lock and +its documentation says so. """ import threading -import time import unittest from fiftyone_ipintelligence_onpremise.swig_data import SwigData -class Value: - - def hasValue(self): - return True - - def getValue(self): - return 5 - - -# How long a stand-in read takes, long enough that overlapping reads are seen. -READ_SECONDS = 0.02 -# The longest a test waits for another thread. -WAIT_SECONDS = 10 -# How long closing is given while a read holds the results. It must still be -# waiting at the end. -BLOCKED_SECONDS = 0.2 - -KEY = "count" -VALUE = 5 - - -class OverlapCountingResults: - """Stands in for the native results and records how many reads overlap.""" - - def __init__(self): - self.guard = threading.Lock() - self.active = 0 - self.most_active = 0 - - def getValueAsInteger(self, name): - with self.guard: - self.active += 1 - self.most_active = max(self.most_active, self.active) - time.sleep(READ_SECONDS) - with self.guard: - self.active -= 1 - return Value() - - -class BlockingResults: - """Stands in for the native results with a read that waits to be let go, - so a test can act while the read is in progress.""" - - def __init__(self): - self.reading = threading.Event() - self.release = threading.Event() - - def getValueAsInteger(self, name): - self.reading.set() - self.release.wait(WAIT_SECONDS) - return Value() +# The types of the locks the threading module makes. +LOCK_TYPES = ( + type(threading.Lock()), type(threading.RLock()), + threading.Condition, threading.Semaphore) class FakeElement: datakey = "ip" - properties = {"count": {"name": "Count", "type": "int"}} + properties = {} class SwigDataThreadTests(unittest.TestCase): - def test_reads_from_several_threads_do_not_overlap(self): - results = OverlapCountingResults() - data = SwigData(FakeElement(), results) - errors = [] - - def read(): - try: - for _ in range(3): - data.get("count") - except Exception as e: - errors.append(e) - - threads = [threading.Thread(target=read) for _ in range(6)] - for thread in threads: - thread.start() - for thread in threads: - thread.join() - - self.assertEqual([], errors) - self.assertEqual(1, results.most_active) - - def test_closing_waits_for_a_read_in_progress(self): - results = BlockingResults() - data = SwigData(FakeElement(), results) - values = [] - reader = threading.Thread( - target=lambda: values.append(data.get(KEY))) - reader.start() - self.assertTrue(results.reading.wait(WAIT_SECONDS)) - - closer = threading.Thread(target=data.close) - closer.start() - closer.join(BLOCKED_SECONDS) - # The read holds the results, so closing waits for it. - self.assertTrue(closer.is_alive()) - - results.release.set() - reader.join(WAIT_SECONDS) - closer.join(WAIT_SECONDS) - self.assertFalse(closer.is_alive()) - self.assertEqual([VALUE], [value.value() for value in values]) - self.assertIsNone(data.swig_results) - with self.assertRaises(Exception): - data.get(KEY) + def test_the_documentation_says_the_caller_coordinates_threads(self): + text = " ".join(SwigData.__doc__.split()) + self.assertIn("unmanaged memory", text) + self.assertIn( + "Multi-threaded access to a results instance is not supported, " + "for performance reasons", text) + self.assertIn("not safe to use from several threads at once", text) + self.assertIn("caller is responsible for thread-safe access", text) + + def test_an_instance_holds_no_lock(self): + data = SwigData(FakeElement(), object()) + locks = [name for name, value in vars(data).items() + if isinstance(value, LOCK_TYPES)] + self.assertEqual([], locks) if __name__ == "__main__": diff --git a/pipeline/fiftyone_pipeline_core/src/fiftyone_pipeline_core/elementdata.py b/pipeline/fiftyone_pipeline_core/src/fiftyone_pipeline_core/elementdata.py index 5ee546d3..3fd78a7c 100644 --- a/pipeline/fiftyone_pipeline_core/src/fiftyone_pipeline_core/elementdata.py +++ b/pipeline/fiftyone_pipeline_core/src/fiftyone_pipeline_core/elementdata.py @@ -31,9 +31,18 @@ class ElementData(object): Only the Flow Element that creates an instance writes it, so an instance does not need to be safe to write from several threads. A finished instance, once the Flow Element that writes it has finished, is safe to - read from several threads at once, such as the caller's own threads. An - instance that is written from several threads, or read while another - thread writes it, is not catered for. + read from several threads at once, such as the caller's own threads, as + its values are Python's own managed data and do not change once + written. An instance that is written from several threads, or read + while another thread writes it, is not catered for. + + The exception is Element Data that reads its values from a results + instance, such as an on-premise engine's, which holds unmanaged memory. + Multi-threaded access to a results instance is not supported, for + performance reasons, so such Element Data is not safe to use from + several threads at once. The caller is responsible for thread-safe + access, and either gives each thread its own Flow Data or coordinates + its own access. """ diff --git a/pipeline/fiftyone_pipeline_core/tests/test_elementdata_documentation.py b/pipeline/fiftyone_pipeline_core/tests/test_elementdata_documentation.py index 58d88e28..4b00ddb1 100644 --- a/pipeline/fiftyone_pipeline_core/tests/test_elementdata_documentation.py +++ b/pipeline/fiftyone_pipeline_core/tests/test_elementdata_documentation.py @@ -2,8 +2,10 @@ """ The documentation of Element Data says it is safe to read from several threads once the Flow Element that writes it has finished, and is not catered for when -written from several threads or read while another thread writes, as the -thread safety page of the specification requires. +written from several threads or read while another thread writes. It also says +that Element Data reading from a results instance, which holds unmanaged +memory, is not safe to use from several threads at once and that the caller is +responsible, as the thread safety page of the specification requires. """ import unittest @@ -21,6 +23,15 @@ def test_the_documentation_says_what_is_safe_with_threads(self): self.assertIn("written from several threads", text) self.assertIn("read while another thread writes", text) + def test_the_documentation_says_results_instances_are_the_exception(self): + text = " ".join(ElementData.__doc__.split()) + self.assertIn("results instance", text) + self.assertIn("unmanaged memory", text) + self.assertIn( + "Multi-threaded access to a results instance is not supported, " + "for performance reasons", text) + self.assertIn("caller is responsible for thread-safe access", text) + if __name__ == "__main__": unittest.main()