Merge pull request #41 from radix/eref

add an ERef object, like Haskell's IORef.

Author: radix

effect/ref.py

@@ -0,0 +1,73 @@
+from characteristic import attributes
+
+from ._base import Effect
+from ._dispatcher import TypeDispatcher
+from ._sync import sync_performer
+
+
+class Reference(object):
+    """
+    An effectful mutable variable, suitable for sharing between multiple
+    logical threads of execution, that can be read and modified in a purely
+    functional way.
+
+    Compare to Haskell's ``IORef`` or Clojure's ``atom``.
+    """
+
+    # TODO: Add modify_atomic that either uses a lock or a low-level
+    # compare-and-set operation.
+
+    def __init__(self, initial):
+        self._value = initial
+
+    def read(self):
+        """Return an Effect that results in the current value."""
+        return Effect(ReadReference(ref=self))
+
+    def modify(self, transformer):
+        """
+        Return an Effect that updates the value with ``fn(old_value)``.
+
+        This is not guaranteed to be linearizable if multiple threads are
+        modifying the reference at the same time.
+        """
+        return Effect(ModifyReference(ref=self, transformer=transformer))
+
+
+@attributes(['ref'])
+class ReadReference(object):
+    """Intent that gets a Reference's current value."""
+
+
+@attributes(['ref', 'transformer'])
+class ModifyReference(object):
+    """
+    Intent that modifies a Reference value in-place with a transformer func.
+
+    This intent is not necessarily linearizable if multiple threads are
+    modifying the same reference at the same time.
+    """
+
+
+@sync_performer
+def perform_read_reference(dispatcher, intent):
+    """Performer for :obj:`ReadReference`."""
+    return intent.ref._value
+
+
+@sync_performer
+def perform_modify_reference(dispatcher, intent):
+    """
+    Performer for :obj:`ModifyReference`.
+
+    This performer is not linearizable if multiple physical threads are
+    modifying the same reference at the same time.
+    """
+    new_value = intent.transformer(intent.ref._value)
+    intent.ref._value = new_value
+    return new_value
+
+
+reference_dispatcher = TypeDispatcher({
+    ReadReference: perform_read_reference,
+    ModifyReference: perform_modify_reference})

effect/test_ref.py

@@ -0,0 +1,42 @@
+from testtools import TestCase
+
+from ._base import Effect
+from ._sync import sync_perform
+from .ref import (
+    Reference, ModifyReference, ReadReference,
+    reference_dispatcher)
+
+
+class ReferenceTests(TestCase):
+    """Tests for :obj:`Reference`."""
+
+    def test_read(self):
+        """``read`` returns an Effect that represents the current value."""
+        ref = Reference('initial')
+        self.assertEqual(ref.read(), Effect(ReadReference(ref=ref)))
+
+    def test_modify(self):
+        """``modify`` returns an Effect that represents modification."""
+        ref = Reference(0)
+        transformer = lambda x: x + 1
+        eff = ref.modify(transformer)
+        self.assertEqual(eff,
+                         Effect(ModifyReference(ref=ref,
+                                                transformer=transformer)))
+
+    def test_perform_read(self):
+        """Performing the reading results in the current value."""
+        ref = Reference('initial')
+        result = sync_perform(reference_dispatcher, ref.read())
+        self.assertEqual(result, 'initial')
+
+    def test_perform_modify(self):
+        """
+        Performing the modification results in transforming the current value,
+        and also returns the new value.
+        """
+        ref = Reference(0)
+        transformer = lambda x: x + 1
+        result = sync_perform(reference_dispatcher, ref.modify(transformer))
+        self.assertEqual(result, 1)
+        self.assertEqual(sync_perform(reference_dispatcher, ref.read()), 1)