Package ghidra.framework.task

Class GTaskManager

  • public class GTaskManager
extends java.lang.Object
    Class for managing a queue of tasks to be executed, one at a time, in priority order. All the tasks pertain to an UndoableDomainObject and transactions are created on the UndoableDomainObject so that tasks can operate on them.

    Tasks are organized into groups such that all tasks in a group will be completed before the tasks in the next group, regardless of priority. Within a group, task are ordered first by priority and then by the order in which they were added to the group. Groups are executed in the order that they are scheduled.

    All tasks within the same group are executed within the same transaction on the UndoableDomainObject. When all the tasks within a group are completed, the transaction is closed unless there is another group scheduled and that group does not specify that it should run in its own transaction.

    Suspending:
    The GTaskManager can be suspended. When suspended, any currently running task will continue to run, but no new or currently scheduled tasks will be executed until the GTaskManager is resumed. There is a special method, #runNextTaskEvenIfSuspended(), that will run the next scheduled task even if the GTaskManager is suspended.

    Yielding to Other Tasks:
    While running, a GTask can call the method waitForHigherPriorityTasks() on the GTaskManager, which will cause the the GTaskManager to run scheduled tasks (within the same group) that are a higher priority than the running task, effectively allowing the running task to yield until all higher priority tasks are executed.

    See Also:
    GTask, GTaskGroup

    • Constructor Detail

      • GTaskManager

        public GTaskManager​(UndoableDomainObject undoableDomainObject,
                    GThreadPool threadPool)
        Creates a new GTaskManager for an UndoableDomainObject
        Parameters:
        undoableDomainObject - the domainObject that tasks scheduled in this GTaskManager will operate upon.
        threadPool - the GThreadPool that will provide the threads that will be used to run tasks in this GTaskManager.

    • Method Detail

      • scheduleTask

        public GScheduledTask scheduleTask​(GTask task,
                                   int priority,
                                   boolean useCurrentGroup)
        Schedules a task to be run by this TaskManager. Tasks are run one at a time.
        Parameters:
        task - the task to be run.
        priority - the priority of the task. Lower numbers are run before higher numbers.
        useCurrentGroup - . If true, this task will be rolled into the current transaction group if one exists. If false, any open transaction will be closed and a new transaction will be opened before this task is run.

      • scheduleTask

        public void scheduleTask​(GTask task,
                         int priority,
                         java.lang.String groupName)
        Schedules a task to be run by this TaskManager within the group with the given group name. If a group already exists with the given name(either currently running or waiting), the task will be added to that group. Otherwise, a new group will be created with the given group name and the task will be placed in that group.
        Parameters:
        task - the task to be run.
        priority - the priority of the task. Lower numbers are run before higher numbers.
        groupName - . The name of the group that the task will be added to.

      • scheduleTaskGroup

        public void scheduleTaskGroup​(GTaskGroup group)
        Schedules a task group to run. Task groups are run in the order they are scheduled. They have the option of being executed in the current transaction (if it exists) or starting a new transaction.
        Parameters:
        group - the TaskGroup to be scheduled.

      • setSuspended

        public void setSuspended​(boolean b)
        Sets the suspended state of this task queue. While suspended, this task manager will not start any new tasks in its queue. Any currently running task will continue to run.
        Parameters:
        b - true to suspend this manager, false to resume executing new tasks.

      • runNextTaskEvenWhenSuspended

        public void runNextTaskEvenWhenSuspended()
        This method will cause the next scheduled task to run even though the task manager is suspended. Calling this method while the queue is not suspended has no effect because if not suspended, it will be busy (or have nothing to do)

      • addTaskListener

        public void addTaskListener​(GTaskListener listener)
        Adds a GTaskListener to be notified as tasks are completed.
        Parameters:
        listener - the listener to add

      • removeTaskListener

        public void removeTaskListener​(GTaskListener listener)
        Removes the given GTaskListener from this queue.
        Parameters:
        listener - the listener to remove.

      • isBusy

        public boolean isBusy()
        Returns true if this manager is running a task, or if suspended has additional tasks queued.
        Returns:
        true if this manager is running a task, or if suspended has additional tasks queued.

      • waitWhileBusy

        public boolean waitWhileBusy​(long timeoutMillis)

      • waitUntilBusy

        public boolean waitUntilBusy​(long timeoutMillis)

      • isRunning

        public boolean isRunning()
        Returns true if this manager is currently running a task. If not suspended, a GTaskManager will always be executing a task as long as there are tasks to execute. If suspended, a GTaskManager may have tasks scheduled, but may not be currently executing one.
        Returns:
        true if this manager is currently running a task.

      • waitForHigherPriorityTasks

        public void waitForHigherPriorityTasks()
        This methods is for currently running tasks to suspend and allow higher priority tasks (within the same task group) to complete before continuing. If called by any thread other than the thread that is currently executing a task for this queue, an exception will be thrown.
        Throws:
        java.lang.IllegalStateException - if this method is called from any thread not currently executing the current task for this queue.

      • getTaskResults

        public java.util.List<GTaskResult> getTaskResults()
        Returns a list of the most recent GTaskResults. The TaskManager only keeps the most recent N GTaskResults.
        Returns:
        the list of the most recent GTaskResults.

      • getScheduledTasks

        public java.util.List<GScheduledTask> getScheduledTasks()
        Returns a list of scheduled tasks for the currently running group.
        Returns:
        a list of scheduled tasks for the currently running group.

      • getDelayedTasks

        public java.util.List<GScheduledTask> getDelayedTasks()
        Returns a list of Tasks that are currently waiting for higher priority tasks.
        Returns:
        a list of Tasks that are currently waiting for higher priority tasks.

      • getRunningTask

        public GScheduledTask getRunningTask()
        Returns the currently running task, or null if no task is running.
        Returns:
        the currently running task;

      • getCurrentGroup

        public GTaskGroup getCurrentGroup()
        Returns the currently running group, or null if no group is running.
        Returns:
        the currently running group, or null if no group is running.

      • getScheduledGroups

        public java.util.List<GTaskGroup> getScheduledGroups()
        Returns a list of Groups that are waiting to run.
        Returns:
        a list of Groups that are waiting to run.

      • isSuspended

        public boolean isSuspended()
        Returns true if this GTaskManager is currently suspended.
        Returns:
        true if this GTaskManager is currently suspended.

      • cancelRunningGroup

        public void cancelRunningGroup​(GTaskGroup group)
        Cancels all tasks in the currently running group. Tasks in the group that have not yet started will never run and will immediately be put into the TaskResults list. The TaskMonitor for the currently running task will be cancelled, but the task will continue to run until it checks the monitor.
        Parameters:
        group - the group to be cancelled. It must match the currently running group or nothing will happen.

      • cancelAll

        public void cancelAll()
        Cancels all scheduled groups and tasks. The TaskMonitor for the currently running task will be cancelled, but the task will continue to run until it checks the monitor.