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