Go-ethereum 原始碼解析之 go-ethereum/ethdb/database.go

---

Source code

// Copyright 2017 The go-ethereum Authors
// This file is part of the go-ethereum library.
//
// The go-ethereum library is free software: you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// The go-ethereum library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.

---

Appendix A. 總體批註

實現了底層資料庫 LevelDB 的抽象層 LDBDatabase，用於生產環境。

ethdb.LDBDatabase 實現了介面 ethdb.Database，並且將實際的操作轉發給 LevelDB 的介面。同時，基於 metrics.Meter 測試各操作的效能。

ethdb.ldbBatch 在 ethdb.LDBDatabase 的基礎上提供了批處理能力。

暫時不深入與效能相關的實現 metrics.Meter。

---

Appendix B. 詳細批註

1. const

• writePauseWarningThrottler = 1 * time.Minute： ??? 效能相關指標

2. var

• var OpenFileLimit = 64： ??? LevelDB 一次能開啟的檔案數量上限？

3. type LDBDatabase struct

資料結構 LDBDatabase 實現了介面 ethdb.Database，並且將實際的操作轉發給 LevelDB 的介面。同時，基於 metrics.Meter 測試各操作的效能。

• fn string： 檔名。??? 幹什麼的檔名呢？

• db *leveldb.DB： LevelDB 例項

• compTimeMeter metrics.Meter // Meter for measuring the total time spent in database compaction

• compReadMeter metrics.Meter // Meter for measuring the data read during compaction

• compWriteMeter metrics.Meter // Meter for measuring the data written during compaction

• writeDelayNMeter metrics.Meter // Meter for measuring the write delay number due to database compaction

• writeDelayMeter metrics.Meter // Meter for measuring the write delay duration due to database compaction

• diskReadMeter metrics.Meter // Meter for measuring the effective amount of data read

• diskWriteMeter metrics.Meter // Meter for measuring the effective amount of data written

• quitLock sync.Mutex // Mutex protecting the quit channel access

• quitChan chan chan error // Quit channel to stop the metrics collection before closing the database

• log log.Logger // Contextual logger tracking the database path

3.1 func NewLDBDatabase(file string, cache int, handles int) (*LDBDatabase, error)

建構函式 NewLDBDatabase() 建立 LDBDatabase 的一個例項，該例項是 LevelDB 的包裝器。

引數：

• file string： 檔名
• cache int： ??? 快取？
• handles int： ??? 處理器？

返回值：

• LDBDatabase 例項
• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 構建日誌器 logger

  • logger := log.New("database", file)

• 調整 cache，確保其最小值為 16

• 調整 handles，確保其最小值為 16

• 輸出日誌資訊：logger.Info("Allocated cache and file handles", "cache", cache, "handles", handles)

• 開啟 LevelDB，並從可能的錯誤恢復

  • db, err := leveldb.OpenFile(file, ...)
  • corrupted := err.(*errors.ErrCorrupted)
  • db, err = leveldb.RecoverFile(file, nil)

• 如果 err 不為 nil，則直接退出

  • return nil, err

• 構建 LDBDatabase 的例項並返回

  • return &LDBDatabase{fn: file, db: db, log: logger}, nil

注意，這裡並沒有初始化任何效能計時器。

3.2 func (db *LDBDatabase) Path() string

方法 Path() 返回資料庫目錄的路徑。

3.3 func (db *LDBDatabase) Put(key []byte, value []byte) error

方法 Put() 實現了介面 ethdb.Putter 和介面 ethdb.Database，將 key & value 寫入資料庫。

引數：

• key []byte： key
• value []byte： value

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 轉發給 LevelDB 的方法 Put()
  • return db.db.Put(key, value, nil)

3.4 func (db *LDBDatabase) Has(key []byte) (bool, error)

方法 Has() 實現了介面 ethdb.Database，查詢給定的 key 是否存在於資料庫。

引數：

• key []byte： key

返回值：

• 存在返回 true，否則返回 false
• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 轉發給 LevelDB 的方法 Has()
  • return db.db.Has(key, nil)

3.5 func (db *LDBDatabase) Get(key []byte) ([]byte, error)

方法 Get() 實現了介面 ethdb.Database，從資料庫中獲取給定 key 對應的 value。

引數：

• key []byte： key

返回值：

• 存在返回 key 對應的 value
• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 轉發給 LevelDB 的方法 Get()
  • dat, err := db.db.Get(key, nil)

3.6 func (db *LDBDatabase) Delete(key []byte) error

方法 Delete() 實現了介面 ethdb.Database，從資料庫中刪除指定的 key。

引數：

• key []byte： key

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 轉發給 LevelDB 的方法 Delete()
  • return db.db.Delete(key, nil)

3.7 func (db *LDBDatabase) NewIterator() iterator.Iterator

方法 NewIterator() 返回 LevelDB 的迭代器 iterator.Iterator。

返回值：

• LevelDB 的迭代器 iterator.Iterator

主要實現：

• return db.db.NewIterator(nil, nil)

3.8 func (db *LDBDatabase) NewIteratorWithPrefix(prefix []byte) iterator.Iterator

方法 NewIteratorWithPrefix() 返回 LevelDB 的迭代器 iterator.Iterator，這個迭代器指向具有指定字首的資料庫子集。

引數：

• prefix []byte： 字首

返回值：

• LevelDB 的迭代器 iterator.Iterator

主要實現：

• return db.db.NewIterator(util.BytesPrefix(prefix), nil)

3.9 func (db *LDBDatabase) Close()

方法 Close() 實現了介面 ethdb.Database。

主要實現：

• ??? 停止效能指標器
• 將實際的關閉操作轉發給 LevelDB 的方法 Close()
  • err := db.db.Close()
  • 如果 err == nil
    • db.log.Info("Database closed")
  • 否則
    • db.log.Error("Failed to close database", "err", err)

3.10 func (db *LDBDatabase) LDB() *leveldb.DB

方法 LDB() 返回 LDBDatabase 中的底層 LevelDB 資料庫。

返回值：

• LDBDatabase 中的底層 LevelDB 資料庫。

主要實現：

• return db.db

3.11 func (db *LDBDatabase) Meter(prefix string)

效能指標相關內容，暫時不關注。

3.12 func (db *LDBDatabase) meter(refresh time.Duration)

效能指標相關內容，暫時不關注。

3.13 func (db *LDBDatabase) NewBatch() Batch

方法 NewBatch() 返回批處理器。

返回值：

• 批處理器 ldbBatch

主要實現：

• return &ldbBatch{db: db.db, b: new(leveldb.Batch)}

4. type ldbBatch struct

資料結構 ldbBatch 在 LevelDB 的基礎上提供批處理能力。

• db *leveldb.DB： 底層的 LevelDB
• b *leveldb.Batch： LevelDB 的批處理器
• size int： 位元組數

4.1 func (b *ldbBatch) Put(key, value []byte) error

方法 Put() 實現了介面 ethdb.Putter 和介面 ethdb.Batch，將 key & value 寫入資料庫。

引數：

• key []byte： key
• value []byte： value

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 轉發給 leveldb.Batch 的方法 Put()
  • b.b.Put(key, value)
• 更新位元組數
  • b.size += len(value)

4.2 func (b *ldbBatch) Delete(key []byte) error

方法 Delete() 實現了介面 ethdb.Deleter 和介面 ethdb.Batch，從資料庫中刪除指定的 key。

引數：

• key []byte： key

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 轉發給 leveldb.Batch 的方法 Delete()
  • b.b.Delete(key)
• 更新位元組數
  • b.size += 1

4.3 func (b *ldbBatch) Write() error

方法 Write() 實現了介面 ethdb.Batch，將批量資料一次性寫入資料庫。

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• return b.db.Write(b.b, nil)

4.4 func (b *ldbBatch) ValueSize() int

方法 ValueSize() 實現了介面 ethdb.Batch，返回批量位元組數。

返回值：

• 批量位元組數

主要實現：

• return b.size

4.5 func (b *ldbBatch) Reset()

方法 Reset() 實現了介面 ethdb.Batch，重置資料庫。

主要實現：

• 轉發給 leveldb.Batch 的方法 Reset()
  • b.b.Reset()
• 更新位元組數
  • b.size = 0

5. type table struct

資料結構 table 封裝了資料庫 Database，描述 Database 中的 key 具有相同的字首 prefix。

• db Database： 資料庫
• prefix string： 字首

5.1 func NewTable(db Database, prefix string) Database

建構函式 NewTable() 建立資料庫，同時資料庫中的 key 具有相同的字首 prefix。

引數：

• db Database： 資料庫
• prefix string： 字首

返回值：

• 資料庫

主要實現：

• return &table{db: db, prefix: prefix,}

5.2 func (dt *table) Put(key []byte, value []byte) error

方法 Put() 實現了介面 ethdb.Putter 和介面 ethdb.Database。

引數：

• key []byte： key
• value []byte： value

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 給 key 加上字首 prefix，同時轉發給 Database 的方法 Put()
  • dt.db.Put(append([]byte(dt.prefix), key...), value)

5.3 func (dt *table) Has(key []byte) (bool, error)

方法 Has() 實現了介面 ethdb.Database。

引數：

• key []byte： key

返回值：

• 存在返回 true，否則返回 false
• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 給 key 加上字首 prefix，同時轉發給 Database 的方法 Has()
  • dt.db.Has(append([]byte(dt.prefix), key...))

5.4 func (dt *table) Get(key []byte) ([]byte, error)

方法 Get() 實現了介面 ethdb.Database。

引數：

• key []byte： key

返回值：

• 存在返回 key 對應的 value
• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 給 key 加上字首 prefix，同時轉發給 Database 的方法 Get()
  • dt.db.Get(append([]byte(dt.prefix), key...))

5.5 func (dt *table) Delete(key []byte) error

方法 Delete() 實現了介面 ethdb.Deleter 和介面 ethdb.Database。

引數：

• key []byte： key

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 給 key 加上字首 prefix，同時轉發給 Database 的方法 Delete()
  • dt.db.Delete(append([]byte(dt.prefix), key...))

5.6 func (dt *table) Close()

方法 Close() 不執行任何操作。注意，這裡並不會關閉底層資料庫。

5.7 func (dt *table) NewBatch() Batch

方法 NewBatch() 返回具有批處理能力的 ethdb.table。

返回值：

• 具有批處理能力的 ethdb.tableBatch

主要實現：

• return &tableBatch{dt.db.NewBatch(), dt.prefix}

6. type tableBatch struct

資料結構 tableBatch 封裝了資料庫 Database，描述 Database 中的 key 具有相同的字首 prefix。同時，提供批處理能力。

• batch Batch： 批處理
• prefix string： 字首

6.1 func NewTableBatch(db Database, prefix string) Batch

建構函式 NewTableBatch() 建立具有批處理能力的資料庫，同時資料庫中的 key 具有相同的字首 prefix。

引數：

• db Database： 資料庫
• prefix string： 字首

返回值：

• 具有批處理能力資料庫

主要實現：

• return &tableBatch{db.NewBatch(), prefix}

6.2 func (tb *tableBatch) Put(key, value []byte) error

方法 Put() 實現了介面 ethdb.Putter 和介面 ethdb.Batch，將 key & value 插入資料庫。

引數：

• key []byte： key
• value []byte： value

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 給 key 加上字首 prefix，同時轉發給 ethdb.Batch 的方法 Put()
  • return tb.batch.Put(append([]byte(tb.prefix), key...), value)

6.3 func (tb *tableBatch) Delete(key []byte) error

方法 Delete() 實現了介面 ethdb.Deleter 和介面 ethdb.Batch，從資料庫中刪除給定的 key。

引數：

• key []byte： key

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 給 key 加上字首 prefix，同時轉發給 ethdb.Batch 的方法 Delete()
  • return tb.batch.Delete(append([]byte(tb.prefix), key...))

6.4 func (tb *tableBatch) Write() error

方法 Write() 實現了介面 ethdb.Batch，將批處理資料一次性寫入資料庫。

返回值：

• 出錯返回錯誤訊息 error，否則返回 nil

主要實現：

• 轉發給 ethdb.Batch 的方法 Write()
  • return tb.batch.Write()

6.5 func (tb *tableBatch) ValueSize() int

方法 ValueSize() 實現了介面 ethdb.Batch，返回批處理資料的位元組數。

返回值：

• 批處理資料位元組數

主要實現：

• 轉發給 ethdb.Batch 的方法 ValueSize()
  • return tb.batch.ValueSize()

6.6 func (tb *tableBatch) Reset()

方法 Reset() 實現了介面 ethdb.Batch，清空批處理資料。

主要實現：

• 轉發給 ethdb.Batch 的方法 Reset()
  • tb.batch.Reset()

---

Reference

1. https://github.com/ethereum/go-ethereum/blob/master/ethdb/database.go

---

Contributor

1. Windstamp, https://github.com/windstamp