Skip to content

Task Controllers API

When you add a task to the Macro Studio engine, it returns a controller object. You use this controller inside your task function to manage its execution state and interact with the system.

macro_studio.Controller

Python
Controller(controller: TaskController)

Provides an API for interacting with and controlling a single task.

This class acts as a handle for tasks registered with the MacroStudio engine, allowing them to query variables, log messages, and control their own lifecycle (pause, resume, stop, restart) or that of other tasks. An instance of this class is typically passed as the first argument to task functions.

Initializes a TaskContext instance.

Parameters:

Name Type Description Default
controller TaskController

The internal TaskController managing this task.

 required

Attributes

repeat property writable

Python
repeat: bool

Represents whether the task should automatically restart upon finishing.

Returns:

Type Description
bool

True if the task is set to repeat, False otherwise.

display_name property writable

Python
display_name: str

Gets or sets the display name of the task.

If None is provided, the function's original name will be used as the display name.

Notes

This name is used purely for display in the UI, not for task lookup.

Returns:

Type Description
str

The current display name of the task.

is_paused property

Python
is_paused: bool

Checks if the task is currently in a paused or interrupted state.

Returns:

Type Description
bool

`Trueif the task is paused or interrupted,False`` otherwise.

is_interrupted property

Python
is_interrupted: bool

Checks if the task is currently in an interrupted state.

An interrupted task has had its execution flow broken (e.g., by TaskInterruptedException) to allow for cleanup.

Returns:

Type Description
bool

True if the task is interrupted, False otherwise.

is_running property

Python
is_running: bool

Checks if the task is actively running.

Returns:

Type Description
bool

True if the task is currently executing, False otherwise.

is_alive property

Python
is_alive: bool

Checks if the task is currently active or armed for execution.

This property indicates the local state of the task. It returns True if the task has not reached a terminal state (e.g., Stopped, Finished, or Crashed). This local state remains True even if the master engine's global worker is currently paused or completely offline.

Returns:

Type Description
bool

True if the task is alive, False otherwise.

Functions

getName

Python
getName() -> str

Retrieves the internal name of the task.

Returns:

Type Description
str

The internal name of the task.

isEnabled

Python
isEnabled() -> bool

Checks if the task is currently enabled.

An enabled task will be considered for execution by the engine.

Returns:

Name Type Description
bool bool

True if the task is enabled, False otherwise.

isValid

Python
isValid() -> bool

Safely checks if the underlying task controller is still valid.

This method can be called without fear of raising a TaskDeletedError.

Returns:

Name Type Description
bool bool

True if the task controller is valid, False otherwise.

setEnabled

Python
setEnabled(enabled: bool)

Enables or disables the task.

An enabled task will be run by the engine; a disabled task will be skipped.

Parameters:

Name Type Description Default
enabled bool

If True, enables the task. If False, disables it.

 required

restart

Python
restart()

Restarts the task.

This kills the current instance of the task and schedules a fresh one to start at the next work cycle of the engine.

pause

Python
pause(interrupt: bool = False) -> bool

Pauses the task execution.

If the task is not already paused, this halts its execution before running its next step.

Parameters:

Name Type Description Default
interrupt bool

Controls how the pause is handled.

  • True: Interrupts the task. This raises a TaskInterruptedException within the task, allowing it to release keys and clean up resources safely (e.g., cutting short a taskSleep).
  • False (Default): Freezes the task in place. The generator execution is suspended at the exact current line. No cleanup logic is triggered; held keys remain held, and local variables are preserved as-is.
 False

Returns:

Type Description
bool

True if the pause command was issued successfully, False if the engine has stopped abruptly or the task could not be paused.

resume

Python
resume() -> float | None

Resumes a previously paused task.

If the engine is running and the task was previously paused, this method resumes its execution from where it left off. If the task has already finished, this method does nothing.

Returns:

Type Description
float | None

The duration in seconds for which the task was paused, or None if the task was not paused or could not be resumed.

stop

Python
stop()

Stops the task.

This attempts to stop a task on its next execution cycle. The task will transition to a terminal state.

log

Python
log(*args: Any, level: LogLevel = LogLevel.INFO)

Sends a structured log message to the UI.

Parameters:

Name Type Description Default
*args Any

The objects to be printed in the log message. If the log level is not ERROR, these arguments will be automatically cast to strings.

 ()
level LogLevel

The LogLevel at which to display the message (e.g., INFO, WARN, ERROR). Defaults to LogLevel.INFO.

 INFO

logError

Python
logError(error_msg: str, trace: str = '')

Sends a specialized error log message to the UI.

This method is specifically for logging errors and includes an optional stack trace.

Parameters:

Name Type Description Default
error_msg str

The main error message to display.

 required
trace str

An optional stack trace string associated with the error. Defaults to an empty string.

 ''

getVar

Python
getVar(key: Hashable) -> Any | None

Retrieves the current value of a setup variable.

Parameters:

Name Type Description Default
key Hashable

The hashable identifier of the variable to retrieve.

 required

Returns:

Type Description
Any | None

The value of the setup variable if present, otherwise None.

macro_studio.ThreadController

Python
ThreadController(controller: TaskController)

Bases: TaskContext

Extends TaskContext for tasks running in a separate thread.

This context provides additional functionalities specific to threaded tasks, such as blocking sleep operations that do not affect the main application or other tasks.

Functions

sleep

Python
sleep(duration: float = 0.01)

Blocks the current thread with high precision for a specified duration.

This method is suitable for threaded tasks that need to pause their execution without yielding control back to the main engine.

Parameters:

Name Type Description Default
duration float

The duration in seconds to sleep the thread. Defaults to 0.01 seconds.

 0.01

Raises:

Type Description
TaskAbortException

If the task is stopped while sleeping.
TaskInterruptedException

If the task is interrupted while sleeping.

waitForResume

Python
waitForResume()

Blocks the thread if the system or this task is in an interrupted pause.

This method will only block the thread if the task or the entire system is in a "hard" (interrupted) pause state. If the task is merely "soft-paused" (e.g., waiting for a logical condition), this method returns immediately.

Raises:

Type Description
TaskAbortException

If the task is stopped while waiting for resume.