Package jetbrains.mps.smodel

Class CancellableReadAction

  • All Implemented Interfaces:
    Runnable
    public abstract class CancellableReadAction
extends Object
implements Runnable
    EXPERIMENTAL FUNCTIONALITY, DON'T USE OUTSIDE OF MPS.

    IMPORTANT! Instances of the class are stateful and shall not be reused!

    Facilitates ModelAccess to cancel model read actions. Pass instance of this class instead of a regular Runnable to ModelAccess.runReadAction(Runnable) or ModelAccess.runReadInEDT(Runnable) to indicate the outcome of read action is not essential/vital and the action could get cancelled.
    Beware, ModelAccess implementation is not obliged to honour this kind of runnables. If it does, it sends cancel() request to all CancellableReadAction at its own discretion, usually when a write or command action comes up. Depending on ModelAccess implementation, it might not be reasonable to use CancellableReadAction from a thread that is dedicated to writes/commands (e.g. EDT) as there's no chance for cancellation then.

    Read action may get cancelled prior to start and therefore subclass may not get control at all. Subclasses shall check isCancelRequested() from time to time (as appropriate with respect to own safe locations) and stop execution as soon as possible once the flag has been noticed. Subclasses shall invoke confirmCancel() in case they terminate execution according to isCancelRequested() request, and shall not perform any special activities if they complete in a regular fashion.
    Right now there's no API to figure out cancellation/completion state of the action once it's over. The API might get added if a need arises. PLEASE don't try to guess internal state based on existing protected methods, introduce a dedicated, well-documented method instead.

    There's no counterpart to support Computable code that produces a value. Subclasses may declare own return value accessor with proper default value for the case read action had not been started at all.

    Since:
    2018.3

    • Constructor Detail

      • CancellableReadAction

        public CancellableReadAction()

    • Method Detail

      • cancel

        public final void cancel()
        This is what external code use to indicate its intention to stop execution of this read action

      • run

        public final void run()
        Specified by:
        run in interface Runnable

      • confirmCancel

        protected final void confirmCancel()
        Subclasses shall invoke in response to isCancelRequested() they intend to honour. Generally, it's the last call prior to return from execute() in case of cancellation. Don't invoke it in case of regular completion of execute().

      • isCancelRequested

        protected final boolean isCancelRequested()
        Note, this method shall not be used outside of execute() (i.e. it doesn't make sense for post-mortem analysis)
        Returns:
        true if external code issued a cancel request

      • execute

        protected abstract void execute()
        Override with model read activities, poll isCancelRequested() as appropriate