The Internal Contract: Mandatory Locking and the TxSendStatus Record

[!NOTE] Technical Context: private_broadcast.h | Lines 190-196

In lines 190 through 196 of private_broadcast.h, we encounter a significant shift in the Thread-Safety Contract. This block defines the GetSendStatusByNode method and introduces the TxSendStatus structure, which serves as the "Master Record" for an individual transaction's private broadcast history.

1. Mandatory Locking: EXCLUSIVE_LOCKS_REQUIRED(m_mutex)

Line 192 contains a subtle but critical difference from the public methods we have seen: EXCLUSIVE_LOCKS_REQUIRED(m_mutex); (Note the absence of the ! symbol).

What does this mean for the Developer?

While the public methods (like Add) expected the lock to Not be held upon entry (because they handle the locking themselves), this internal method Requires that the caller has already acquired the lock.

This is a "Protected Internal Method." It is designed to be called by other methods within the class that are already doing complex, multi-step operations. By requiring the lock to be held, the architect ensures that the entire sequence of operations is "Atomic"—meaning it happens as a single, uninterrupted block. This prevents "Partial State" bugs, where one thread sees the node ID but another thread deletes the transaction before the first thread can finish its work.

2. GetSendStatusByNode: The Internal Tracker

The method returns std::optional<TxAndSendStatusForNode>. This is the convenience type we discussed in Part 023.

This is the "Search Engine" of the class. Given a nodeid, it scans the internal memory to find if there is an active broadcast for that node. If it finds one, it returns a reference to the transaction and its status. If not, it returns nullopt. This is the core logic that allows the node to "Remember" its peer relationships.

3. struct TxSendStatus: The Master Transaction Record

Line 193 introduces the TxSendStatus struct. This is the "Container" that holds everything the node knows about a single transaction's broadcast effort.

4. time_added: The Record of Creation

Line 194 initializes the time_added field:

Copy

const NodeClock::time_point time_added{NodeClock::now()};

This is a Default Initializer. In C++, this ensures that every time a new TxSendStatus object is created, it automatically records the current time of the node.

The Immutability of Creation

By making this const, the architect ensures that the "Time of Addition" can never be changed. This is the "Anchor" for the 5-minute stale timer. It allows the node to answer the question: "How long has this transaction been in my queue?" with absolute, unforgeable accuracy.

5. std::vector<SendStatus> send_statuses: The Peer Collection

Line 195 contains the heart of the record: a vector of SendStatus objects.

This is the "Roster" of everyone who is supposed to receive this transaction. Each item in this vector tracks a different peer. This allows the transaction to be "Multi-Homed"—it can be traveling to three different peers simultaneously, each at a different stage of the confirmation handshake. This "Vector of Statuses" is what gives the PrivateBroadcast class its robustness—if two peers fail, the third one might still succeed.

Conclusion: The Structure of Accountability

Lines 190-196 represent the "Accounting Layer" of the system. We have a strict contract for thread-safety (the mandatory lock) and a robust, time-stamped record for every transaction (TxSendStatus). This is the infrastructure that allows the node to manage its private broadcasts with the same level of accountability as its public blockchain validation.

In the final articles of this batch (0029-0030), we will reveal the m_mutex and the m_transactions map that physically hold these records in the node's memory.