action-manager.h

  1/* SPDX-License-Identifier: GPL-2.0-only */
  2/*
  3 * Copyright 2023 Red Hat
  4 */
  5
  6#ifndef VDO_ACTION_MANAGER_H
  7#define VDO_ACTION_MANAGER_H
  8
  9#include "admin-state.h"
 10#include "types.h"
 11
 12/*
 13 * An action_manager provides a generic mechanism for applying actions to multi-zone entities (such
 14 * as the block map or slab depot). Each action manager is tied to a specific context for which it
 15 * manages actions. The manager ensures that only one action is active on that context at a time,
 16 * and supports at most one pending action. Calls to schedule an action when there is already a
 17 * pending action will result in VDO_COMPONENT_BUSY errors. Actions may only be submitted to the
 18 * action manager from a single thread (which thread is determined when the action manager is
 19 * constructed).
 20 *
 21 * A scheduled action consists of four components:
 22 *
 23 *   preamble
 24 *     an optional method to be run on the initiator thread before applying the action to all zones
 25 *   zone_action
 26 *     an optional method to be applied to each of the zones
 27 *   conclusion
 28 *     an optional method to be run on the initiator thread once the per-zone method has been
 29 *     applied to all zones
 30 *   parent
 31 *     an optional completion to be finished once the conclusion is done
 32 *
 33 * At least one of the three methods must be provided.
 34 */
 35
 36/*
 37 * A function which is to be applied asynchronously to a set of zones.
 38 * @context: The object which holds the per-zone context for the action
 39 * @zone_number: The number of zone to which the action is being applied
 40 * @parent: The object to notify when the action is complete
 41 */
 42typedef void (*vdo_zone_action_fn)(void *context, zone_count_t zone_number,
 43				   struct vdo_completion *parent);
 44
 45/*
 46 * A function which is to be applied asynchronously on an action manager's initiator thread as the
 47 * preamble of an action.
 48 * @context: The object which holds the per-zone context for the action
 49 * @parent: The object to notify when the action is complete
 50 */
 51typedef void (*vdo_action_preamble_fn)(void *context, struct vdo_completion *parent);
 52
 53/*
 54 * A function which will run on the action manager's initiator thread as the conclusion of an
 55 * action.
 56 * @context: The object which holds the per-zone context for the action
 57 *
 58 * Return: VDO_SUCCESS or an error
 59 */
 60typedef int (*vdo_action_conclusion_fn)(void *context);
 61
 62/*
 63 * A function to schedule an action.
 64 * @context: The object which holds the per-zone context for the action
 65 *
 66 * Return: true if an action was scheduled
 67 */
 68typedef bool (*vdo_action_scheduler_fn)(void *context);
 69
 70/*
 71 * A function to get the id of the thread associated with a given zone.
 72 * @context: The action context
 73 * @zone_number: The number of the zone for which the thread ID is desired
 74 */
 75typedef thread_id_t (*vdo_zone_thread_getter_fn)(void *context, zone_count_t zone_number);
 76
 77struct action_manager;
 78
 79int __must_check vdo_make_action_manager(zone_count_t zones,
 80					 vdo_zone_thread_getter_fn get_zone_thread_id,
 81					 thread_id_t initiator_thread_id, void *context,
 82					 vdo_action_scheduler_fn scheduler,
 83					 struct vdo *vdo,
 84					 struct action_manager **manager_ptr);
 85
 86const struct admin_state_code *__must_check
 87vdo_get_current_manager_operation(struct action_manager *manager);
 88
 89void * __must_check vdo_get_current_action_context(struct action_manager *manager);
 90
 91bool vdo_schedule_default_action(struct action_manager *manager);
 92
 93bool vdo_schedule_action(struct action_manager *manager, vdo_action_preamble_fn preamble,
 94			 vdo_zone_action_fn action, vdo_action_conclusion_fn conclusion,
 95			 struct vdo_completion *parent);
 96
 97bool vdo_schedule_operation(struct action_manager *manager,
 98			    const struct admin_state_code *operation,
 99			    vdo_action_preamble_fn preamble, vdo_zone_action_fn action,
100			    vdo_action_conclusion_fn conclusion,
101			    struct vdo_completion *parent);
102
103bool vdo_schedule_operation_with_context(struct action_manager *manager,
104					 const struct admin_state_code *operation,
105					 vdo_action_preamble_fn preamble,
106					 vdo_zone_action_fn action,
107					 vdo_action_conclusion_fn conclusion,
108					 void *context, struct vdo_completion *parent);
109
110#endif /* VDO_ACTION_MANAGER_H */