[message-queue] simplify retrieval of message queue information (#11405)

This commit simplifies how information about the message queue, such
as the number of messages, data buffers, or total bytes in the queue,
is retrieved. The `MessageQueue::GetInfo()` method is changed to
clear the passed-in `Info` structure (instead of adding the counts to
the existing fields and expecting the caller to clear it).

A new helper method, `MessageQueue::AddQueueInfos()`, is added to
aggregate queue information when needed.

Various modules, such as `MeshForwarder`, `Ip6`, and `Mle`, are
updated to provide methods to retrieve their queue information
instead of exposing a reference to their internal queues.

In particular, `Coap` is updated to provide combined information for
all its queues, including request and cached response queues. This
simplifies the `Instance::GetBufferInfo()` method, which retrieves
information about all queues across all components.

src/core/coap/coap.cpp

@@ -564,6 +564,15 @@ Error CoapBase::AbortTransaction(ResponseHandler aHandler, void *aContext)
     return error;
 }
 
+void CoapBase::GetRequestAndCachedResponsesQueueInfo(MessageQueue::Info &aQueueInfo) const
+{
+    MessageQueue::Info info;
+
+    mPendingRequests.GetInfo(aQueueInfo);
+    mResponsesQueue.GetResponses().GetInfo(info);
+    MessageQueue::AddQueueInfos(aQueueInfo, info);
+}
+
 Message *CoapBase::CopyAndEnqueueMessage(const Message &aMessage, uint16_t aCopyLength, const Metadata &aMetadata)
 {
     Error    error       = kErrorNone;

src/core/coap/coap.hpp

@@ -720,18 +720,14 @@ public:
     void SetInterceptor(Interceptor aInterceptor, void *aContext) { mInterceptor.Set(aInterceptor, aContext); }
 
     /**
-     * Returns a reference to the request message list.
+     * Retrieves aggregated information about the CoAP request and cached response message queues.
      *
-     * @returns A reference to the request message list.
-     */
-    const MessageQueue &GetRequestMessages(void) const { return mPendingRequests; }
-
-    /**
-     * Returns a reference to the cached response list.
+     * Provides combined statistics, such as the total number of messages and data buffers currently used across all
+     * queues associated with CoAP requests and cached responses within this CoAP instance.
      *
-     * @returns A reference to the cached response list.
+     * @param[out] aQueueInfo     A `MessageQueue::Info` to populate with info about the queues.
      */
-    const MessageQueue &GetCachedResponses(void) const { return mResponsesQueue.GetResponses(); }
+    void GetRequestAndCachedResponsesQueueInfo(MessageQueue::Info &aQueueInfo) const;
 
 protected:
     /**

src/core/common/message.cpp

@@ -944,6 +944,8 @@ Message::ConstIterator MessageQueue::begin(void) const { return Message::ConstIt
 
 void MessageQueue::GetInfo(Info &aInfo) const
 {
+    ClearAllBytes(aInfo);
+
     for (const Message &message : *this)
     {
         aInfo.mNumMessages++;
@@ -952,6 +954,13 @@ void MessageQueue::GetInfo(Info &aInfo) const
     }
 }
 
+void MessageQueue::AddQueueInfos(Info &aInfo, const Info &aOther)
+{
+    aInfo.mNumMessages += aOther.mNumMessages;
+    aInfo.mNumBuffers += aOther.mNumBuffers;
+    aInfo.mTotalBytes += aOther.mTotalBytes;
+}
+
 //---------------------------------------------------------------------------------------------------------------------
 // PriorityQueue
 
@@ -1093,6 +1102,8 @@ Message::ConstIterator PriorityQueue::begin(void) const { return Message::ConstI
 
 void PriorityQueue::GetInfo(Info &aInfo) const
 {
+    ClearAllBytes(aInfo);
+
     for (const Message &message : *this)
     {
         aInfo.mNumMessages++;

src/core/common/message.hpp

@@ -1643,15 +1643,21 @@ public:
     /**
      * Gets the information about number of messages and buffers in the queue.
      *
-     * Updates `aInfo` and adds number of message/buffers in the message queue to the corresponding member
-     * variable in `aInfo`. The caller needs to make sure `aInfo` is initialized before calling this method (e.g.,
-     * clearing `aInfo`). Same `aInfo` can be passed in multiple calls of `GetInfo(aInfo)` on different queues to add
-     * up the number of messages/buffers on different queues.
-     *
-     * @param[out] aInfo  A reference to `Info` structure to update.ni
+     * @param[out] aInfo  A reference to `Info` structure to update.
      */
     void GetInfo(Info &aInfo) const;
 
+    /**
+     * Adds the queue statistics from one queue `Info` to another.
+     *
+     * Aggregates queue information by adding the counts (e.g., number of messages, buffers, total bytes) from
+     * @p aOther to the corresponding counts in @p aInfo.
+     *
+     * @param[in,out] aInfo    A queue `Info` to update.
+     * @param[in]     aOther   A queue `Info` to add to @p aInfo.
+     */
+    static void AddQueueInfos(Info &aInfo, const Info &aOther);
+
     // The following methods are intended to support range-based `for`
     // loop iteration over the queue entries and should not be used
     // directly. The range-based `for` works correctly even if the

src/core/instance/instance.cpp

@@ -489,27 +489,23 @@ void Instance::GetBufferInfo(BufferInfo &aInfo)
     aInfo.mFreeBuffers    = Get<MessagePool>().GetFreeBufferCount();
     aInfo.mMaxUsedBuffers = Get<MessagePool>().GetMaxUsedBufferCount();
 
-    Get<MeshForwarder>().GetSendQueue().GetInfo(aInfo.m6loSendQueue);
-    Get<MeshForwarder>().GetReassemblyQueue().GetInfo(aInfo.m6loReassemblyQueue);
-    Get<Ip6::Ip6>().GetSendQueue().GetInfo(aInfo.mIp6Queue);
+    Get<MeshForwarder>().GetQueueInfo(aInfo.m6loSendQueue, aInfo.m6loReassemblyQueue);
+    Get<Ip6::Ip6>().GetSendQueueInfo(aInfo.mIp6Queue);
 
 #if OPENTHREAD_FTD
-    Get<Ip6::Mpl>().GetBufferedMessageSet().GetInfo(aInfo.mMplQueue);
+    Get<Ip6::Mpl>().GetBufferedMessageSetInfo(aInfo.mMplQueue);
 #endif
 
-    Get<Mle::MleRouter>().GetMessageQueue().GetInfo(aInfo.mMleQueue);
+    Get<Mle::MleRouter>().GetMessageQueueInfo(aInfo.mMleQueue);
 
-    Get<Tmf::Agent>().GetRequestMessages().GetInfo(aInfo.mCoapQueue);
-    Get<Tmf::Agent>().GetCachedResponses().GetInfo(aInfo.mCoapQueue);
+    Get<Tmf::Agent>().GetRequestAndCachedResponsesQueueInfo(aInfo.mCoapQueue);
 
 #if OPENTHREAD_CONFIG_SECURE_TRANSPORT_ENABLE
-    Get<Tmf::SecureAgent>().GetRequestMessages().GetInfo(aInfo.mCoapSecureQueue);
-    Get<Tmf::SecureAgent>().GetCachedResponses().GetInfo(aInfo.mCoapSecureQueue);
+    Get<Tmf::SecureAgent>().GetRequestAndCachedResponsesQueueInfo(aInfo.mCoapSecureQueue);
 #endif
 
 #if OPENTHREAD_CONFIG_COAP_API_ENABLE
-    Get<Coap::ApplicationCoap>().GetRequestMessages().GetInfo(aInfo.mApplicationCoapQueue);
-    Get<Coap::ApplicationCoap>().GetCachedResponses().GetInfo(aInfo.mApplicationCoapQueue);
+    Get<Coap::ApplicationCoap>().GetRequestAndCachedResponsesQueueInfo(aInfo.mApplicationCoapQueue);
 #endif
 }
 

src/core/net/ip6.hpp

@@ -269,11 +269,11 @@ public:
     const Address *SelectSourceAddress(const Address &aDestination) const;
 
     /**
-     * Returns a reference to the send queue.
+     * Retrieves information about the IPv6 send queue.
      *
-     * @returns A reference to the send queue.
+     * @param[out] aQueueInfo     A `PriorityQueue::Info` to populate with info about the send queue.
      */
-    const PriorityQueue &GetSendQueue(void) const { return mSendQueue; }
+    void GetSendQueueInfo(PriorityQueue::Info &aQueueInfo) const { mSendQueue.GetInfo(aQueueInfo); }
 
     /**
      * Converts an IP protocol number to a string.

src/core/net/ip6_mpl.hpp

@@ -189,11 +189,11 @@ public:
 
 #if OPENTHREAD_FTD
     /**
-     * Returns a reference to the buffered message set.
+     * Retrieves information about the message queue containing buffered message set.
      *
-     * @returns A reference to the buffered message set.
+     * @param[out] aQueueInfo    A `MessageQueue::Info` to populate with info about the queue.
      */
-    const MessageQueue &GetBufferedMessageSet(void) const { return mBufferedMessageSet; }
+    void GetBufferedMessageSetInfo(MessageQueue::Info &aQueueInfo) { mBufferedMessageSet.GetInfo(aQueueInfo); }
 #endif
 
 private:

src/core/thread/mesh_forwarder.hpp

@@ -251,18 +251,18 @@ public:
     Error EvictMessage(Message::Priority aPriority);
 
     /**
-     * Returns a reference to the send queue.
+     * Retrieves information about the send queue and the reassembly queue.
      *
-     * @returns  A reference to the send queue.
-     */
-    const PriorityQueue &GetSendQueue(void) const { return mSendQueue; }
-
-    /**
-     * Returns a reference to the reassembly queue.
+     * Provides details such as the number of messages and data buffers currently utilized by the priority send queue
+     * and the message reassembly queue.
      *
-     * @returns  A reference to the reassembly queue.
+     * @param[out] aSendQueueInfo         A `PriorityQueue::Info` to populate with info about the send queue.
+     * @param[out] aReassemblyQueueInfo   A `MessageQueue::Info` to populate with info about the reassembly queue.
      */
-    const MessageQueue &GetReassemblyQueue(void) const { return mReassemblyList; }
+    void GetQueueInfo(PriorityQueue::Info &aSendQueueInfo, MessageQueue::Info &aReassemblyQueueInfo) const
+    {
+        mSendQueue.GetInfo(aSendQueueInfo), mReassemblyList.GetInfo(aReassemblyQueueInfo);
+    }
 
     /**
      * Returns a reference to the IP level counters.

src/core/thread/mle.hpp

@@ -587,11 +587,11 @@ public:
     const LeaderData &GetLeaderData(void);
 
     /**
-     * Returns a reference to the send queue.
+     * Retrieves information about the MLE message queue used for delayed messages.
      *
-     * @returns A reference to the send queue.
+     * @param[out] aQueueInfo     A `MessageQueue::Info` to populate with info about the MLE queue.
      */
-    const MessageQueue &GetMessageQueue(void) const { return mDelayedSender.GetQueue(); }
+    void GetMessageQueueInfo(MessageQueue::Info &aQueryInfo) const { mDelayedSender.GetQueueInfo(aQueryInfo); }
 
     /**
      * Gets the MLE counters.
@@ -1161,8 +1161,8 @@ private:
 #endif
         void RemoveScheduledChildUpdateRequestToParent(void);
 
-        void                HandleTimer(void);
-        const MessageQueue &GetQueue(void) const { return mSchedules; }
+        void HandleTimer(void);
+        void GetQueueInfo(MessageQueue::Info &aQueueInfo) const { mSchedules.GetInfo(aQueueInfo); }
 
     private:
         typedef Message Schedule;