[message] simplify accessing of indirect tx ChildMask bit-set (open…

…thread#10824)

This commit renames the `BitVector<>` class to `BitSet<>` and updates
its methods, introducing simpler methods such as `Add()`, `Remove()`,
and `IsEmpty()`. This aligns better with the intended use of this
class as a bit-set, e.g., as a `ChildMask` to track the set of
sleepy children to which a message is scheduled for indirect
transmission.

The `Message` class now provides the `GetIndirectTxChildMask()`
method, which returns a reference to the `ChildMask` bit-set.

src/core/BUILD.gn

@@ -391,7 +391,7 @@ openthread_core_files = [
   "common/as_core_type.hpp",
   "common/binary_search.cpp",
   "common/binary_search.hpp",
-  "common/bit_vector.hpp",
+  "common/bit_set.hpp",
   "common/callback.hpp",
   "common/clearable.hpp",
   "common/code_utils.hpp",

src/core/common/bit_set.hpp

@@ -0,0 +1,140 @@
+/*
+ *  Copyright (c) 2020, The OpenThread Authors.
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *  1. Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *  3. Neither the name of the copyright holder nor the
+ *     names of its contributors may be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/**
+ * @file
+ *   This file includes definitions for a bit-set.
+ */
+
+#ifndef BIT_SET_HPP_
+#define BIT_SET_HPP_
+
+#include "openthread-core-config.h"
+
+#include "common/clearable.hpp"
+#include "common/equatable.hpp"
+#include "common/numeric_limits.hpp"
+
+namespace ot {
+
+/**
+ * @addtogroup core-bit-set
+ *
+ * @brief
+ *   This module includes definitions for bit-set.
+ *
+ * @{
+ */
+
+/**
+ * Represents a bit-set.
+ *
+ * @tparam kNumBits  Specifies the number of bits.
+ */
+template <uint16_t kNumBits> class BitSet : public Equatable<BitSet<kNumBits>>, public Clearable<BitSet<kNumBits>>
+{
+public:
+    /**
+     * Indicates whether a given bit index is contained in the set.
+     *
+     * The caller MUST ensure that @p aIndex is smaller than `kNumBits`. Otherwise, the behavior of this method is
+     * undefined.
+     *
+     * @param[in] aIndex  The bit index to check
+     *
+     * @retval TRUE   If the bit index @p aIndex is contained in the set.
+     * @retval FALSE  If the bit index @p aIndex is not contained in the set.
+     */
+    bool Has(uint16_t aIndex) const { return (mMask[aIndex / 8] & BitMaskFor(aIndex)) != 0; }
+
+    /**
+     * Adds the given bit index to the set.
+     *
+     * The caller MUST ensure that @p aIndex is smaller than `kNumBits`. Otherwise, the behavior of this method is
+     * undefined.
+     *
+     * @param[in] aIndex  The bit index to add.
+     */
+    void Add(uint16_t aIndex) { mMask[aIndex / 8] |= BitMaskFor(aIndex); }
+
+    /**
+     * Removes the given bit index from the set.
+     *
+     * The caller MUST ensure that @p aIndex is smaller than `kNumBits`. Otherwise, the behavior of this method is
+     * undefined.
+     *
+     * @param[in] aIndex  The bit index to remove.
+     */
+    void Remove(uint16_t aIndex) { mMask[aIndex / 8] &= ~BitMaskFor(aIndex); }
+
+    /**
+     * Updates the set by either adding or removing the given bit index.
+     *
+     * The caller MUST ensure that @p aIndex is smaller than `kNumBits`. Otherwise, the behavior of this method is
+     * undefined.
+     *
+     * @param[in] aIndex  The bit index.
+     * @param[in] aToAdd  Boolean indicating whether to add (when set to TRUE) or to remove (when set to FALSE).
+     */
+    void Update(uint16_t aIndex, bool aToAdd) { aToAdd ? Add(aIndex) : Remove(aIndex); }
+
+    /**
+     * Indicates whether or not the set is empty.
+     *
+     * @retval TRUE   If the set is empty.
+     * @retval FALSE  If the set is not empty.
+     */
+    bool IsEmpty(void) const
+    {
+        bool isEmpty = true;
+
+        for (uint8_t byte : mMask)
+        {
+            if (byte != 0)
+            {
+                isEmpty = false;
+                break;
+            }
+        }
+
+        return isEmpty;
+    }
+
+private:
+    static uint8_t BitMaskFor(uint16_t aIndex) { return (0x80 >> (aIndex & 7)); }
+
+    uint8_t mMask[BytesForBitSize(kNumBits)];
+};
+
+/**
+ * @}
+ */
+
+} // namespace ot
+
+#endif // BIT_SET_HPP_

src/core/common/message.cpp

@@ -792,16 +792,6 @@ Message *Message::Clone(uint16_t aLength) const
     return messageCopy;
 }
 
-#if OPENTHREAD_FTD
-bool Message::GetChildMask(uint16_t aChildIndex) const { return GetMetadata().mChildMask.Get(aChildIndex); }
-
-void Message::ClearChildMask(uint16_t aChildIndex) { GetMetadata().mChildMask.Set(aChildIndex, false); }
-
-void Message::SetChildMask(uint16_t aChildIndex) { GetMetadata().mChildMask.Set(aChildIndex, true); }
-
-bool Message::IsChildPending(void) const { return GetMetadata().mChildMask.HasAny(); }
-#endif
-
 Error Message::GetLinkInfo(ThreadLinkInfo &aLinkInfo) const
 {
     Error error = kErrorNone;

src/core/common/message.hpp

@@ -1053,37 +1053,23 @@ class Message : public otMessage, public Buffer, public GetProvider<Message>
 
 #if OPENTHREAD_FTD
     /**
-     * Returns whether or not the message forwarding is scheduled for the child.
+     * Gets the indirect transmission `ChildMask` associated with this `Message`.
      *
-     * @param[in]  aChildIndex  The index into the child table.
+     * The `ChildMask` indicates the set of children for which this message is scheduled for indirect transmission.
      *
-     * @retval TRUE   If the message is scheduled to be forwarded to the child.
-     * @retval FALSE  If the message is not scheduled to be forwarded to the child.
+     * @returns A reference to the indirect transmission `ChildMask`.
      */
-    bool GetChildMask(uint16_t aChildIndex) const;
+    ChildMask &GetIndirectTxChildMask(void) { return GetMetadata().mChildMask; }
 
     /**
-     * Unschedules forwarding of the message to the child.
+     * Gets the indirect transmission `ChildMask` associated with this `Message`.
      *
-     * @param[in]  aChildIndex  The index into the child table.
-     */
-    void ClearChildMask(uint16_t aChildIndex);
-
-    /**
-     * Schedules forwarding of the message to the child.
-     *
-     * @param[in]  aChildIndex  The index into the child table.
-     */
-    void SetChildMask(uint16_t aChildIndex);
-
-    /**
-     * Returns whether or not the message forwarding is scheduled for at least one child.
+     * The `ChildMask` indicates the set of children for which this message is scheduled for indirect transmission.
      *
-     * @retval TRUE   If message forwarding is scheduled for at least one child.
-     * @retval FALSE  If message forwarding is not scheduled for any child.
+     * @returns A reference to the indirect transmission `ChildMask`.
      */
-    bool IsChildPending(void) const;
-#endif // OPENTHREAD_FTD
+    const ChildMask &GetIndirectTxChildMask(void) const { return GetMetadata().mChildMask; }
+#endif
 
     /**
      * Returns the RLOC16 of the mesh destination.

src/core/thread/child.cpp

@@ -87,11 +87,11 @@ MlrState Child::Ip6AddrEntry::GetMlrState(const Child &aChild) const
 
     index = aChild.mIp6Addresses.IndexOf(*this);
 
-    if (aChild.mMlrToRegisterMask.Get(index))
+    if (aChild.mMlrToRegisterSet.Has(index))
     {
         state = kMlrStateToRegister;
     }
-    else if (aChild.mMlrRegisteredMask.Get(index))
+    else if (aChild.mMlrRegisteredSet.Has(index))
     {
         state = kMlrStateRegistered;
     }
@@ -108,8 +108,8 @@ void Child::Ip6AddrEntry::SetMlrState(MlrState aState, Child &aChild)
 
     index = aChild.mIp6Addresses.IndexOf(*this);
 
-    aChild.mMlrToRegisterMask.Set(index, aState == kMlrStateToRegister);
-    aChild.mMlrRegisteredMask.Set(index, aState == kMlrStateRegistered);
+    aChild.mMlrToRegisterSet.Update(index, aState == kMlrStateToRegister);
+    aChild.mMlrRegisteredSet.Update(index, aState == kMlrStateRegistered);
 }
 
 #endif // OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE
@@ -130,8 +130,8 @@ void Child::ClearIp6Addresses(void)
     mMeshLocalIid.Clear();
     mIp6Addresses.Clear();
 #if OPENTHREAD_FTD && OPENTHREAD_CONFIG_TMF_PROXY_MLR_ENABLE
-    mMlrToRegisterMask.Clear();
-    mMlrRegisteredMask.Clear();
+    mMlrToRegisterSet.Clear();
+    mMlrRegisteredSet.Clear();
 #endif
 }
 
@@ -232,11 +232,11 @@ Error Child::RemoveIp6Address(const Ip6::Address &aAddress)
         uint16_t entryIndex = mIp6Addresses.IndexOf(*entry);
         uint16_t lastIndex  = mIp6Addresses.GetLength() - 1;
 
-        mMlrToRegisterMask.Set(entryIndex, mMlrToRegisterMask.Get(lastIndex));
-        mMlrToRegisterMask.Set(lastIndex, false);
+        mMlrToRegisterSet.Update(entryIndex, mMlrToRegisterSet.Has(lastIndex));
+        mMlrToRegisterSet.Remove(lastIndex);
 
-        mMlrRegisteredMask.Set(entryIndex, mMlrRegisteredMask.Get(lastIndex));
-        mMlrRegisteredMask.Set(lastIndex, false);
+        mMlrRegisteredSet.Update(entryIndex, mMlrRegisteredSet.Has(lastIndex));
+        mMlrRegisteredSet.Remove(lastIndex);
     }
 #endif