Controller：EOS区块链核心控制器

FC_REFLECT( eosio::chain::controller::config,
    (actor_whitelist) // 账户集合，作为actor白名单
    (actor_blacklist) // 账户集合，作为actor黑名单
    (contract_whitelist) // 账户集合，作为合约白名单
    (contract_blacklist) // 账户集合，作为合约黑名单
    (blocks_dir) // 存储区块数据的目录名字，有默认值为"blocks"
    (state_dir) // 存储状态数据的目录名字，有默认值为"state"
    (state_size) // 状态数据的大小，有默认值为1GB
    (reversible_cache_size) // 可逆去快数据的缓存大小，有默认值为340MB
    (read_only) // 是否只读，默认为false。
    (force_all_checks) // 是否强制执行所有检查，默认为false。
    (disable_replay_opts) // 是否禁止重播参数，默认为false。
    (contracts_console) // 是否允许合约输出到控制台，一般为了调试合约使用，默认为false。
    (genesis) // eosio::chain::genesis_state结构体的实例，包含了创世块的初始化配置内容。
    (wasm_runtime) // 运行时webassembly虚拟机的类型，默认值为eosio::chain::wasm_interface::vm_type::wabt
    (resource_greylist) // 账户集合，是资源灰名单。
    (trusted_producers) // 账户集合，为可信生产者。
)

flat_set< pair<account_name, action_name> > action_blacklist; // 账户和action组成一个二元组作为元素的集合，储存了action的黑名单
flat_set<public_key_type> key_blacklist; // 公钥集合，公钥黑名单
uint64_t                 state_guard_size       =  chain::config::default_state_guard_size; // 状态守卫大小，默认为128MB
uint64_t                 reversible_guard_size  =  chain::config::default_reversible_guard_size; // 可逆区块守卫大小，默认为2MB
bool                     allow_ram_billing_in_notify = false; // 是否允许内存账单通知，默认为false。
db_read_mode             read_mode              = db_read_mode::SPECULATIVE; // db只读模式，默认为SPECULATIVE
validation_mode          block_validation_mode  = validation_mode::FULL; // 区块校验模式，默认为FULL

controller_impl( const controller::config& cfg, controller& s  )
   :self(s),
    db( cfg.state_dir,
        cfg.read_only ? database::read_only : database::read_write,
        cfg.state_size ),
    reversible_blocks( cfg.blocks_dir/config::reversible_blocks_dir_name,
        cfg.read_only ? database::read_only : database::read_write,
        cfg.reversible_cache_size ),
    blog( cfg.blocks_dir ),
    fork_db( cfg.state_dir ), // 调用fork_db构造器，传入一个文件路径。
    wasmif( cfg.wasm_runtime ),
    resource_limits( db ),
    authorization( s, db ),
    conf( cfg ),
    chain_id( cfg.genesis.compute_chain_id() ),
    read_mode( cfg.read_mode )

fork_database::fork_database( const fc::path& data_dir ):my( new fork_database_impl() ) {
  my->datadir = data_dir;

  if (!fc::is_directory(my->datadir))
     fc::create_directories(my->datadir);

  auto fork_db_dat = my->datadir / config::forkdb_filename; // 在该目录下创建一个文件forkdb.dat
  if( fc::exists( fork_db_dat ) ) { // 如果该文件已存在
     string content;
     fc::read_file_contents( fork_db_dat, content ); // 将其读到内存中

     fc::datastream<const char*> ds( content.data(), content.size() );
     unsigned_int size; fc::raw::unpack( ds, size ); // 按照区块结构解析
     for( uint32_t i = 0, n = size.value; i < n; ++i ) { // 遍历所有区块
        block_state s;
        fc::raw::unpack( ds, s );
        set( std::make_shared<block_state>( move( s ) ) ); // 逐一插入到数据库fork_database中
     }
     block_id_type head_id;
     fc::raw::unpack( ds, head_id );

     my->head = get_block( head_id ); // 处理fork_database的头区块数据

     fc::remove( fork_db_dat ); // 删除持久化文件forkdb.dat。
  }
}

fork_db.irreversible.connect( [&]( auto b ) {
                                 on_irreversible(b);
                                 });

auto itr = my->index.find( h->id ); // h是prune入参，const block_state_ptr& h
if( itr != my->index.end() ) {
    irreversible(*itr);
    my->index.erase(itr);
}

...
    fork_db.mark_in_current_chain(head, true);
    fork_db.set_validity(head, true);
}
emit(self.irreversible_block, s);

void controller::commit_block() {
   validate_db_available_size(); // 校验db数据库的大小
   validate_reversible_available_size(); // 校验reversible数据库的大小
   my->commit_block(true); // 调用controller_impl结构体中的的commit_block函数，并且传入true
}

if (add_to_fork_db) {
    pending->_pending_block_state->validated = true; // 将pending区块对象的状态属性validated置为true，标记已校验。
    auto new_bsp = fork_db.add(pending->_pending_block_state); // 将pending区块添加至fork_db。
    emit(self.accepted_block_header, pending->_pending_block_state); // 发射controller的accepted_block_header信号，携带pending区块状态对象。
    head = fork_db.head(); // 将当前节点的头块设置为fork_db的头块。
    // 校验pending区块是否最终成功同时变为fork_db以及主节点的头块。
    EOS_ASSERT(new_bsp == head, fork_database_exception, "committed block did not become the new head in fork database");
 }

if ( read_mode != db_read_mode::IRREVERSIBLE ) { // 在db读取模式不等于IRREVERSIBLE时，要调用maybe_switch_forks函数。
    maybe_switch_forks( s );
}

apply_block( new_head->block, s ); // 将新块应用到主库中去。
fork_db.mark_in_current_chain( new_head, true ); // 在fork_db中将新块的属性in_current_chain标记为true。
fork_db.set_validity( new_head, true ); // 在fork_db中将新块的属性validity标记为true。
head = new_head; // 更新节点主库的头块为当前块。

my->fork_db.close();

void fork_database::close() {
  if( my->index.size() == 0 ) return;
  auto fork_db_dat = my->datadir / config::forkdb_filename;
  // 获取文件输出流。
  std::ofstream out( fork_db_dat.generic_string().c_str(), std::ios::out | std::ios::binary | std::ofstream::trunc );
  uint32_t num_blocks_in_fork_db = my->index.size();
  // 将当前fork_db的区块数据打包到输出流，持久化到fork_db.dat文件中。
  fc::raw::pack( out, unsigned_int{num_blocks_in_fork_db} );
  for( const auto& s : my->index ) {
     fc::raw::pack( out, *s );
  }
  if( my->head )
     fc::raw::pack( out, my->head->id );
  else
     fc::raw::pack( out, block_id_type() );

  // 通常头块不是不可逆的。如果fork_db中只剩一个块就是头块，一般不会将它删除因为下一个区块需要从头块建立。不过可以在退出之前将这个区块作为不可逆区块从fork_db中删除。
  auto lib    = my->head->dpos_irreversible_blocknum;
  auto oldest = *my->index.get<by_block_num>().begin();
  if( oldest->block_num <= lib ) {
     prune( oldest );
  }

  my->index.clear();
}

my->head = my->fork_db.head();

void controller::startup( const snapshot_reader_ptr& snapshot ) {
   my->head = my->fork_db.head(); // 将fork_db的头块设置为状态主库头块
   if( !my->head ) { // 如果状态主库头块为空，则说明fork_db没有数据，可能需要重播block_log生成这些数据。
      elog( "No head block in fork db, perhaps we need to replay" );
   }
   my->init(snapshot); // 根据startup的入参snapshot调用controller_impl的初始化函数init。
}

void init(const snapshot_reader_ptr& snapshot) {
  if (snapshot) { // 如果入参snapshot不为空
     EOS_ASSERT(!head, fork_database_exception, "");//快照存在而状态主库头块不存在是个异常状态。
     snapshot->validate();// 校验快照
     read_from_snapshot(snapshot);// 执行read_from_snapshot函数
     auto end = blog.read_head();// 从日志文件中获取不可逆区块头块。
     if( !end ) {// 如果不可逆区块头块为空，重置日志文件，清除所有数据，重新初始化block_log状态。
        blog.reset(conf.genesis, signed_block_ptr(), head->block_num + 1);
     } else if ( end->block_num() > head->block_num) {// 如果不可逆区块头块号大于状态主库头块号。
        replay();// 状态库的数据与真实数据不同步，版本过旧，需要重播修复状态主库数据。
     } else {
        // 校验提示报错：区块日志提供了快照，但不包含主库头块号
        EOS_ASSERT(end->block_num() == head->block_num, fork_database_exception,
                   "Block log is provided with snapshot but does not contain the head block from the snapshot");
     }
  } else if( !head ) {如果入参snapshot为空且状态主库的头块也不存在，说明状态库完全是空的。
     initialize_fork_db(); // 重新初始化fork_db
     auto end = blog.read_head();// 读取区块日志中的不可逆区块头块。
     if( end && end->block_num() > 1 ) {// 如果头块存在且头块号大于1
        replay();// 重播生成状态库。
     } else if( !end ) {// 如果头块不存在
        blog.reset( conf.genesis, head->block );// 重置日志文件，清除所有数据，重新初始化block_log状态。
     }
  }
  ...
  if( snapshot ) {//快照存在，计算完整hash值。通过sha256算法计算，将结果写入快照，同时将结果打印到控制台。
     const auto hash = calculate_integrity_hash();
     ilog( "database initialized with hash: ${hash}", ("hash", hash) );
  }
}

void read_from_snapshot( const snapshot_reader_ptr& snapshot ) {
  snapshot->read_section<chain_snapshot_header>([this]( auto &section ){
     chain_snapshot_header header;
     section.read_row(header, db);
     header.validate();
  });// 先读取快照头数据。
  snapshot->read_section<block_state>([this]( auto &section ){
     block_header_state head_header_state;
     section.read_row(head_header_state, db);// 读取区块头状态数据
     auto head_state = std::make_shared<block_state>(head_header_state);
     // 对fork_db的设置。
     fork_db.set(head_state);
     fork_db.set_validity(head_state, true);
     fork_db.mark_in_current_chain(head_state, true);
     head = head_state;
     snapshot_head_block = head->block_num;// 设置快照的头块号为主库头块号
  });
  controller_index_set::walk_indices([this, &snapshot]( auto utils ){
     using value_t = typename decltype(utils)::index_t::value_type;
     // 跳过table_id_object(内联的合同表格部分)
     if (std::is_same<value_t, table_id_object>::value) {
        return;
     }
     snapshot->read_section<value_t>([this]( auto& section ) {//按照value_t类型读取快照到section
        bool more = !section.empty();
        while(more) {// 循环读取section内容，知道全部读取完毕。
           decltype(utils)::create(db, [this, &section, &more]( auto &row ) {
              more = section.read_row(row, db);// 按行读取数据，回调逐行写入主库。
           });
        }
     });
  });
  read_contract_tables_from_snapshot(snapshot);//从快照中同步合约数据
  authorization.read_from_snapshot(snapshot);//从快照中同步认证数据
  resource_limits.read_from_snapshot(snapshot);//从快照中同步资源限制数据

  db.set_revision( head->block_num );// 更新头块
}

if (my->snapshot_path) {
 auto infile = std::ifstream(my->snapshot_path->generic_string(), (std::ios::in | std::ios::binary));
 auto reader = std::make_shared<istream_snapshot_reader>(infile);
 my->chain->startup(reader);// 带上该快照文件启动链。
 infile.close();
} 

void controller::write_snapshot( const snapshot_writer_ptr& snapshot ) const {
   // 写入快照时，不允许存在pending区块。
   EOS_ASSERT( !my->pending, block_validate_exception, "cannot take a consistent snapshot with a pending block" );
   return my->add_to_snapshot(snapshot);
}

void add_to_snapshot( const snapshot_writer_ptr& snapshot ) const {
  snapshot->write_section<chain_snapshot_header>([this]( auto &section ){
     section.add_row(chain_snapshot_header(), db);// 向快照中写入快照头数据
  });
  snapshot->write_section<genesis_state>([this]( auto &section ){
     section.add_row(conf.genesis, db);// 向快照中写入创世块数据
  });
  snapshot->write_section<block_state>([this]( auto &section ){
     section.template add_row<block_header_state>(*fork_db.head(), db);// 向快照中写入头块区块头数据。
  });
  controller_index_set::walk_indices([this, &snapshot]( auto utils ){
     using value_t = typename decltype(utils)::index_t::value_type;
     if (std::is_same<value_t, table_id_object>::value) {// 跳过table_id_object(内联的合同表格部分)
        return;
     }
     snapshot->write_section<value_t>([this]( auto& section ){ // 遍历主库db区块。
        decltype(utils)::walk(db, [this, &section]( const auto &row ) {
           section.add_row(row, db); // 向快照中逐行写入快照
        });
     });
  });

  add_contract_tables_to_snapshot(snapshot);// 向快照中写入合约数据
  authorization.add_to_snapshot(snapshot);// 向快照中写入认证数据
  resource_limits.add_to_snapshot(snapshot);// 向快照中写入资源限制数据
}

producer_plugin::snapshot_information producer_plugin::create_snapshot() const {
   chain::controller& chain = app().get_plugin<chain_plugin>().chain();// 获取chain_plugin的插件实例
   auto reschedule = fc::make_scoped_exit([this](){// 获取生产者出块计划
      my->schedule_production_loop();
   });
   if (chain.pending_block_state()) {// 快照大忌：如果有pending块，不可生成快照。
      // abort the pending block
      chain.abort_block();// 将pending块干掉
   } else {
      reschedule.cancel();// 无pending块，则取消出块计划。
   }
   // 开始写快照。
   auto head_id = chain.head_block_id();
   // 快照目录：可通过配置producer_plugin的snapshots-dir项来指定快照目录，会在节点数据目录下生成该快照目录，如果未特殊指定，默认目录名字为“snapshots”
   // 在快照目录下生成格式为“snapshot-${id}.bin”的快照文件。id是当前链的头块id
   std::string snapshot_path = (my->_snapshots_dir / fc::format_string("snapshot-${id}.bin", fc::mutable_variant_object()("id", head_id))).generic_string();

   EOS_ASSERT( !fc::is_regular_file(snapshot_path), snapshot_exists_exception,
               "snapshot named ${name} already exists", ("name", snapshot_path));

   auto snap_out = std::ofstream(snapshot_path, (std::ios::out | std::ios::binary));// 构造快照文件输出流
   auto writer = std::make_shared<ostream_snapshot_writer>(snap_out);// 构造快照写入器
   chain.write_snapshot(writer);// 备份当前链写入快照
   // 资源释放。
   writer->finalize();
   snap_out.flush();
   snap_out.close();

   return {head_id, snapshot_path};// 返回快照文件路径
}