# patroni.async_executor module

Implement facilities for executing asynchronous tasks.

class patroni.async_executor.AsyncExecutor(cancellable: CancellableSubprocess, ha_wakeup: Callable[[...], None])

  Bases: `object`

  Asynchronous executor of (long) tasks.

  Variables:

    critical_task – a `CriticalTask` instance to handle execution of critical background tasks.

  __init__(cancellable: CancellableSubprocess, ha_wakeup: Callable[[...], None]) → None

    Create a new instance of `AsyncExecutor`.

    Configure the given cancellable and ha_wakeup, initializes the control attributes, and instantiate the lock and event objects that are used to access attributes and manage communication between threads.

    Parameters:

      - cancellable – a subprocess that supports being cancelled.

      - ha_wakeup – function to wake up the HA loop.

  property busy: bool

    `True` if there is an action scheduled to occur, else `False`.

  cancel() → None

    Request cancellation of a scheduled async task, if any.

    Note

    Wait until task is cancelled before returning control to caller.

  reset_scheduled_action() → None

    Unschedule a previously scheduled action, if any.

    Note

    Must be called once the scheduled task finishes or is cancelled.

  run(func: Callable[[...], Any], args: Tuple[Any, ...] = ()) → Any | None

    Run func with args.

    Note

    Expected to be executed through a thread.

    Parameters:

      - func – function to be run. If it returns anything other than `None`, HA loop will be woken up at the end of `run()` execution.

      - args – arguments to be passed to func.

    Returns:

      `None` if func execution has been cancelled or faced any exception, otherwise the result of func.

  run_async(func: Callable[[...], Any], args: Tuple[Any, ...] = ()) → None

    Start an async thread that runs func with args.

    Parameters:

      - func – function to be run.

      - args – arguments to be passed along with func.

  schedule(action: str) → str | None

    Schedule action to be executed.

    Note

    Must be called before executing a task.

    Note

    action can only be scheduled if there is no other action currently scheduled.

    Parameters:

      action – action to be executed.

    Returns:

      `None` if action has been successfully scheduled, or the previously scheduled action, if any.

  property scheduled_action: str | None

    The currently scheduled action, if any, else `None`.

  try_run_async(action: str, func: Callable[[...], Any], args: Tuple[Any, ...] = ()) → str | None

    Try to run an async task, if none is currently being executed.

    Parameters:

      - action – name of the task to be executed.

      - func – actual function that performs the task action.

      - args – arguments to be passed to func.

    Returns:

      `None` if func was scheduled successfully, otherwise an error message informing of an already ongoing task.

class patroni.async_executor.CriticalTask

  Bases: `object`

  Represents a critical task in a background process that we either need to cancel or get the result of.

  Fields of this object may be accessed only when holding a lock on it. To perform the critical task the background thread must, while holding lock on this object, check `is_cancelled` flag, run the task and mark the task as complete using `complete()`.

  The main thread must hold async lock to prevent the task from completing, hold lock on critical task object, call `cancel()`. If the task has completed `cancel()` will return `False` and `result` field will contain the result of the task. When `cancel()` returns `True` it is guaranteed that the background task will notice the `is_cancelled` flag.

  Variables:

    - is_cancelled – if the critical task has been cancelled.

    - result – contains the result of the task, if it has already been completed.

  __init__() → None

    Create a new instance of `CriticalTask`.

    Instantiate the lock and the task control attributes.

  cancel() → bool

    Tries to cancel the task.

    Note

    Caller must hold lock on async executor and the task when calling.

    Returns:

      `False` if the task has already run, or `True` it has been cancelled.

  complete(result: Any) → None

    Mark task as completed along with a result.

    Note

    Must be called from async thread. Caller must hold lock on task when calling.

  reset() → None

    Must be called every time the background task is finished.

    Note

    Must be called from async thread. Caller must hold lock on async executor when calling.