001package arez.spy;
002
003import arez.ComputableValue;
004import arez.Disposable;
005
006/**
007 * Enum to control scheduling priority of observers/reactions.
008 * Observers with higher priorities will react first. If observers have equal priorities then observers
009 * scheduled first will react first. Observers must not depend upon ComputableValue instances with
010 * a lower priority otherwise priority is ignored.
011 *
012 * <p>A user should be very careful when specifying a {@link #HIGH} priority as it is possible that
013 * the the reaction will be scheduled part way through the process of disposing and/or unlinking one-or-more
014 * components. Dispose reactions will often be scheduled with a higher priority but reactions unlinking disposed
015 * arez components from remaining arez components. In many cases this may mean invoking
016 * {@link Disposable#isDisposed(Object)} before accessing arez components.</p>
017 *
018 * @see arez.annotations.Priority
019 */
020public enum Priority
021{
022  /**
023   * Highest priority.
024   * This priority should be used when the reaction will dispose other reactive elements (and thus they
025   * need not be scheduled).
026   */
027  HIGHEST,
028  /**
029   * High priority.
030   * This priority should be used when the reaction will trigger many downstream reactions.
031   */
032  HIGH,
033  /**
034   * Normal priority if not otherwise specified.
035   */
036  NORMAL,
037  /**
038   * Low priority.
039   * Usually used to schedule observers that reflect state onto non-reactive
040   * application components. i.e. Observers that are used to build html views,
041   * perform network operations etc. These reactions are often at low priority
042   * to avoid recalculation of dependencies (i.e. {@link ComputableValue}s) triggering
043   * this reaction multiple times within a single reaction round.
044   */
045  LOW,
046  /**
047   * Lowest priority.
048   * This is low-priority reactions that reflect onto non-reactive applications. It is
049   * also used for (i.e. {@link ComputableValue}s) that may be unobserved when a {@link #LOW}
050   * priority reaction runs.
051   */
052  LOWEST
053}