1 /*
2  * Copyright (c) 2024 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef META_INTERFACE_ISTARTABLE_CONTROLLER_H
17 #define META_INTERFACE_ISTARTABLE_CONTROLLER_H
18 
19 #include <meta/base/interface_macros.h>
20 #include <meta/interface/interface_macros.h>
21 #include <meta/interface/intf_startable.h>
22 
23 META_BEGIN_NAMESPACE()
24 
25 REGISTER_INTERFACE(IStartableController, "dd8e8c3d-f81a-4e33-8c42-6db05eb65e24")
26 
27 /**
28  * @brief The IStartableController interface is implemented by controller objects for startables.
29  * @note The default implementation is META_NS::ClassId::StartableController.
30  */
31 class IStartableController : public CORE_NS::IInterface {
32     META_INTERFACE(CORE_NS::IInterface, IStartableController)
33 public:
34     /**
35      * @brief The ControlBehavior enum defines the modes which can be used to set which
36      *        startables are affected by a control operation such as StartAll or StopAll.
37      */
38     enum class ControlBehavior : uint32_t {
39         /** Control startables whose StartableMode=StartBehavior::AUTOMATIC. */
40         CONTROL_AUTOMATIC = 0,
41         /** Control all startables regardless of their StartableMode, both AUTOMATIC and
42          *  MANUAL startables are affected by the operation. */
43         CONTROL_ALL = 1,
44     };
45     /**
46      * @brief The traversal order in which the hierarchy should be traversed when starting/stopping
47      *        the startables.
48      */
49     META_PROPERTY(META_NS::TraversalType, TraversalType)
50     /**
51      * @brief Controls how the controller should handle new startables that are added to the hierarchy.
52      *        If StartBehavior::AUTOMATIC, new startables whose StartableMode==StartBehavior::AUTOMATIC
53      *        are started automatically, and startables that are removed from the hierarchy are stopped
54      *        automatically.
55      *        If StartBehavior::MANUAL, new startables are not started/stopped by the controller
56      *        automatically.
57      */
58     META_PROPERTY(META_NS::StartBehavior, StartBehavior)
59     /**
60      * @brief Start all startables which are part of the target hierarchy, using the order specified
61      *        by TraversalType.
62      * @param behavior Control which startables are started.
63      * @return True if successful, false otherwise.
64      */
65     virtual bool StartAll(ControlBehavior behavior) = 0;
66     /**
67      * @brief Stops all startables which are part of the target hierarchy, in reverse order to
68      *        the order in which the startables were started by StartAll.
69      * @param behavior Control which startables are started.
70      * @return True if successful, false otherwise.
71      */
72     virtual bool StopAll(ControlBehavior behavior) = 0;
73     /**
74      * @brief Returns all startables currently being controlled.
75      */
76     virtual BASE_NS::vector<IStartable::Ptr> GetAllStartables() const = 0;
77     /**
78      * @brief Sets the task queue id of the task queue which should be used to Start/Stop startables
79      *        handled by the controller.
80      * @param startStartableQueueId Task queue id to use for starting startables. If {}, use current thread for all
81      *        operations.
82      * @param stopStartableQueueId Task queue id to use for stopping startables. If {}, use current thread for all
83      *        operations. Note that setting stopStartableQueueId may alter the order in which Detach and Stop operations
84      *        happen for a startable which also implements IAttachment, as Stop operation is deferred to the given task
85      *        queue. This may cause Stop to be called after Detach.
86      * @return True if queue id was valid, false otherise.
87      */
88     virtual bool SetStartableQueueId(
89         const BASE_NS::Uid& startStartableQueueId, const BASE_NS::Uid& stopStartableQueueId) = 0;
90     /**
91      * @brief Starts all StartBehavior::AUTOMATIC startables
92      */
StartAll()93     bool StartAll()
94     {
95         return StartAll(ControlBehavior::CONTROL_AUTOMATIC);
96     }
97     /**
98      * @brief Stops all StartBehavior::AUTOMATIC startables
99      */
StopAll()100     bool StopAll()
101     {
102         return StopAll(ControlBehavior::CONTROL_AUTOMATIC);
103     }
104 };
105 
106 META_END_NAMESPACE()
107 
108 #endif
109