Use properties for Event.ok and Event.defused

jpgrayson · jpgrayson · commit 5962e7e5feee · 2016-03-28T16:30:15.000-04:00
New `Event.ok` and `Event.defused` properties wrap `Event._ok` and
`Event._defused` attributes. The key benefit is that doc strings now
can exist for `Event.ok` and `Event.defused`.

This is a performance-neutral change since all of the fast-paths still
use direct access to the `_ok` and `_defused` attributes.
diff --git a/src/simpy/core.py b/src/simpy/core.py
@@ -122,7 +122,7 @@ def run(self, until=None):
 
                 # Schedule the event with before all regular timeouts.
                 until = Event(self)
-                until.ok = True
+                until._ok = True
                 until._value = None
                 self.schedule(until, URGENT, at - self.now)
 
@@ -220,7 +220,7 @@ def step(self):
         for callback in callbacks:
             callback(event)
 
-        if not event.ok and not hasattr(event, 'defused'):
+        if not event._ok and not event.defused:
             # The event has failed and has not been defused. Crash the
             # environment.
             # Create a copy of the failure exception with a new traceback.
diff --git a/src/simpy/events.py b/src/simpy/events.py
@@ -51,8 +51,8 @@ class Event(object):
     examining *ok* and do further processing with the *value* it has produced.
 
     Failed events are never silently ignored and will raise an exception upon
-    being processed. If a callback handles an exception, it must set *defused*
-    flag to ``True`` to prevent this.
+    being processed. If a callback handles an exception, it must set :attr:`defused`
+    to ``True`` to prevent this.
 
     This class also implements ``__and__()`` (``&``) and ``__or__()`` (``|``).
     If you concatenate two events using one of these operators,
@@ -88,13 +88,43 @@ def processed(self):
         callbacks have been invoked)."""
         return self.callbacks is None
 
+    @property
+    def ok(self):
+        """Becomes ``True`` when the event has been triggered successfully.
+
+        A "successful" event is one triggered with :meth:`succeed()`.
+
+        """
+        return self._value is not PENDING and self._ok
+
+    @property
+    def defused(self):
+        """Becomes ``True`` when the failed event's exception is "defused".
+
+        When an event fails (i.e. with :meth:`fail()`), the failed event's
+        `value` is an exception that will be re-raised when the
+        :class:`~simpy.core.Environment` processes the event (i.e. in
+        :meth:`~simpy.core.Environment.step()`).
+
+        It is also possible for the failed event's exception to be defused by
+        setting :attr:`defused` to ``True`` from an event callback. Doing so
+        prevents the event's exception from being re-raised when the event is
+        processed by the :class:`~simpy.core.Environment`.
+
+        """
+        return not self.ok and hasattr(self, '_defused')
+
+    @defused.setter
+    def defused(self, value):
+        self._defused = True
+
     @property
     def value(self):
         """The value of the event if it is available.
 
         The value is available when the event has been triggered.
 
-        Raise a :exc:`AttributeError` if the value is not yet available.
+        Raises :exc:`AttributeError` if the value is not yet available.
 
         """
         if self._value is PENDING:
@@ -109,21 +139,21 @@ def trigger(self, event):
         chain reactions.
 
         """
-        self.ok = event.ok
+        self._ok = event._ok
         self._value = event._value
         self.env.schedule(self)
 
     def succeed(self, value=None):
         """Set the event's value, mark it as successful and schedule it for
         processing by the environment. Returns the event instance.
 
-        Raise a :exc:`RuntimeError` if this event has already been triggerd.
+        Raises :exc:`RuntimeError` if this event has already been triggerd.
 
         """
         if self._value is not PENDING:
             raise RuntimeError('%s has already been triggered' % self)
 
-        self.ok = True
+        self._ok = True
         self._value = value
         self.env.schedule(self)
         return self
@@ -132,16 +162,16 @@ def fail(self, exception):
         """Set *exception* as the events value, mark it as failed and schedule
         it for processing by the environment. Returns the event instance.
 
-        Raise a :exc:`ValueError` if *exception* is not an :exc:`Exception`.
+        Raises :exc:`ValueError` if *exception* is not an :exc:`Exception`.
 
-        Raise a :exc:`RuntimeError` if this event has already been triggered.
+        Raises :exc:`RuntimeError` if this event has already been triggered.
 
         """
         if self._value is not PENDING:
             raise RuntimeError('%s has already been triggered' % self)
         if not isinstance(exception, BaseException):
             raise ValueError('%s is not an exception.' % exception)
-        self.ok = False
+        self._ok = False
         self._value = exception
         self.env.schedule(self)
         return self
@@ -174,7 +204,7 @@ def __init__(self, env, delay, value=None):
         self.callbacks = []
         self._value = value
         self._delay = delay
-        self.ok = True
+        self._ok = True
         env.schedule(self, NORMAL, delay)
 
     def _desc(self):
@@ -200,7 +230,7 @@ def __init__(self, env, process):
         # The initialization events needs to be scheduled as urgent so that it
         # will be handled before interrupts. Otherwise a process whose
         # generator has not yet been started could be interrupted.
-        self.ok = True
+        self._ok = True
         env.schedule(self, URGENT)
 
 
@@ -217,8 +247,8 @@ def __init__(self, process, cause):
         self.env = process.env
         self.callbacks = [self._interrupt]
         self._value = Interrupt(cause)
-        self.ok = False
-        self.defused = True
+        self._ok = False
+        self._defused = True
 
         if process._value is not PENDING:
             raise RuntimeError('%s has terminated and cannot be interrupted.' %
@@ -328,12 +358,12 @@ def _resume(self, event):
         while True:
             # Get next event from process
             try:
-                if event.ok:
+                if event._ok:
                     event = self._generator.send(event._value)
                 else:
                     # The process has no choice but to handle the failed event
                     # (or fail itself).
-                    event.defused = True
+                    event._defused = True
 
                     # Create an exclusive copy of the exception for this
                     # process to prevent traceback modifications by other
@@ -347,14 +377,14 @@ def _resume(self, event):
             except StopIteration as e:
                 # Process has terminated.
                 event = None
-                self.ok = True
+                self._ok = True
                 self._value = e.args[0] if len(e.args) else None
                 self.env.schedule(self)
                 break
             except BaseException as e:
                 # Process has failed.
                 event = None
-                self.ok = False
+                self._ok = False
                 tb = e.__traceback__ if not PY2 else sys.exc_info()[2]
                 # Strip the frame of this function from the traceback as it
                 # does not add any useful information.
@@ -496,7 +526,7 @@ def _populate_value(self, value):
 
     def _build_value(self, event):
         """Build the value of this condition."""
-        if event.ok:
+        if event._ok:
             self._value = ConditionValue()
             self._populate_value(self._value)
 
@@ -508,9 +538,9 @@ def _check(self, event):
 
         self._count += 1
 
-        if not event.ok:
+        if not event._ok:
             # Abort if the event has failed.
-            event.defused = True
+            event._defused = True
             self.fail(event._value)
         elif self._evaluate(self._events, self._count):
             # The condition has been met. The _collect_values callback will
diff --git a/tests/test_exceptions.py b/tests/test_exceptions.py
@@ -167,7 +167,7 @@ def callback(event):
     event = env.event()
     event.callbacks.append(callback)
     event.fail(RuntimeError())
-    assert not hasattr(event, 'defused'), 'Event has been defused immediately'
+    assert not event.defused, 'Event has been defused immediately'
     env.run(until=1)
     assert event.defused, 'Event has not been defused'
 
@@ -185,7 +185,7 @@ def pem(env, event):
     env.process(pem(env, event))
     event.fail(RuntimeError())
 
-    assert not hasattr(event, 'defused'), 'Event has been defuseed immediately'
+    assert not event.defused, 'Event has been defused immediately'
     env.run(until=1)
     assert event.defused, 'Event has not been defused'
 
