@@ -118,6 +118,8 @@ class DeviceEnergyManagementDelegate : public DeviceEnergyManagement::Delegate
118118 * If the ESA accepts the requested Forecast then it SHALL update its Forecast attribute (incrementing its ForecastID)
119119 * and run the revised Forecast as its new intended operation.
120120 *
121+ * *** NOTE *** for the memory management of the forecast object, see the comment before the mForecast delaration below.
122+ *
121123 * @param forecastID Indicates the ESA ForecastID that is to be modified.
122124 * @param slotAdjustments List of adjustments to be applied to the ESA, corresponding to the expected ESA forecastID.
123125 * @return Success if the entire list of SlotAdjustmentStruct are accepted, otherwise the command
@@ -240,6 +242,38 @@ class DeviceEnergyManagementDelegate : public DeviceEnergyManagement::Delegate
240242
241243 DataModel::Nullable<Structs::PowerAdjustCapabilityStruct::Type> mPowerAdjustCapabilityStruct ;
242244
245+ // The DeviceEnergyManagementDelegate owns the master copy of the ForecastStruct object which is accessed via GetForecast and SetForecast.
246+ // The slots field of forecast is owned and managed by the object that implements the DEMManufacturerDelegate interface.
247+ //
248+ // The rationale for this is as follows:
249+ // It is envisioned there will be one master forecast object declared in DeviceEnergyManagementDelegate. When
250+ // constructed, the field DataModel::List<const Structs::SlotStruct::Type> slots will be empty.
251+ //
252+ // The EVSEManufacturerImpl class (examples/energy-management-app/energy-management-common/include/EVSEManufacturerImpl.h) is
253+ // an example implementation that a specific vendor can use as a template. It understands how the underlying energy appliance
254+ // functions. EVSEManufacturerImpl inherits from DEMManufacturerDelegate
255+ // (examples/energy-management-app/energy-management-common/include/DEMManufacturerDelegate.h) which is a generic interface
256+ // and how the DeviceEnergyManagementDelegate class
257+ // (examples/energy-management-app/energy-management-common/src/DeviceEnergyManagementDelegateImpl.cpp) communicates from the
258+ // generic cluster world to the specific appliance implementation (EVSEManufacturerImpl).
259+ //
260+ // EVSEManufacturerImpl understands the slot structures of the appliance and configures the slot structures as follows:
261+ //
262+ // Call DeviceEnergyManagementDelegate::GetForecast() to get the current forecast
263+ // Modify the slot structure - the slots memory is owned by EVSEManufacturerImpl
264+ // Call DeviceEnergyManagementDelegate::GetForecast() to set the current forecast
265+ //
266+ //
267+ // The cluster object DeviceEnergyManagement::Instance
268+ // (src/app/clusters/device-energy-management-server/device-energy-management-server.cpp) only reads the slots field of
269+ // forecast when checking commands (indeed it does not modify any forecast fields itself). The DeviceEnergyManagementDelegate
270+ // object does modify some of forecast's fields but does NOT modify the slots field. The only command that can modify the
271+ // slots field is HandleModifyForecastRequest. Whilst DeviceEnergyManagementDelegate::ModifyForecastRequest does some state
272+ // checking, the slots field is only modified by the EVSEManufacturerImpl object via the call
273+ // DEMManufacturerDelegate::HandleModifyForecastRequest. DEMManufacturerDelegate::HandleModifyForecastRequest may
274+ // delete/allocate the slots memory but this will be done atomically in the call to
275+ // DEMManufacturerDelegate::HandleModifyForecastRequest so the underlying memory is coherent => the call to
276+ // DEMManufacturerDelegate::HandleModifyForecastRequest cannot be interrupted by any other CHIP task activity.
243277 DataModel::Nullable<Structs::ForecastStruct::Type> mForecast ;
244278
245279 // Keep track whether a PowerAdjustment is in progress
0 commit comments