001package arez.annotations;
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 */
018public enum Priority
019{
020  /**
021   * Highest priority.
022   * This priority should be used when the reaction will dispose other reactive elements (and thus they
023   * need not be scheduled).
024   */
025  HIGHEST,
026  /**
027   * High priority.
028   * This priority should be used when the reaction will trigger many downstream reactions.
029   */
030  HIGH,
031  /**
032   * Normal priority.
033   */
034  NORMAL,
035  /**
036   * Low priority.
037   * Usually used to schedule observers that reflect state onto non-reactive
038   * application components. i.e. Observers that are used to build html views,
039   * perform network operations etc. These reactions are often at low priority
040   * to avoid recalculation of dependencies (i.e. {@link ComputableValue}s) triggering
041   * this reaction multiple times within a single reaction round.
042   */
043  LOW,
044  /**
045   * Lowest priority.
046   * This is low-priority reactions that reflect onto non-reactive applications. It is
047   * also used for (i.e. {@link ComputableValue}s) that may be unobserved when a {@link #LOW}
048   * priority reaction runs.
049   */
050  LOWEST,
051  /**
052   * Default priority.
053   * Use the value of the {@link ArezComponent#defaultPriority} specified at the component level or {@link #NORMAL}
054   * if for the value of {@link ArezComponent#defaultPriority}.
055   */
056  DEFAULT
057}