src/lib/support/PersistedCounter.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2016-2017 Nest Labs, Inc.
   5  *    All rights reserved.
   6  *
   7  *    Licensed under the Apache License, Version 2.0 (the "License");
   8  *    you may not use this file except in compliance with the License.
   9  *    You may obtain a copy of the License at
  10  *
  11  *        http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  *    Unless required by applicable law or agreed to in writing, software
  14  *    distributed under the License is distributed on an "AS IS" BASIS,
  15  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  *    See the License for the specific language governing permissions and
  17  *    limitations under the License.
  18  */
  19
  20 /**
  21  * @file
  22  *
  23  * @brief
  24  *   Class declarations for a monotonically-increasing counter that is periodically
  25  *   saved in the platform's persistent storage.
  26  */
  27
  28 #pragma once
  29
  30 #include <platform/PersistedStorage.h>
  31 #include <support/CHIPCounter.h>
  32
  33 namespace chip {
  34
  35 /**
  36  * @class PersistedCounter
  37  *
  38  * @brief
  39  *   A class for managing a counter as an integer value intended to persist
  40  *   across reboots.
  41  *
  42  * Counter values are always set to start at a multiple of a bootup value
  43  * "epoch".
  44  *
  45  * Example:
  46  *
  47  * - Assuming epoch is 100 via PersistedCounter::Init(_, 100) and GetValue +
  48  *   AdvanceValue is called, we get the following outputs:
  49  *
  50  *   - Output: 0, 1, 2, 3, 4  <reboot/reinit>
  51  *   - Output: 100, 101, 102, 103, 104, 105 <reboot/reinit>
  52  *   - Output: 200, 201, 202, ...., 299, 300, 301, 302 <reboot/reinit>
  53  *   - Output: 400, 401 ...
  54  *
  55  */
  56 class PersistedCounter : public MonotonicallyIncreasingCounter
  57 {
  58 public:
  59     PersistedCounter();
  60     ~PersistedCounter() override;
  61
  62     /**
  63      *  @brief
  64      *    Initialize a PersistedCounter object.
  65      *
  66      *  @param[in] aId     The identifier of this PersistedCounter instance.
  67      *  @param[in] aEpoch  On bootup, values we vend will start at a
  68      *                     multiple of this parameter.
  69      *
  70      *  @return CHIP_ERROR_INVALID_ARGUMENT if aId is NULL
  71      *          CHIP_ERROR_INVALID_STRING_LENGTH if aId is longer than
  72      *          CHIP_CONFIG_PERSISTED_STORAGE_MAX_KEY_LENGTH.
  73      *          CHIP_ERROR_INVALID_INTEGER_VALUE if aEpoch is 0.
  74      *          CHIP_NO_ERROR otherwise
  75      */
  76     CHIP_ERROR Init(chip::Platform::PersistedStorage::Key aId, uint32_t aEpoch);
  77
  78     /**
  79      *  @brief
  80      *  Increment the counter and write to persisted storage if we've completed
  81      *  the current epoch.
  82      *
  83      *  @return Any error returned by a write to persisted storage.
  84      */
  85     CHIP_ERROR Advance() override;
  86
  87 private:
  88     /**
  89      *  @brief
  90      *    Write out the counter value to persistent storage.
  91      *
  92      *  @param[in] aStartValue  The counter value to write out.
  93      *
  94      *  @return Any error returned by a write to persistent storage.
  95      */
  96     CHIP_ERROR PersistNextEpochStart(uint32_t aStartValue);
  97
  98     /**
  99      *  @brief
 100      *    Read our starting counter value (if we have one) in from persistent storage.
 101      *
 102      *  @param[in,out] aStartValue  The value read out.
 103      *
 104      *  @return Any error returned by a read from persistent storage.
 105      */
 106     CHIP_ERROR ReadStartValue(uint32_t & aStartValue);
 107
 108     chip::Platform::PersistedStorage::Key mId; // start value is stored here
 109     uint32_t mEpoch;                           // epoch modulus value
 110     uint32_t mNextEpoch;                       // next epoch start
 111 };
 112
 113 } // namespace chip