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_IITERABLE_H
17 #define META_INTERFACE_IITERABLE_H
18 
19 #include <meta/base/interface_macros.h>
20 #include <meta/interface/intf_function.h>
21 #include <meta/interface/intf_lockable.h>
22 
23 META_BEGIN_NAMESPACE()
24 
25 /**
26  * @brief The TraversalType enum is used to define a traversal order in a hierarchy.
27  */
28 enum class TraversalType : uint32_t {
29     /** Traverse only immediate children */
30     NO_HIERARCHY = 0,
31     /** Traverse a hierarchy using any order, this usually just maps to one of the orders below */
32     FULL_HIERARCHY = 1,
33     /** Traverse a hierarchy using a post-order depth-first algorithm */
34     DEPTH_FIRST_POST_ORDER = 2,
35     /** Traverse a hierarchy using a pre-order depth-first algorithm */
36     DEPTH_FIRST_PRE_ORDER = 3,
37     /** Traverse a hierarchy using a breadth first algorithm */
38     BREADTH_FIRST_ORDER = 4
39 };
40 
41 struct IterateStrategy {
42     TraversalType traversal { TraversalType::NO_HIERARCHY };
43     LockType lock { LockType::UNIQUE_LOCK };
44 };
45 
46 struct IterationParameters {
47     ICallable& function;
48     IterateStrategy strategy;
49 };
50 
51 META_REGISTER_INTERFACE(IIterable, "76bfbc71-bbfe-476c-9ef5-9c01a3bf267d")
52 
53 /**
54  * @brief Result type for iterating to support recursive iteration with stopping
55  */
56 struct IterationResult {
57     enum Type { FAILED, STOP, CONTINUE } value;
58 
59     IterationResult(Type v = CONTINUE) : value(v) {}
60     IterationResult(bool) = delete;
61 
ContinueIterationResult62     bool Continue() const
63     {
64         return value == CONTINUE;
65     }
66 
67     operator bool() const
68     {
69         return value != FAILED;
70     }
71 };
72 
73 /**
74  * @brief The IIterable interface which allows to iterate over elements e.g. in container
75  */
76 class IIterable : public CORE_NS::IInterface {
77     META_INTERFACE(CORE_NS::IInterface, IIterable)
78 public:
79     /* @brief Invoke function for each element in order as long as the function returns true. In case false is
80      *        returned, the iteration stops. Mutating the element sequence within the invoked
81      *        function results undefined behaviour. Mutating the element value passed to the function
82      *        is permitted.
83      * @param func The function being invoked, must be one of the callables below
84      * @return True if function was called, i.e. it was compatible with the value type
85      */
86     virtual IterationResult Iterate(const IterationParameters& params) = 0;
87     virtual IterationResult Iterate(const IterationParameters& params) const = 0;
88 };
89 
90 /**
91  * @brief Callable interface for IIterable
92  */
93 template<typename Type>
94 class IIterableCallable : public ICallable {
95     META_INTERFACE(ICallable, IIterableCallable, UidFromType<Type>())
96 public:
97     using ArgType = Type&;
98     virtual IterationResult Invoke(Type&) = 0;
99 };
100 
101 /**
102  * @brief Callable interface for IIterable with const reference
103  */
104 template<typename Type>
105 class IIterableConstCallable : public ICallable {
106     META_INTERFACE(ICallable, IIterableConstCallable, UidFromType<Type>())
107 public:
108     using ArgType = const Type&;
109     virtual IterationResult Invoke(const Type&) = 0;
110 };
111 
112 META_END_NAMESPACE()
113 
114 #endif
115