Skip to content

Commit b40ad4e

Browse files
hastyhasty
committed
Method documentation
1 parent 04bdb52 commit b40ad4e

File tree

3 files changed

+213
-21
lines changed

3 files changed

+213
-21
lines changed

‎examples/thermostat/thermostat-common/include/atomic-write-manager.h

+83
Original file line numberDiff line numberDiff line change
@@ -39,28 +39,111 @@ class ThermostatAtomicWriteManager : public AtomicWriteManager
3939
public:
4040
static inline ThermostatAtomicWriteManager & GetInstance() { return sInstance; }
4141

42+
/**
43+
* @brief Set the Delegate object
44+
*
45+
* @param delegate
46+
*/
4247
void SetDelegate(AtomicWriteDelegate * delegate) override { mDelegate = delegate; };
4348

49+
/**
50+
* @brief Check if there is an open atomic write on an endpoint, optionally associated with a specific attribute
51+
*
52+
* @param attributeId Optional attribute filter
53+
* @param endpoint The endpoint to check atomic write state
54+
* @return true if there is an open atomic write
55+
* @return false if there is not at open atomic write
56+
*/
4457
bool InWrite(const std::optional<AttributeId> attributeId, EndpointId endpoint) override;
4558

59+
/**
60+
* @brief Check if there is an open atomic write on an endpoint, associated with a given SubjectDescriptor, and optionally
61+
* associated with a specific attribute
62+
*
63+
* @param attributeId Optional attribute filter
64+
* @param subjectDescriptor The subject descriptor to check against
65+
* @param endpoint The endpoint to check atomic write state
66+
* @return true if there is an open atomic write
67+
* @return false if there is not an open atomic write
68+
*/
4669
bool InWrite(const std::optional<AttributeId> attributeId, const Access::SubjectDescriptor & subjectDescriptor,
4770
EndpointId endpoint) override;
4871

72+
/**
73+
* @brief Check if there is an open atomic write on an endpoint, associated with the source node for a given command invocation,
74+
* and optionally associated with a specific attribute
75+
*
76+
* @param attributeId
77+
* @param commandObj
78+
* @param endpoint
79+
* @return true
80+
* @return false
81+
*/
4982
bool InWrite(const std::optional<AttributeId> attributeId, CommandHandler * commandObj, EndpointId endpoint) override;
5083

84+
/**
85+
* @brief Check if there is an open atomic write on an endpoint, associated with the source node for a given command invocation,
86+
* and associated with the set of attribute IDs
87+
*
88+
* @param attributeIds The set of attribute IDs to check against
89+
* @param commandObj The command being invoked
90+
* @param endpoint The endpoint for the atomic write
91+
* @return true if there is an open atomic write
92+
* @return false if there is not an open atomic write
93+
*/
5194
bool InWrite(const DataModel::DecodableList<AttributeId>::Iterator attributeIds, CommandHandler * commandObj,
5295
EndpointId endpoint) override;
5396

97+
/**
98+
* @brief Attempt to start an atomic write
99+
*
100+
* @param commandObj The AtomicRequest command
101+
* @param commandPath The path for the command
102+
* @param commandData The payload of the command
103+
* @return true if the atomic write was opened
104+
* @return false if the atomic write was not opened
105+
*/
54106
bool BeginWrite(chip::app::CommandHandler * commandObj, const ConcreteCommandPath & commandPath,
55107
const Commands::AtomicRequest::DecodableType & commandData) override;
56108

109+
/**
110+
* @brief Attempt to commit an atomic write; returns true if the server is able to commit or failed trying, false if it was
111+
* unable to find a matching atomic write
112+
*
113+
* @param commandObj The AtomicRequest command
114+
* @param commandPath The path for the command
115+
* @param commandData The payload of the command
116+
* @return true if the atomic write was committed or rolled back
117+
* @return false if the atomic write was not found
118+
*/
57119
bool CommitWrite(chip::app::CommandHandler * commandObj, const ConcreteCommandPath & commandPath,
58120
const Commands::AtomicRequest::DecodableType & commandData) override;
59121

122+
/**
123+
* @brief Attempt to roll back an atomic write; returns true if the server is able to commit or failed trying, false if it was
124+
* unable to find a matching atomic write
125+
*
126+
* @param commandObj The AtomicRequest command
127+
* @param commandPath The path for the command
128+
* @param commandData The payload of the command
129+
* @return true if the atomic write was rolled back
130+
* @return false if the atomic write was not found
131+
*/
60132
bool RollbackWrite(chip::app::CommandHandler * commandObj, const ConcreteCommandPath & commandPath,
61133
const Commands::AtomicRequest::DecodableType & commandData) override;
62134

135+
/**
136+
* @brief Reset any atomic writes associated with the given endpoint
137+
*
138+
* @param endpoint
139+
*/
63140
void ResetWrite(EndpointId endpoint) override;
141+
142+
/**
143+
* @brief Reset any atomic writes originating from a given fabric index
144+
*
145+
* @param fabricIndex
146+
*/
64147
void ResetWrite(FabricIndex fabricIndex) override;
65148

66149
private:

‎src/app/clusters/thermostat-server/atomic-write.h

+128-21
Original file line numberDiff line numberDiff line change
@@ -31,18 +31,68 @@ namespace app {
3131
namespace Clusters {
3232
namespace Thermostat {
3333

34+
/**
35+
* @brief The AtomicWriteDelegate handles actual execution of the atomic write by the cluster
36+
*
37+
*/
3438
class AtomicWriteDelegate
3539
{
3640
public:
3741
AtomicWriteDelegate() = default;
3842

3943
virtual ~AtomicWriteDelegate() = default;
4044

41-
virtual imcode OnBeginWrite(EndpointId endpoint, AttributeId attributeId) = 0;
45+
/**
46+
* @brief OnBeginWrite is called when the client has successfully started an atomic write. The server should begin pending any
47+
* writes to the associated attribute; if it is not capable for any reason, it should return an error code, and the atomic write
48+
* will be discarded
49+
*
50+
* @param endpoint The endpoint for the atomic write
51+
* @param attributeId The attribute for the associated atomic write
52+
* @return Success, if the server is able to pend writes; otherwise an error code.
53+
*/
54+
virtual imcode OnBeginWrite(EndpointId endpoint, AttributeId attributeId) = 0;
55+
56+
/**
57+
* @brief OnPreCommitWrite is called when a client attempts to commit an atomic write. The server should evaluate writes to this
58+
* attribute, and return an error code if they would not be successful. This method should not have any side effects; even if it
59+
* returns Success, any pending changes may still be discarded if OnPreCommit fails for a separate attribute included in the
60+
* atomic write
61+
*
62+
* @param endpoint The endpoint for the atomic write
63+
* @param attributeId The attribute for the associated atomic write
64+
* @return Success, if the pending writes would succeed; otherwise an error code.
65+
*/
4266
virtual imcode OnPreCommitWrite(EndpointId endpoint, AttributeId attributeId) = 0;
43-
virtual imcode OnCommitWrite(EndpointId endpoint, AttributeId attributeId) = 0;
44-
virtual imcode OnRollbackWrite(EndpointId endpoint, AttributeId attributeId) = 0;
4567

68+
/**
69+
* @brief OnCommitWrite is called when a client attempts to commit an atomic write, and all calls to OnPreCommitWrite were
70+
* successful.
71+
*
72+
* @param endpoint The endpoint for the atomic write
73+
* @param attributeId The attribute for the associated atomic write
74+
* @return Success, if the pending writes succeeded; otherwise an error code.
75+
*/
76+
virtual imcode OnCommitWrite(EndpointId endpoint, AttributeId attributeId) = 0;
77+
78+
/**
79+
* @brief OnRollbackWrite is called when a client attempts to rollback an atomic write, or when the timeout expires without the
80+
* client attempting to commit or rollback the atomic write
81+
*
82+
* @param endpoint The endpoint for the atomic write
83+
* @param attributeId The attribute for the associated atomic write
84+
* @return Success, if rolling back pending writes succeeded; otherwise an error code.
85+
*/
86+
virtual imcode OnRollbackWrite(EndpointId endpoint, AttributeId attributeId) = 0;
87+
88+
/**
89+
* @brief Get the maximum write time out for a given attribute
90+
*
91+
* @param endpoint The endpoint for the atomic write
92+
* @param attributeId The attribute for the associated atomic write
93+
* @return The maximum milliseconds a server is willing to wait for an atomic write to succeed for the given attribute, or
94+
* nullopt if the server can not determine the maximum
95+
*/
4696
virtual std::optional<System::Clock::Milliseconds16> GetWriteTimeout(EndpointId endpoint, AttributeId attributeId) = 0;
4797
};
4898

@@ -54,53 +104,110 @@ class AtomicWriteManager
54104
virtual ~AtomicWriteManager() = default;
55105

56106
/**
57-
* @brief Gets whether an atomic write is in progress for the given endpoint and attribute
107+
* @brief Check if there is an open atomic write on an endpoint, optionally associated with a specific attribute
58108
*
59-
* @param[in] attributeId The attribute ID.
60-
* @param[in] endpoint The endpoint.
61-
*
62-
* @return Whether an atomic write is in progress for the given endpoint
109+
* @param attributeId Optional attribute filter
110+
* @param endpoint The endpoint to check atomic write state
111+
* @return true if there is an open atomic write
112+
* @return false if there is not at open atomic write
63113
*/
64114
virtual bool InWrite(const std::optional<AttributeId> attributeId, EndpointId endpoint) = 0;
65115

66116
/**
67-
* @brief Gets whether an atomic write is in progress for the given endpoint and attribute
68-
*
69-
* @param[in] attributeId The attribute ID.
70-
* @param[in] subjectDescriptor The subject descriptor.
71-
* @param[in] endpoint The endpoint.
117+
* @brief Check if there is an open atomic write on an endpoint, associated with a given SubjectDescriptor, and optionally
118+
* associated with a specific attribute
72119
*
73-
* @return Whether an atomic write is in progress for the given endpoint
120+
* @param attributeId Optional attribute filter
121+
* @param subjectDescriptor The subject descriptor to check against
122+
* @param endpoint The endpoint to check atomic write state
123+
* @return true if there is an open atomic write
124+
* @return false if there is not an open atomic write
74125
*/
75126
virtual bool InWrite(const std::optional<AttributeId> attributeId, const Access::SubjectDescriptor & subjectDescriptor,
76127
EndpointId endpoint) = 0;
77128

78129
/**
79-
* @brief Gets whether an atomic write is in progress for the given endpoint and attribute
130+
* @brief Check if there is an open atomic write on an endpoint, associated with the source node for a given command invocation,
131+
* and optionally associated with a specific attribute
80132
*
81-
* @param[in] attributeId The attribute ID.
82-
* @param[in] commandObj The command handler.
83-
* @param[in] endpoint The endpoint.
84-
*
85-
* @return Whether an atomic write is in progress for the given endpoint
133+
* @param attributeId
134+
* @param commandObj
135+
* @param endpoint
136+
* @return true
137+
* @return false
86138
*/
87139
virtual bool InWrite(const std::optional<AttributeId> attributeId, CommandHandler * commandObj, EndpointId endpoint) = 0;
88140

141+
/**
142+
* @brief Check if there is an open atomic write on an endpoint, associated with the source node for a given command invocation,
143+
* and associated with the set of attribute IDs
144+
*
145+
* @param attributeIds The set of attribute IDs to check against
146+
* @param commandObj The command being invoked
147+
* @param endpoint The endpoint for the atomic write
148+
* @return true if there is an open atomic write
149+
* @return false if there is not an open atomic write
150+
*/
89151
virtual bool InWrite(const DataModel::DecodableList<AttributeId>::Iterator attributeIds, CommandHandler * commandObj,
90152
EndpointId endpoint) = 0;
91153

154+
/**
155+
* @brief Attempt to start an atomic write
156+
*
157+
* @param commandObj The AtomicRequest command
158+
* @param commandPath The path for the command
159+
* @param commandData The payload of the command
160+
* @return true if the atomic write was opened
161+
* @return false if the atomic write was not opened
162+
*/
92163
virtual bool BeginWrite(chip::app::CommandHandler * commandObj, const ConcreteCommandPath & commandPath,
93164
const Commands::AtomicRequest::DecodableType & commandData) = 0;
94165

166+
/**
167+
* @brief Attempt to commit an atomic write; returns true if the server is able to commit or failed trying, false if it was
168+
* unable to find a matching atomic write
169+
*
170+
* @param commandObj The AtomicRequest command
171+
* @param commandPath The path for the command
172+
* @param commandData The payload of the command
173+
* @return true if the atomic write was committed or rolled back
174+
* @return false if the atomic write was not found
175+
*/
95176
virtual bool CommitWrite(chip::app::CommandHandler * commandObj, const ConcreteCommandPath & commandPath,
96177
const Commands::AtomicRequest::DecodableType & commandData) = 0;
97178

179+
/**
180+
* @brief Attempt to roll back an atomic write; returns true if the server is able to commit or failed trying, false if it was
181+
* unable to find a matching atomic write
182+
*
183+
* @param commandObj The AtomicRequest command
184+
* @param commandPath The path for the command
185+
* @param commandData The payload of the command
186+
* @return true if the atomic write was rolled back
187+
* @return false if the atomic write was not found
188+
*/
98189
virtual bool RollbackWrite(chip::app::CommandHandler * commandObj, const ConcreteCommandPath & commandPath,
99190
const Commands::AtomicRequest::DecodableType & commandData) = 0;
100191

101-
virtual void ResetWrite(EndpointId endpoint) = 0;
192+
/**
193+
* @brief Reset any atomic writes associated with the given endpoint
194+
*
195+
* @param endpoint
196+
*/
197+
virtual void ResetWrite(EndpointId endpoint) = 0;
198+
199+
/**
200+
* @brief Reset any atomic writes originating from a given fabric index
201+
*
202+
* @param fabricIndex
203+
*/
102204
virtual void ResetWrite(FabricIndex fabricIndex) = 0;
103205

206+
/**
207+
* @brief Sets a delegate for actually executing atomic writes
208+
*
209+
* @param delegate
210+
*/
104211
virtual void SetDelegate(AtomicWriteDelegate * delegate) = 0;
105212
};
106213

‎src/app/clusters/thermostat-server/thermostat-server.h

+2
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ class ThermostatAttrAccess : public chip::app::AttributeAccessInterface,
4848
CHIP_ERROR Read(const ConcreteReadAttributePath & aPath, AttributeValueEncoder & aEncoder) override;
4949
CHIP_ERROR Write(const ConcreteDataAttributePath & aPath, chip::app::AttributeValueDecoder & aDecoder) override;
5050

51+
// AtomicWriteDelegate
5152
imcode OnBeginWrite(EndpointId endpoint, AttributeId attributeId) override;
5253
imcode OnPreCommitWrite(EndpointId endpoint, AttributeId attributeId) override;
5354
imcode OnCommitWrite(EndpointId endpoint, AttributeId attributeId) override;
@@ -66,6 +67,7 @@ class ThermostatAttrAccess : public chip::app::AttributeAccessInterface,
6667
imcode CommitPresets(EndpointId endpoint);
6768
imcode RollbackPresets(EndpointId endpoint);
6869

70+
// FabricTable::Delegate
6971
void OnFabricRemoved(const FabricTable & fabricTable, FabricIndex fabricIndex) override;
7072
};
7173

0 commit comments

Comments
 (0)