/interpreter/tags/reactive-pattern-matching/src/edu/vub/at/signals/SignalListener.java

http://ambienttalk.googlecode.com/ · Java · 127 lines · 10 code · 8 blank · 109 comment · 0 complexity · 6a3239921c3940e0dc0644807625eb4c MD5 · raw file

  1. /**
  2. * AmbientTalk/2 Project
  3. * SignalListener.java created on Jun 29, 2008 at 11:39:06 AM
  4. * (c) Programming Technology Lab, 2006 - 2007
  5. * Authors: Tom Van Cutsem & Stijn Mostinckx
  6. *
  7. * Permission is hereby granted, free of charge, to any person
  8. * obtaining a copy of this software and associated documentation
  9. * files (the "Software"), to deal in the Software without
  10. * restriction, including without limitation the rights to use,
  11. * copy, modify, merge, publish, distribute, sublicense, and/or
  12. * sell copies of the Software, and to permit persons to whom the
  13. * Software is furnished to do so, subject to the following
  14. * conditions:
  15. *
  16. * The above copyright notice and this permission notice shall be
  17. * included in all copies or substantial portions of the Software.
  18. *
  19. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  20. * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  21. * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  22. * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  23. * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  24. * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  25. * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  26. * OTHER DEALINGS IN THE SOFTWARE.
  27. */
  28. package edu.vub.at.signals;
  29. import java.util.EventListener;
  30. import edu.vub.at.objects.ATMessage;
  31. /**
  32. * SignalListener is an interface specifying which messages can be sent to any dependent
  33. * reactive computation. This interface provides methods to get the dependency height of
  34. * a dependent computation and update it if necessary.
  35. *
  36. * It also provides methods to unhook signal listeners, such that obsolete branches can
  37. * be removed from the dataflow graph.
  38. *
  39. * @author smostinc
  40. *
  41. */
  42. public interface SignalListener extends EventListener {
  43. /**
  44. * This method is called when one of the parent signal has been updated. The update
  45. * is not performed immediately when this method is invoked. There are two important
  46. * reasons for delaying the update: First of all, the parent signal may not belong
  47. * to the same event loop as its child. This is typically the case when modelling an
  48. * external event source such as time, key strokes, etc. In this case, the external
  49. * process should not be able to perform computation inside another event loop.
  50. * <p>
  51. * Even if parent and child signal belong to the same event loop, performing updates
  52. * of the child signal immediately after having updated the parent is not acceptable
  53. * since this may introduce update glitches. Consider the following example:
  54. * <pre><code>
  55. * (seconds < (seconds + 1))
  56. * </code></pre>
  57. * In the above example, both the comparison <code>&lt;</code> and the addition have
  58. * a direct dependency on the seconds signal. If dependent signals were immediately
  59. * updated, the comparison could be updated first, yielding <code>false</code>.
  60. * <p>
  61. * To avoid update glitches updates are not performed immediately, but are scheduled
  62. * to be performed when the dataflow engine reached the proper dependency height. As
  63. * such, update glitches can be avoided, since the dependency height of <code>&lt;
  64. * </code> in the example is 2 since it depends on <code>seconds</code> (height: 0)
  65. * and <code>seconds + 1</code> (height: 1).
  66. *
  67. * @param theParent the parent signal that has been updated
  68. * @param theUpdate the update that was propagated by that parent
  69. */
  70. public void scheduleUpdate(ATSignal theParent, ATMessage theUpdate);
  71. /**
  72. *
  73. * @param theParent
  74. * @param theUpdate
  75. * @return whether the listener wants to receive subsequent updates
  76. */
  77. public boolean performUpdate(ATSignal theParent, ATMessage theUpdate);
  78. /**
  79. * Every signal is assigned a dependency height, which determines the stratus where
  80. * the signal is situated in the dataflow graph. Updates are propagated first to the
  81. * signals with the lowest dependency height to ensure that signals are only updated
  82. * when the signals they depend on are guaranteed not to contain stale information.
  83. *
  84. * @return The dependency height of this signal listener.
  85. */
  86. public int dependencyHeight();
  87. /**
  88. * When the value of a behavior is set to another behavior, this behavior may have a
  89. * higher dependency height. Updates from the newly assigned value should henceforth
  90. * be propagated to all dependent computations. However, before these update can be
  91. * propagated the dependency graph should be stratified anew. There are essentially
  92. * two solutions: we can keep the strata static and establish a "delayed" dependency
  93. * between both behaviors, which implies that updates are only propagated during the
  94. * next turn. The alternative is to reassign the dependency heights of all dependent
  95. * signals, such that they are strictly greater than those of the new parent signal.
  96. * <p>
  97. * The latter approach is adopted in <b>FrTime</b>, as well as in AmbientTalk. This
  98. * method is used to update the dependency height of a signal listener. It verifies
  99. * whether the new height is strictly greater than its current dependency height and
  100. * transitively updates dependent signals if necessary.
  101. */
  102. public void updateDependencyHeight(int newDependencyHeight);
  103. /**
  104. * When constructing parts of the dataflow network inside a method which was invoked
  105. * with a signal as receiver or parameter, the constructed dataflow will implicitly
  106. * depend on the signals that were passed to the method as well. When these signals
  107. * change, the method will be executed anew, and the dataflow network that was built
  108. * during the previous invocation is no longer valid.
  109. * <p>
  110. * This observation is a generalization of the technique in <b>FrTime</b>, where the
  111. * problem only surfaces when using signals in conditions or in function position.
  112. * <p>
  113. * The unhook method is used to deconstruct the dataflow graph, whenever a signal on
  114. * which the signal listener depended implicitly is changed. The signal listener has
  115. * to ensure that updates will no longer be propagated to rule out already scheduled
  116. * update attempts.
  117. */
  118. public void unhook();
  119. }