drivers/md/dm-vdo/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  */
  42 typedef 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  */
  51 typedef 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  */
  60 typedef 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  */
  68 typedef 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  */
  75 typedef thread_id_t (*vdo_zone_thread_getter_fn)(void *context, zone_count_t zone_number);
  76
  77 struct action_manager;
  78
  79 int __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
  86 const struct admin_state_code *__must_check
  87 vdo_get_current_manager_operation(struct action_manager *manager);
  88
  89 void * __must_check vdo_get_current_action_context(struct action_manager *manager);
  90
  91 bool vdo_schedule_default_action(struct action_manager *manager);
  92
  93 bool 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
  97 bool 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
 103 bool 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 */