Add documentation of blocking and SetBlocking

Renamed the function to conform to naming convention.
Added CHANGELOG entry.

Author: AlexanderWells-diamond

CHANGELOG.rst

@@ -10,6 +10,10 @@ Versioning <https://semver.org/spec/v2.0.0.html>`_.
 Unreleased_
 -----------
 
+Added:
+
+- `Caput with callback <../../pull/98>`_
+
 Fixed:
 
 - `Passing a custom asyncio event loop into the AsyncioDispatcher causes methods to never run <../../pull/96>`_

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.

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'
 ]

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
 

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"""