diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 125aec3c..fa54fa57 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -10,6 +10,10 @@ Versioning `_. Unreleased_ ----------- +Added: + +- `Caput with callback <../../pull/98>`_ + Fixed: - `Passing a custom asyncio event loop into the AsyncioDispatcher causes methods to never run <../../pull/96>`_ diff --git a/docs/reference/api.rst b/docs/reference/api.rst index 9b311240..210fc425 100644 --- a/docs/reference/api.rst +++ b/docs/reference/api.rst @@ -228,6 +228,23 @@ Test Facilities`_ documentation for more details of each function. which don't change its value will be discarded. In particular this means that such updates don't call `validate` or `on_update`. + .. _blocking: + + `blocking` + ~~~~~~~~~~ + + Only available on OUT records. When set to `True` the record will set the + ``PACT`` field when processing is ongoing. This means that ``caput`` and + similar tools can correctly wait for processing to complete. + + This flag defaults to `False`, to retain compatibility with previous + versions. + + .. seealso:: + `SetBlocking` for configuring a global default blocking value + + + For all of these functions any EPICS database field can be assigned a value by passing it as a keyword argument for the corresponding field name (in upper case) or by assigning to the corresponding field of the returned record object. @@ -358,6 +375,17 @@ record creation function. prevent the accidential creation of records with the currently set device name. +.. function:: SetBlocking(blocking) + + This can be used to globally set the default `blocking` flag, which will + apply to all records created after this point. This allows blocking to be + easily set/unset when creating groups of records. + + This does not change the blocking value for any already created records. + + .. seealso:: + `blocking` for description of the flag + The following helper functions are useful when constructing links between records. diff --git a/softioc/builder.py b/softioc/builder.py index 2f64e75b..497e8b5e 100644 --- a/softioc/builder.py +++ b/softioc/builder.py @@ -9,7 +9,7 @@ from . import device, pythonSoftIoc # noqa # Re-export this so users only have to import the builder -from .device import set_blocking # noqa +from .device import SetBlocking # noqa PythonDevice = pythonSoftIoc.PythonDevice() @@ -305,5 +305,5 @@ def UnsetDevice(): 'LoadDatabase', 'SetDeviceName', 'UnsetDevice', # Device support functions - 'set_blocking' + 'SetBlocking' ] diff --git a/softioc/device.py b/softioc/device.py index 04f6047f..3c446922 100644 --- a/softioc/device.py +++ b/softioc/device.py @@ -27,8 +27,7 @@ # Default False to maintain behaviour from previous versions. blocking = False -# TODO: Docs and Tests for the Blocking feature -def set_blocking(val): +def SetBlocking(val): global blocking blocking = val diff --git a/tests/test_records.py b/tests/test_records.py index aa84d2ba..c54363a0 100644 --- a/tests/test_records.py +++ b/tests/test_records.py @@ -16,7 +16,7 @@ ) from softioc import asyncio_dispatcher, builder, softioc -from softioc.device import set_blocking +from softioc.device import SetBlocking # Test file for miscellaneous tests related to records @@ -185,6 +185,7 @@ def test_pini_always_on(): def validate_fixture_names(params): """Provide nice names for the out_records fixture in TestValidate class""" return params[0].__name__ + class TestValidate: """Tests related to the validate callback""" @@ -524,11 +525,11 @@ def test_blocking_creates_attributes(self): def test_blocking_global_flag_creates_attributes(self): """Test that the global blocking flag creates the expected attributes""" - set_blocking(True) + SetBlocking(True) bo1 = builder.boolOut("OUTREC1") self.check_record_blocking_attributes(bo1) - set_blocking(False) + SetBlocking(False) bo2 = builder.boolOut("OUTREC2") assert bo2._blocking is False @@ -576,6 +577,7 @@ async def blocking_update_func(new_val): log("CHILD: Received exit command, child exiting") + @requires_cothread def test_blocking_single_thread_multiple_calls(self): """Test that a blocking record correctly causes multiple caputs from a single thread to wait for the expected time"""