xref: /linux/drivers/md/dm-vdo/action-manager.h (revision 79790b6818e96c58fe2bffee1b418c16e64e7b80)
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