Package ghidra.framework.task

Class GTaskManager

java.lang.Object
ghidra.framework.task.GTaskManager
public class GTaskManager extends Object
Class for managing a queue of tasks to be executed, one at a time, in priority order. All the tasks pertain to an DomainObject and transactions are created on the DomainObject 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 DomainObject. 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, runNextTaskEvenWhenSuspended(), 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:

  • Constructor Details

    • GTaskManager

      public GTaskManager(DomainObject domainObject, GThreadPool threadPool)
      Creates a new GTaskManager for an DomainObject
      Parameters:
      domainObject - 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 Details

    • 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.
      Returns:
      scheduled task

    • scheduleTask

      public void scheduleTask(GTask task, int priority, 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:
      IllegalStateException - if this method is called from any thread not currently executing the current task for this queue.

    • getTaskResults

      public 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 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 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 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.