trace.go
<p>[TOC]</p>
<h3>简要描述</h3>
<p>btcd 数据组织和插桩接口，主要完成如下工作：</p>
<ul>
<li>对于每一个独立的区块同步过程，通过在多个运行阶段中，共享同一个 <code>TraceData</code> 实现对 Snapshot、Revision 等数据的组织和插桩。</li>
<li>实时地将组织好的数据通过 log 提供的接口输出。</li>
</ul>
<h3><code>TraceData</code> 数据结构</h3>
<pre><code class="language-golang">type TraceData struct {
initSnapshot *structure.Snapshot
finalSnapshot *structure.Snapshot
}</code></pre>
<h3>方法接口列表</h3>
<ul>
<li><code>func (data *TraceData) SetInitSnapshot(targetChainID string, targetChainHeight int32, initTime time.Time, bestState *structure.BestState) error</code></li>
<li><code>func (data *TraceData) SetFinalSnapshot(finalTime time.Time, bestState *structure.BestState) error</code></li>
<li><code>func (data *TraceData) CommitRevision(revision *structure.Revision, commitTime time.Time, revisionData structure.RevisionData)</code></li>
</ul>
<h3><code>SetInitSnapshot</code> 方法接口</h3>
<h5>方法参数介绍</h5>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名</th>
<th style="text-align: left;">类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">targetChainID</td>
<td style="text-align: left;">string</td>
<td>当前区块同步过程目标的链 ID，也就是 fork height，通常为 0</td>
</tr>
<tr>
<td style="text-align: left;">targetChainHeight</td>
<td style="text-align: left;">int32</td>
<td>当前区块同步过程目标的链的高度</td>
</tr>
<tr>
<td style="text-align: left;">initTime</td>
<td style="text-align: left;">time.Time</td>
<td>当前区块同步过程的开始时间</td>
</tr>
<tr>
<td style="text-align: left;">bestState</td>
<td style="text-align: left;"><a href="https://github.com/BitTraceProject/BitTrace-Types/blob/main/pkg/structure/state.go">*structure.BestState</a></td>
<td>当前区块链系统的状态信息集合</td>
</tr>
</tbody>
</table>
<h5>返回值介绍</h5>
<ul>
<li>略过</li>
</ul>
<h5>调用逻辑</h5>
<ul>
<li>SetInitSnapshot 在一次区块同步过程的最开始被调用，通常是在 <code>Process.go</code> 中。</li>
<li>调用之后，首先会初始化 Snapshot，作为同步过程期间组织 Revision 的基础。</li>
<li>初始化完成之后，会将此时的 init Snapshpt，通过 <code>Data</code> 接口将序列化的数据尝试输出到日志中。</li>
</ul>
<h5>注意事项</h5>
<ul>
<li>init Snapshot 输出时 Revision List 是空的。</li>
</ul>
<h3><code>SetFinalSnapshot</code> 方法接口</h3>
<h5>方法参数介绍</h5>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名</th>
<th style="text-align: left;">类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">finalTime</td>
<td style="text-align: left;">time.Time</td>
<td>当前区块同步过程的结束时间</td>
</tr>
<tr>
<td style="text-align: left;">bestState</td>
<td style="text-align: left;"><a href="https://github.com/BitTraceProject/BitTrace-Types/blob/main/pkg/structure/state.go">*structure.BestState</a></td>
<td>当前区块链系统的状态信息集合</td>
</tr>
</tbody>
</table>
<h5>返回值介绍</h5>
<ul>
<li>略过</li>
</ul>
<h5>调用逻辑</h5>
<ul>
<li>SetFinalSnapshot 在一次区块同步过程的最后被调用，通常是在 <code>manager.go</code> 中。</li>
<li>调用之后，首先会 Commit Snapshot，然后会将此时的 final Snapshpt，通过 <code>Data</code> 接口将序列化的数据尝试输出到日志中。</li>
</ul>
<h5>注意事项</h5>
<ul>
<li>final Snapshot 输出时 Revision List 是满的。</li>
</ul>
<h3><code>CommitRevision</code> 方法接口</h3>
<h5>方法参数介绍</h5>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名</th>
<th style="text-align: left;">类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">revision</td>
<td style="text-align: left;"><a href="https://github.com/BitTraceProject/BitTrace-Types/blob/main/pkg/structure/revision.go">*structure.Revision</a></td>
<td>当前运行阶段数据</td>
</tr>
<tr>
<td style="text-align: left;">commitTime</td>
<td style="text-align: left;">time.Time</td>
<td>提交时间</td>
</tr>
<tr>
<td style="text-align: left;">revisionData</td>
<td style="text-align: left;"><a href="https://github.com/BitTraceProject/BitTrace-Types/blob/main/pkg/structure/revision.go">structure.RevisionData</a></td>
<td>关联的其他自定义数据</td>
</tr>
</tbody>
</table>
<h5>返回值介绍</h5>
<ul>
<li>无</li>
</ul>
<h5>调用逻辑</h5>
<ul>
<li>CommitRevision 在一次区块同步过程中会被多次调用，将 Revision 这个粒度的数据组织到 Snapshot 中。</li>
<li>调用时机是，当区块同步过程的某一运行阶段结束后，切换到下一阶段之前。</li>
</ul>
<h5>注意事项</h5>
<ul>
<li>无</li>
</ul>