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 */ 111