go-ethereum/swarm/network/syncdb.go

// Copyright 2016 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/>.

package network

import (
	"encoding/binary"
	"fmt"

	"github.com/ethereum/go-ethereum/log"
	"github.com/ethereum/go-ethereum/swarm/storage"
	"github.com/syndtr/goleveldb/leveldb"
	"github.com/syndtr/goleveldb/leveldb/iterator"
)

const counterKeyPrefix = 0x01

/*
syncDb is a queueing service for outgoing deliveries.
One instance per priority queue for each peer

a syncDb instance maintains an in-memory buffer (of capacity bufferSize)
once its in-memory buffer is full it switches to persisting in db
and dbRead iterator iterates through the items keeping their order
once the db read catches up (there is no more items in the db) then
it switches back to in-memory buffer.

when syncdb is stopped all items in the buffer are saved to the db
*/
type syncDb struct {
	start          []byte               // this syncdb starting index in requestdb
	key            storage.Key          // remote peers address key
	counterKey     []byte               // db key to persist counter
	priority       uint                 // priotity High|Medium|Low
	buffer         chan interface{}     // incoming request channel
	db             *storage.LDBDatabase // underlying db (TODO should be interface)
	done           chan bool            // chan to signal goroutines finished quitting
	quit           chan bool            // chan to signal quitting to goroutines
	total, dbTotal int                  // counts for one session
	batch          chan chan int        // channel for batch requests
	dbBatchSize    uint                 // number of items before batch is saved
}

// constructor needs a shared request db (leveldb)
// priority is used in the index key
// uses a buffer and a leveldb for persistent storage
// bufferSize, dbBatchSize are config parameters
func newSyncDb(db *storage.LDBDatabase, key storage.Key, priority uint, bufferSize, dbBatchSize uint, deliver func(interface{}, chan bool) bool) *syncDb {
	start := make([]byte, 42)
	start[1] = byte(priorities - priority)
	copy(start[2:34], key)

	counterKey := make([]byte, 34)
	counterKey[0] = counterKeyPrefix
	copy(counterKey[1:], start[1:34])

	syncdb := &syncDb{
		start:       start,
		key:         key,
		counterKey:  counterKey,
		priority:    priority,
		buffer:      make(chan interface{}, bufferSize),
		db:          db,
		done:        make(chan bool),
		quit:        make(chan bool),
		batch:       make(chan chan int),
		dbBatchSize: dbBatchSize,
	}
	log.Trace(fmt.Sprintf("syncDb[peer: %v, priority: %v] - initialised", key.Log(), priority))

	// starts the main forever loop reading from buffer
	go syncdb.bufferRead(deliver)
	return syncdb
}

/*
bufferRead is a forever iterator loop that takes care of delivering
outgoing store requests reads from incoming buffer

its argument is the deliver function taking the item as first argument
and a quit channel as second.
Closing of this channel is supposed to abort all waiting for delivery
(typically network write)

The iteration switches between 2 modes,
* buffer mode reads the in-memory buffer and delivers the items directly
* db mode reads from the buffer and writes to the db, parallelly another
routine is started that reads from the db and delivers items

If there is buffer contention in buffer mode (slow network, high upload volume)
syncdb switches to db mode and starts dbRead
Once db backlog is delivered, it reverts back to in-memory buffer

It is automatically started when syncdb is initialised.

It saves the buffer to db upon receiving quit signal. syncDb#stop()
*/
func (self *syncDb) bufferRead(deliver func(interface{}, chan bool) bool) {
	var buffer, db chan interface{} // channels representing the two read modes
	var more bool
	var req interface{}
	var entry *syncDbEntry
	var inBatch, inDb int
	batch := new(leveldb.Batch)
	var dbSize chan int
	quit := self.quit
	counterValue := make([]byte, 8)

	// counter is used for keeping the items in order, persisted to db
	// start counter where db was at, 0 if not found
	data, err := self.db.Get(self.counterKey)
	var counter uint64
	if err == nil {
		counter = binary.BigEndian.Uint64(data)
		log.Trace(fmt.Sprintf("syncDb[%v/%v] - counter read from db at %v", self.key.Log(), self.priority, counter))
	} else {
		log.Trace(fmt.Sprintf("syncDb[%v/%v] - counter starts at %v", self.key.Log(), self.priority, counter))
	}

LOOP:
	for {
		// waiting for item next in the buffer, or quit signal or batch request
		select {
		// buffer only closes when writing to db
		case req = <-buffer:
			// deliver request : this is blocking on network write so
			// it is passed the quit channel as argument, so that it returns
			// if syncdb is stopped. In this case we need to save the item to the db
			more = deliver(req, self.quit)
			if !more {
				log.Debug(fmt.Sprintf("syncDb[%v/%v] quit: switching to db. session tally (db/total): %v/%v", self.key.Log(), self.priority, self.dbTotal, self.total))
				// received quit signal, save request currently waiting delivery
				// by switching to db mode and closing the buffer
				buffer = nil
				db = self.buffer
				close(db)
				quit = nil // needs to block the quit case in select
				break      // break from select, this item will be written to the db
			}
			self.total++
			log.Trace(fmt.Sprintf("syncDb[%v/%v] deliver (db/total): %v/%v", self.key.Log(), self.priority, self.dbTotal, self.total))
			// by the time deliver returns, there were new writes to the buffer
			// if buffer contention is detected, switch to db mode which drains
			// the buffer so no process will block on pushing store requests
			if len(buffer) == cap(buffer) {
				log.Debug(fmt.Sprintf("syncDb[%v/%v] buffer full %v: switching to db. session tally (db/total): %v/%v", self.key.Log(), self.priority, cap(buffer), self.dbTotal, self.total))
				buffer = nil
				db = self.buffer
			}
			continue LOOP

			// incoming entry to put into db
		case req, more = <-db:
			if !more {
				// only if quit is called, saved all the buffer
				binary.BigEndian.PutUint64(counterValue, counter)
				batch.Put(self.counterKey, counterValue) // persist counter in batch
				self.writeSyncBatch(batch)               // save batch
				log.Trace(fmt.Sprintf("syncDb[%v/%v] quitting: save current batch to db", self.key.Log(), self.priority))
				break LOOP
			}
			self.dbTotal++
			self.total++
			// otherwise break after select
		case dbSize = <-self.batch:
			// explicit request for batch
			if inBatch == 0 && quit != nil {
				// there was no writes since the last batch so db depleted
				// switch to buffer mode
				log.Debug(fmt.Sprintf("syncDb[%v/%v] empty db: switching to buffer", self.key.Log(), self.priority))
				db = nil
				buffer = self.buffer
				dbSize <- 0 // indicates to 'caller' that batch has been written
				inDb = 0
				continue LOOP
			}
			binary.BigEndian.PutUint64(counterValue, counter)
			batch.Put(self.counterKey, counterValue)
			log.Debug(fmt.Sprintf("syncDb[%v/%v] write batch %v/%v - %x - %x", self.key.Log(), self.priority, inBatch, counter, self.counterKey, counterValue))
			batch = self.writeSyncBatch(batch)
			dbSize <- inBatch // indicates to 'caller' that batch has been written
			inBatch = 0
			continue LOOP

			// closing syncDb#quit channel is used to signal to all goroutines to quit
		case <-quit:
			// need to save backlog, so switch to db mode
			db = self.buffer
			buffer = nil
			quit = nil
			log.Trace(fmt.Sprintf("syncDb[%v/%v] quitting: save buffer to db", self.key.Log(), self.priority))
			close(db)
			continue LOOP
		}

		// only get here if we put req into db
		entry, err = self.newSyncDbEntry(req, counter)
		if err != nil {
			log.Warn(fmt.Sprintf("syncDb[%v/%v] saving request %v (#%v/%v) failed: %v", self.key.Log(), self.priority, req, inBatch, inDb, err))
			continue LOOP
		}
		batch.Put(entry.key, entry.val)
		log.Trace(fmt.Sprintf("syncDb[%v/%v] to batch %v '%v' (#%v/%v/%v)", self.key.Log(), self.priority, req, entry, inBatch, inDb, counter))
		// if just switched to db mode and not quitting, then launch dbRead
		// in a parallel go routine to send deliveries from db
		if inDb == 0 && quit != nil {
			log.Trace(fmt.Sprintf("syncDb[%v/%v] start dbRead", self.key.Log(), self.priority))
			go self.dbRead(true, counter, deliver)
		}
		inDb++
		inBatch++
		counter++
		// need to save the batch if it gets too large (== dbBatchSize)
		if inBatch%int(self.dbBatchSize) == 0 {
			batch = self.writeSyncBatch(batch)
		}
	}
	log.Info(fmt.Sprintf("syncDb[%v:%v]: saved %v keys (saved counter at %v)", self.key.Log(), self.priority, inBatch, counter))
	close(self.done)
}

// writes the batch to the db and returns a new batch object
func (self *syncDb) writeSyncBatch(batch *leveldb.Batch) *leveldb.Batch {
	err := self.db.Write(batch)
	if err != nil {
		log.Warn(fmt.Sprintf("syncDb[%v/%v] saving batch to db failed: %v", self.key.Log(), self.priority, err))
		return batch
	}
	return new(leveldb.Batch)
}

// abstract type for db entries (TODO could be a feature of Receipts)
type syncDbEntry struct {
	key, val []byte
}

func (self syncDbEntry) String() string {
	return fmt.Sprintf("key: %x, value: %x", self.key, self.val)
}

/*
	dbRead is iterating over store requests to be sent over to the peer
	this is mainly to prevent crashes due to network output buffer contention (???)
	as well as to make syncronisation resilient to disconnects
	the messages are supposed to be sent in the p2p priority queue.

	the request DB is shared between peers, but domains for each syncdb
	are disjoint. dbkeys (42 bytes) are structured:
	* 0: 0x00 (0x01 reserved for counter key)
	* 1: priorities - priority (so that high priority can be replayed first)
	* 2-33: peers address
	* 34-41: syncdb counter to preserve order (this field is missing for the counter key)

	values (40 bytes) are:
	* 0-31: key
	* 32-39: request id

dbRead needs a boolean to indicate if on first round all the historical
record is synced. Second argument to indicate current db counter
The third is the function to apply
*/
func (self *syncDb) dbRead(useBatches bool, counter uint64, fun func(interface{}, chan bool) bool) {
	key := make([]byte, 42)
	copy(key, self.start)
	binary.BigEndian.PutUint64(key[34:], counter)
	var batches, n, cnt, total int
	var more bool
	var entry *syncDbEntry
	var it iterator.Iterator
	var del *leveldb.Batch
	batchSizes := make(chan int)

	for {
		// if useBatches is false, cnt is not set
		if useBatches {
			// this could be called before all cnt items sent out
			// so that loop is not blocking while delivering
			// only relevant if cnt is large
			select {
			case self.batch <- batchSizes:
			case <-self.quit:
				return
			}
			// wait for the write to finish and get the item count in the next batch
			cnt = <-batchSizes
			batches++
			if cnt == 0 {
				// empty
				return
			}
		}
		it = self.db.NewIterator()
		it.Seek(key)
		if !it.Valid() {
			copy(key, self.start)
			useBatches = true
			continue
		}
		del = new(leveldb.Batch)
		log.Trace(fmt.Sprintf("syncDb[%v/%v]: new iterator: %x (batch %v, count %v)", self.key.Log(), self.priority, key, batches, cnt))

		for n = 0; !useBatches || n < cnt; it.Next() {
			copy(key, it.Key())
			if len(key) == 0 || key[0] != 0 {
				copy(key, self.start)
				useBatches = true
				break
			}
			val := make([]byte, 40)
			copy(val, it.Value())
			entry = &syncDbEntry{key, val}
			// log.Trace(fmt.Sprintf("syncDb[%v/%v] - %v, batches: %v, total: %v, session total from db: %v/%v", self.key.Log(), self.priority, self.key.Log(), batches, total, self.dbTotal, self.total))
			more = fun(entry, self.quit)
			if !more {
				// quit received when waiting to deliver entry, the entry will not be deleted
				log.Trace(fmt.Sprintf("syncDb[%v/%v] batch %v quit after %v/%v items", self.key.Log(), self.priority, batches, n, cnt))
				break
			}
			// since subsequent batches of the same db session are indexed incrementally
			// deleting earlier batches can be delayed and parallelised
			// this could be batch delete when db is idle (but added complexity esp when quitting)
			del.Delete(key)
			n++
			total++
		}
		log.Debug(fmt.Sprintf("syncDb[%v/%v] - db session closed, batches: %v, total: %v, session total from db: %v/%v", self.key.Log(), self.priority, batches, total, self.dbTotal, self.total))
		self.db.Write(del) // this could be async called only when db is idle
		it.Release()
	}
}

//
func (self *syncDb) stop() {
	close(self.quit)
	<-self.done
}

// calculate a dbkey for the request, for the db to work
// see syncdb for db key structure
// polimorphic: accepted types, see syncer#addRequest
func (self *syncDb) newSyncDbEntry(req interface{}, counter uint64) (entry *syncDbEntry, err error) {
	var key storage.Key
	var chunk *storage.Chunk
	var id uint64
	var ok bool
	var sreq *storeRequestMsgData

	if key, ok = req.(storage.Key); ok {
		id = generateId()
	} else if chunk, ok = req.(*storage.Chunk); ok {
		key = chunk.Key
		id = generateId()
	} else if sreq, ok = req.(*storeRequestMsgData); ok {
		key = sreq.Key
		id = sreq.Id
	} else if entry, ok = req.(*syncDbEntry); !ok {
		return nil, fmt.Errorf("type not allowed: %v (%T)", req, req)
	}

	// order by peer > priority > seqid
	// value is request id if exists
	if entry == nil {
		dbkey := make([]byte, 42)
		dbval := make([]byte, 40)

		// encode key
		copy(dbkey[:], self.start[:34]) // db  peer
		binary.BigEndian.PutUint64(dbkey[34:], counter)
		// encode value
		copy(dbval, key[:])
		binary.BigEndian.PutUint64(dbval[32:], id)

		entry = &syncDbEntry{dbkey, dbval}
	}
	return
}